Tracking a document signature

After Create Task you get a taskId. Use that id to watch status, wait until the document is in the signer’s inbox, and download the signed PDF when the task completes.

There are two read endpoints:

• Read Task By Id: one task
• Bulk Read Tasks: a filtered, paginated list

Both require the x-api-key header. Results are limited to tasks created by the organization on that key.

Task statuses

Received on create is not the same as “ready for the signer.” Poll until Pending or a terminal status.

Track one task

GET /api/v1/signature/tasks/{id}

GET /api/v1/signature/tasks/184392
Host: partner-api.demo.suturehealth.com
x-api-key: YOUR_API_KEY

Query parameters

A pending task has no signed file:

{
  "taskId": 184392,
  "documentId": 77821,
  "externalDocumentId": "ehr-doc-1234",
  "status": "Pending",
  "inputJson": null,
  "isModifiedBySigner": false,
  "createdAt": "2026-08-14T15:02:11Z",
  "updatedAt": "2026-08-14T15:02:48Z",
  "output": {
    "statusReason": null,
    "attachment": null,
    "eventTime": "2026-08-14T15:02:48Z",
    "externalSavedDocumentId": null,
    "isArchived": false,
    "isFiled": false
  }
}

After the signer signs, the same call (default includeOutputAttachment=true) returns status: Completed and a Base64 PDF on output.attachment.

To confirm completion without pulling the PDF:

GET /api/v1/signature/tasks/184392?includeOutputAttachment=false

To inspect what you originally sent:

GET /api/v1/signature/tasks/184392?includeInputJson=true
GET /api/v1/signature/tasks/184392?includeInputJson=true&includeInputAttachment=true

Polling

1. Create the task and store taskId and externalDocId.
2. GET by id every few seconds until status is Pending, Failed, or Cancelled.
3. When you need the signed file, GET again after Completed. Prefer includeOutputAttachment=false on intermediate polls.

documentId is SutureHealth’s inbox request id. It is null until the task reaches Pending.

Errors

Track many tasks

GET /api/v1/signature/tasks

Use the list endpoint to reconcile a queue, catch completions you did not poll, or find a task by the id you stored at create time.

GET /api/v1/signature/tasks?statuses=Pending&page=1&pageSize=20
Host: partner-api.demo.suturehealth.com
x-api-key: YOUR_API_KEY

Filters

The same includeInputJson, includeInputAttachment, and includeOutputAttachment flags from read-by-id apply here. Default includeOutputAttachment is true. Set it to false on large pages unless you need every signed PDF.

Pagination

Response envelope:

{
  "tasks": [
    {
      "taskId": 184392,
      "documentId": 77821,
      "externalDocumentId": "ehr-doc-1234",
      "status": "Pending",
      "createdAt": "2026-08-14T15:02:11Z",
      "updatedAt": "2026-08-14T15:02:48Z",
      "output": {
        "attachment": null,
        "isArchived": false,
        "isFiled": false
      }
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalCount": 1
  }
}

Useful list calls

Find the task you just created:

GET /api/v1/signature/tasks?externalDocumentIds=ehr-doc-1234&pageSize=10

Inbox still waiting on a signer:

GET /api/v1/signature/tasks?statuses=Pending&page=1&pageSize=50&includeOutputAttachment=false

Signed since this morning:

GET /api/v1/signature/tasks?statuses=Completed&updatedAfter=2026-08-14T00:00:00Z&includeOutputAttachment=false

Created today:

GET /api/v1/signature/tasks?createdAfter=2026-08-14T00:00:00Z&createdBefore=2026-08-15T00:00:00Z

Recommended integration pattern

1. Create the task and persist taskId + externalDocId.
2. Prefer status webhooks for status changes (Pending, Completed, Rejected, Failed, …). Use poll by id only as a fallback (for example after downtime, or if you have not registered a webhook yet).
3. On a schedule, bulk read statuses=Completed (and Rejected) for tasks you have not yet stored. Filter with updatedAfter or externalDocumentIds.
4. Download output.attachment once, store it in your system, then update the task with your externalSavedDocumentId.
5. Retract from your side only while the task is still Pending.

Webhooks

Preferred for status updates: register an HTTPS endpoint and verify signed deliveries when a task moves (for example to Pending, Completed, Rejected, or Failed).

Full guide: Receiving status webhooks — subscribe, delivery payload, HMAC verification, deactivate / delete.

Keep the read endpoints on this page for PDF download, ad-hoc checks, and reconciliation if a delivery was missed.