Updating and retracting a task

Two write operations apply after you have a taskId from Create Task:

Update Task: PATCH a finished task so SutureHealth stores your external saved-document id (and optionally archives or files it)
Retract Task: DELETE a Pending task you no longer want signed

There is no Partner API reject endpoint. Only the signer can reject, and they do that in Inbox. A rejected task is then eligible for Update, the same as a completed or retracted task.

Both calls use query parameters (not a JSON body) and the x-api-key header.

Update a finished task

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

Use this after you have persisted the signed (or rejected) document in your system and want SutureHealth to record that id.

Allowed statuses: Completed, Rejected, Retracted. A Pending task returns 400.

Query parameters

Parameter	Required	Notes
`externalSavedDocumentId`	Yes	Your id for the stored document. Must be unique for this sender. Sending the same value a second time returns `400`.
`archived`	No	`true` archives the inbox request. Archive cannot be undone (`archived=false` after a successful archive returns `400`).
`saved`	No	`true` marks the request filed. Filing cannot be undone.

A successful update returns 204 No Content. Read the task again to confirm:

output.externalSavedDocumentId
output.isArchived
output.isFiled

Examples

Record where you stored the signed PDF:

PATCH /api/v1/signature/tasks/184392?externalSavedDocumentId=ehr-saved-998877
Host: partner-api.demo.suturehealth.com
x-api-key: YOUR_API_KEY

Record the id and archive:

PATCH /api/v1/signature/tasks/184392?externalSavedDocumentId=ehr-saved-998877&archived=true

Record the id and file (save) the request:

PATCH /api/v1/signature/tasks/184392?externalSavedDocumentId=ehr-saved-998877&saved=true

You can later find these tasks with Bulk Read Tasks:

GET /api/v1/signature/tasks?externalSavedDocumentIds=ehr-saved-998877
GET /api/v1/signature/tasks?isArchived=true
GET /api/v1/signature/tasks?isFiled=true

Update errors (`400`)

externalSavedDocumentId omitted
Task is still Pending (or Received / Processing / Failed)
Task id is unknown for this API key
That externalSavedDocumentId was already applied to this task
Attempt to un-archive or un-file a document that is already archived or filed

Retract a pending task

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

Retract when the document should no longer be signed, for example the order was cancelled, or you will send a corrected PDF as a new task.

Only Pending tasks can be retracted. A successful call returns 204 No Content. Status then becomes Retracted (read the task to confirm; it may take a moment).

DELETE /api/v1/signature/tasks/184392?reason=Order%20cancelled
Host: partner-api.demo.suturehealth.com
x-api-key: YOUR_API_KEY

reason is optional and stored as the task’s status reason.

If the task is not pending (already signed, rejected, failed, or unknown), the API returns 400.

After retract you may Update Task to attach an externalSavedDocumentId if you keep a copy on your side.

Reject is Inbox-only

Partners cannot reject through this API. Paths such as POST /signature/tasks/{id}/reject are not supported.

To stop a request that is still waiting, retract it. If the signer already rejected in Inbox, read the task (status: Rejected, no output.attachment) and update it with your saved-document id if you store that outcome.

Which call to use

Situation	Call
Document is still in the signer’s inbox and should be withdrawn	`DELETE` retract
Signer signed; you stored the PDF	`PATCH` with `externalSavedDocumentId`
Signer signed; you stored the PDF and want it off the active list	`PATCH` with `externalSavedDocumentId` and `archived=true` or `saved=true`
Signer rejected in Inbox; you recorded that in your EHR	`PATCH` with `externalSavedDocumentId`
You need a corrected PDF	Retract the pending task (if still pending), then create a new task