Tratta Docs

# Signature Documents

Signature documents are signature-ready DOCX files you send to Tratta for a single Debt Account. The customer signs the document in the Portal, and Tratta produces a signed PDF with a certificate of completion attached.

Each document is presented in one or more contexts. The global context lists it in the customer's documents in the Portal, while the checkout contexts present it during that checkout. A document presented during checkout counts as signed only once the payment goes through. A document presented in several contexts can be signed once in each of them.

To react to signed documents in real time, subscribe to the signature-document.signed webhook event.

Supported values for status:

  • awaiting_signature : the customer has not opened the document yet.
  • viewed : the customer has opened the document, but it is not signed yet.
  • signed : the document is signed and its signed PDF is ready to download.
  • cancelled : the document was deleted in the Console before it was signed.

# Create Signature Document

POST https://<org-uuid>.production.tratta.io/api/v1/debt-accounts/{id|external_id}/signature-documents

curl https://<org-uuid>.production.tratta.io/api/v1/debt-accounts/{id|external_id}/signature-documents \
 -H "Authorization: Bearer eyJ0eXA3asdk..." \
 -F file=@consent-judgment.docx \
 -F name="Consent judgment" \
 -F signature_placeholder="signature"

The request body is sent as multipart/form-data, since it includes a file. Documents cannot be attached to a child Debt Account.

# Parameters

file required|file

The signature-ready document. Only DOCX files up to 10 MB are accepted.

name required|string

The name of the document shown to the customer. Maximum 255 characters.

description optional|string

A description of the document. Maximum 1000 characters.

signature_placeholder required|string

The placeholder that marks where the customer signs, without its opening and closing characters. For example, signature for a document containing [signature]. The request is rejected if the placeholder does not appear in the document.

placeholder_opening_chars optional|string

The characters that open a placeholder. Defaults to [. Maximum 10 characters.

placeholder_closing_chars optional|string

The characters that close a placeholder. Defaults to ]. Maximum 10 characters.

contexts optional|array

Where the document is presented to the customer. Defaults to ["global"].

Supported values:

  • global : the customer's document list in the Portal.
  • full_payment_checkout
  • partial_payment_checkout
  • payment_plan_checkout
  • settlement_offer_checkout
  • settlement_offer_payment_plan_checkout

send_email optional|boolean

Set to true to email the customer a link to their documents in the Portal. Requires the global context and an email address on the Customer. Defaults to false.

external_id optional|string

Your own id for the document, unique across your Debt Accounts. Sending the same external_id again for the same Debt Account returns the existing document instead of creating a second one. Maximum 255 characters.

# Returns

A json with data property that contains created signature document object.

Sending the same external_id again for the same Debt Account returns the existing document instead of creating a second one.

{
  "id": "9f2c1d3e-7a4b-4c8d-9e1f-2a3b4c5d6e7f",
  "external_id": "DOC-1001",
  "name": "Consent judgment",
  "description": null,
  "status": "awaiting_signature",
  "contexts": [
    "global"
  ],
  "debt_account": {
    "id": "debt-account-uuid",
    "external_id": "ACC-12345"
  },
  "created_at": "2026-09-28 09:00:00",
  "viewed_at": null,
  "signed_at": null
}

# Get Signature Document

GET https://<org-uuid>.production.tratta.io/api/v1/signature-documents/{id|external_id}

curl https://<org-uuid>.production.tratta.io/api/v1/signature-documents/{id|external_id} \
 -H "Authorization: Bearer eyJ0eXA3asdk..."

# Parameters

id required|string

This can be both the signature document id (uuid) generated in Tratta or your own external_id provided in Create Signature Document.

# Returns

A json with data property that contains created signature document object. 

{
  "id": "9f2c1d3e-7a4b-4c8d-9e1f-2a3b4c5d6e7f",
  "external_id": "DOC-1001",
  "name": "Consent judgment",
  "description": null,
  "status": "signed",
  "contexts": [
    "global"
  ],
  "debt_account": {
    "id": "debt-account-uuid",
    "external_id": "ACC-12345"
  },
  "created_at": "2026-09-28 09:00:00",
  "viewed_at": "2026-09-28 13:55:40",
  "signed_at": "2026-09-28 14:02:09"
}

# Get Signature Document Download URL

GET https://<org-uuid>.production.tratta.io/api/v1/signature-documents/{id|external_id}/download-url

curl https://<org-uuid>.production.tratta.io/api/v1/signature-documents/{id|external_id}/download-url \
 -H "Authorization: Bearer eyJ0eXA3asdk..."

# Parameters

id required|string

This can be both the signature document id (uuid) generated in Tratta or your own external_id provided in Create Signature Document.

# Returns

A json with data property that contains a download_url to the latest signed PDF, with the certificate of completion attached. The URL expires after 5 minutes. It is only available once the document is signed.

{
  "download_url": "https://example.com/files/signed_document.pdf"
}

←