Collaboration

Assign team members to deals, leave threaded comments, request additional documents from applicants, and track a full chronological activity timeline. Collaboration endpoints let you integrate Banklyze into team workflows and build notification systems around deal progression.

Assignments

Assignments link organization users to deals with a specific role. Assigned users can be notified of deal events and filtered in deal list queries. A user may only hold one role per deal at a time — a second assignment for the same user replaces the previous role.

Assign an organization user to a deal with the specified role. If the user is already assigned to the deal, their role is updated. Emits a deal.assigned event visible in the deal timeline.

Path Parameters

Name	Type	Required	Description
deal_id	integer	Required	The unique deal ID

Request Body

Name	Type	Required	Description
user_id	integer	Required	ID of the organization user to assign
role	string	Default: reviewer	Assignment role: reviewer, underwriter, or admin

Example

curl

curl -X POST https://api.banklyze.com/v1/deals/42/assignments \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 7,
    "role": "underwriter"
  }'

Response

Response — 201 Created

{
  "deal_id": 42,
  "user_id": 7,
  "role": "underwriter",
  "assigned_at": "2026-03-04T10:15:00Z"
}

Retrieve all users currently assigned to a deal along with their roles and assignment timestamps.

Path Parameters

Name	Type	Required	Description
deal_id	integer	Required	The unique deal ID

Example

curl

curl -X GET https://api.banklyze.com/v1/deals/42/assignments \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "data": [
    {
      "deal_id": 42,
      "user_id": 7,
      "role": "underwriter",
      "assigned_at": "2026-03-04T10:15:00Z"
    },
    {
      "deal_id": 42,
      "user_id": 12,
      "role": "reviewer",
      "assigned_at": "2026-03-04T11:30:00Z"
    }
  ]
}

Remove a user from a deal. The user will no longer appear in the assignments list and will stop receiving deal notifications.

Path Parameters

Name	Type	Required	Description
deal_id	integer	Required	The unique deal ID
user_id	integer	Required	ID of the user to unassign

Example

curl

curl -X DELETE https://api.banklyze.com/v1/deals/42/assignments/7 \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "status": "ok",
  "message": "User unassigned from deal"
}

Retrieve a paginated list of all deals that the currently authenticated user has been assigned to, including their role on each deal. Useful for building personal queues and workload views.

Query Parameters

Name	Type	Required	Description
page	integer	Default: 1	Page number (1-indexed)
per_page	integer	Default: 25	Results per page (max 100)

Example

curl

curl -X GET "https://api.banklyze.com/v1/me/assigned-deals?page=1&per_page=25" \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "data": [
    {
      "id": 42,
      "business_name": "Acme Trucking LLC",
      "status": "under_review",
      "health_score": 72.5,
      "health_grade": "B",
      "role": "underwriter",
      "assigned_at": "2026-03-04T10:15:00Z",
      "updated_at": "2026-03-04T12:00:00Z"
    },
    {
      "id": 38,
      "business_name": "Blue Sky Catering Inc",
      "status": "ready",
      "health_score": 81.3,
      "health_grade": "A",
      "role": "reviewer",
      "assigned_at": "2026-03-03T09:00:00Z",
      "updated_at": "2026-03-03T14:22:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 2,
    "total_pages": 1
  }
}

Comments

Comments provide a threaded discussion space for each deal. Every comment is attributed to the authenticated user and timestamped. Comments support soft-deletion — deleted comments are hidden from list responses but retained in audit logs. Only the original author may edit or delete their own comments.

Retrieve a paginated, chronologically ordered list of comments on a deal. Soft-deleted comments are excluded from the response.

Path Parameters

Name	Type	Required	Description
deal_id	integer	Required	The unique deal ID

Query Parameters

Name	Type	Required	Description
page	integer	Default: 1	Page number (1-indexed)
per_page	integer	Default: 25	Results per page (max 100)

Example

curl

curl -X GET "https://api.banklyze.com/v1/deals/42/comments?page=1&per_page=25" \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "data": [
    {
      "id": 1,
      "deal_id": 42,
      "user_id": 7,
      "user_name": "Jane Doe",
      "body": "Reviewed statements — deposit pattern looks consistent. NSF in October is a one-off.",
      "created_at": "2026-03-04T10:30:00Z",
      "updated_at": "2026-03-04T10:30:00Z",
      "deleted_at": null
    },
    {
      "id": 2,
      "deal_id": 42,
      "user_id": 12,
      "user_name": "Mike Rivera",
      "body": "Spoke with owner — confirmed the large January deposit was from equipment sale proceeds.",
      "created_at": "2026-03-04T11:05:00Z",
      "updated_at": "2026-03-04T11:05:00Z",
      "deleted_at": null
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 2,
    "total_pages": 1
  }
}

Post a new comment on a deal. The comment is attributed to the authenticated API key's user. Emits a comment.added event in the deal timeline.

Path Parameters

Name	Type	Required	Description
deal_id	integer	Required	The unique deal ID

Request Body

Name	Type	Required	Description
body	string	Required	Comment body text (max 10,000 characters)

Example

curl

curl -X POST https://api.banklyze.com/v1/deals/42/comments \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Reviewed statements — deposit pattern looks consistent. NSF in October is a one-off."
  }'

Response

Response — 201 Created

{
  "id": 1,
  "deal_id": 42,
  "user_id": 7,
  "user_name": "Jane Doe",
  "body": "Reviewed statements — deposit pattern looks consistent. NSF in October is a one-off.",
  "created_at": "2026-03-04T10:30:00Z",
  "updated_at": "2026-03-04T10:30:00Z",
  "deleted_at": null
}

Update the body of an existing comment. Only the original author of the comment may edit it. The updated_at timestamp is set to the current time on successful edit.

Path Parameters

Name	Type	Required	Description
deal_id	integer	Required	The unique deal ID
comment_id	integer	Required	The unique comment ID

Request Body

Name	Type	Required	Description
body	string	Required	Updated comment body text (max 10,000 characters)

Example

curl

curl -X PATCH https://api.banklyze.com/v1/deals/42/comments/1 \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Reviewed statements — deposit pattern looks consistent. NSF in October is a one-off (confirmed with owner)."
  }'

Response

Response — 200 OK

{
  "id": 1,
  "deal_id": 42,
  "user_id": 7,
  "user_name": "Jane Doe",
  "body": "Reviewed statements — deposit pattern looks consistent. NSF in October is a one-off (confirmed with owner).",
  "created_at": "2026-03-04T10:30:00Z",
  "updated_at": "2026-03-04T10:45:00Z",
  "deleted_at": null
}

Soft-delete a comment. Only the original author may delete their comment. The record is retained internally but will not appear in future list responses. The deleted_at field is set to the deletion timestamp.

Path Parameters

Name	Type	Required	Description
deal_id	integer	Required	The unique deal ID
comment_id	integer	Required	The unique comment ID

Example

curl

curl -X DELETE https://api.banklyze.com/v1/deals/42/comments/1 \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "status": "ok",
  "message": "Comment deleted"
}

Document Requests

Document requests let underwriters formally request additional documents from applicants. Each request is tracked with a status and can include a custom message. When the applicant fulfills the request by uploading the referenced document type, the status transitions to fulfilled automatically.

Create a new document request for a deal. The specified document type will be tracked and the request marked fulfilled when a document of that type is subsequently uploaded to the deal.

Path Parameters

Name	Type	Required	Description
deal_id	integer	Required	The unique deal ID

Request Body

Name	Type	Required	Description
document_type	string	Required	Type of document requested: bank_statement, tax_return, or profit_and_loss
message	string	Optional	Optional message to the applicant explaining the request (max 2,000 characters)

Example

curl

curl -X POST https://api.banklyze.com/v1/deals/42/doc-requests \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "tax_return",
    "message": "Please provide the most recent two years of business tax returns."
  }'

Response

Response — 201 Created

{
  "id": 5,
  "deal_id": 42,
  "document_type": "tax_return",
  "message": "Please provide the most recent two years of business tax returns.",
  "status": "pending",
  "created_at": "2026-03-04T13:00:00Z"
}

Retrieve all document requests attached to a deal. Each entry shows the requested document type, optional message, and current fulfillment status.

Path Parameters

Name	Type	Required	Description
deal_id	integer	Required	The unique deal ID

Example

curl

curl -X GET https://api.banklyze.com/v1/deals/42/doc-requests \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "data": [
    {
      "id": 5,
      "deal_id": 42,
      "document_type": "tax_return",
      "message": "Please provide the most recent two years of business tax returns.",
      "status": "pending",
      "created_at": "2026-03-04T13:00:00Z"
    },
    {
      "id": 6,
      "deal_id": 42,
      "document_type": "profit_and_loss",
      "message": null,
      "status": "fulfilled",
      "created_at": "2026-03-03T09:00:00Z"
    }
  ]
}

Timeline & Activity

Banklyze records every significant event on a deal as a timeline entry. The per-deal timeline provides a complete audit log for a single deal, while the organization-wide activity feed surfaces recent events across all deals for team situational awareness.

Retrieve a chronological list of all events that have occurred on a deal, including document uploads, processing completions, assignments, comments, decisions, and system events. Results are ordered newest first.

Path Parameters

Name	Type	Required	Description
deal_id	integer	Required	The unique deal ID

Query Parameters

Name	Type	Required	Description
page	integer	Default: 1	Page number (1-indexed)
per_page	integer	Default: 50	Results per page (max 100)

Example

curl

curl -X GET "https://api.banklyze.com/v1/deals/42/timeline?page=1&per_page=50" \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "data": [
    {
      "id": 201,
      "deal_id": 42,
      "event_type": "deal.created",
      "actor": "Jane Doe",
      "description": "Deal created",
      "metadata": {},
      "created_at": "2026-03-01T09:00:00Z"
    },
    {
      "id": 202,
      "deal_id": 42,
      "event_type": "document.uploaded",
      "actor": "Jane Doe",
      "description": "Bank statement uploaded: acme_jan_2026.pdf",
      "metadata": { "document_id": 15 },
      "created_at": "2026-03-01T09:05:00Z"
    },
    {
      "id": 203,
      "deal_id": 42,
      "event_type": "deal.assigned",
      "actor": "Admin",
      "description": "Assigned to Mike Rivera as reviewer",
      "metadata": { "user_id": 12, "role": "reviewer" },
      "created_at": "2026-03-04T11:30:00Z"
    },
    {
      "id": 204,
      "deal_id": 42,
      "event_type": "comment.added",
      "actor": "Mike Rivera",
      "description": "Left a comment",
      "metadata": { "comment_id": 2 },
      "created_at": "2026-03-04T11:05:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 4,
    "total_pages": 1
  }
}

Retrieve a paginated, reverse-chronological feed of events across all deals in your organization. Useful for building real-time dashboards, notification surfaces, and audit reports. Each entry includes the deal context so you can link directly to the relevant deal.

Query Parameters

Name	Type	Required	Description
page	integer	Default: 1	Page number (1-indexed)
per_page	integer	Default: 25	Results per page (max 100)

Example

curl

curl -X GET "https://api.banklyze.com/v1/activity?page=1&per_page=25" \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "data": [
    {
      "id": 890,
      "deal_id": 42,
      "business_name": "Acme Trucking LLC",
      "event_type": "deal.decision_set",
      "actor": "Jane Doe",
      "description": "Decision set to: approve",
      "metadata": { "decision": "approve" },
      "created_at": "2026-03-04T14:00:00Z"
    },
    {
      "id": 891,
      "deal_id": 38,
      "business_name": "Blue Sky Catering Inc",
      "event_type": "document.processing_complete",
      "actor": "system",
      "description": "Document processing complete",
      "metadata": { "document_id": 22 },
      "created_at": "2026-03-04T13:45:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 47,
    "total_pages": 2
  }
}

Search for users in your organization by name or email. Primarily used to populate user-picker UIs when creating assignments. Returns only users who are members of your organization.

Query Parameters

Name	Type	Required	Description
q	string	Required	Search query matched against name and email (1–100 characters)

Example

curl

curl -X GET "https://api.banklyze.com/v1/users/search?q=jane" \
  -H "X-API-Key: your_api_key_here"

Response

Response — 200 OK

{
  "data": [
    {
      "id": 7,
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "role": "underwriter"
    }
  ]
}