Tratta Docs

# Signature Documents

Signature documents are signature-ready DOCX files you send to Tratta for a single Debt Account. The customer signs them in the Portal, and each signing produces a signed document: a signed PDF with a certificate of completion attached. The signed document's id is the Document ID printed on the certificate.

Each signature document is presented in one or more contexts. The global context lists it in the customer's documents in the Portal, where it is signed once. The checkout contexts present it during that checkout, and a signing there counts only once the payment goes through. The customer can sign it again at a later checkout, so a signature document can have several signed documents.

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

# 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,
  "contexts": [
    "global"
  ],
  "debt_account": {
    "id": "debt-account-uuid",
    "external_id": "ACC-12345"
  },
  "signed_documents_count": 0,
  "views_count": 0,
  "created_at": "2026-09-28 09:00:00",
  "viewed_at": null,
  "cancelled_at": null,
  "signed_documents": []
}

# 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.

signed_documents lists each signed document, oldest first, with the context it was signed in. signed_at is when the customer signed. A signing during checkout is listed only once the payment goes through, which can be after signed_at. views_count is how many times the customer opened the signature document in the Portal, and viewed_at is the first time. cancelled_at is when the signature document was deleted in the Console. It is no longer presented to the customer, but its signed documents remain available.

{
  "id": "9f2c1d3e-7a4b-4c8d-9e1f-2a3b4c5d6e7f",
  "external_id": "DOC-1001",
  "name": "Consent judgment",
  "description": null,
  "contexts": [
    "global",
    "payment_plan_checkout"
  ],
  "debt_account": {
    "id": "debt-account-uuid",
    "external_id": "ACC-12345"
  },
  "signed_documents_count": 2,
  "views_count": 3,
  "created_at": "2026-09-28 09:00:00",
  "viewed_at": "2026-09-28 13:55:40",
  "cancelled_at": null,
  "signed_documents": [
    {
      "id": "3b7e9a12-5c4d-4f6e-8a1b-2c3d4e5f6a7b",
      "context": "global",
      "signed_at": "2026-09-28 14:02:09"
    },
    {
      "id": "c8e1f4a7-2b3d-4e5f-9a6b-7c8d9e0f1a2b",
      "context": "payment_plan_checkout",
      "signed_at": "2026-10-05 10:15:00"
    }
  ]
}

# Get Signed Document

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

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

# Parameters

id required|string

The signed document id (uuid), as listed in the signed_documents of Get Signature Document and sent in the signature-document.signed webhook event.

# Returns

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

download_url links to the signed PDF, with the certificate of completion attached. The URL expires after 5 minutes. Get the signed document again for a new one. signature_document is the signature document it was signed from, without its signed_documents.

{
  "id": "c8e1f4a7-2b3d-4e5f-9a6b-7c8d9e0f1a2b",
  "context": "payment_plan_checkout",
  "signed_at": "2026-10-05 10:15:00",
  "download_url": "https://example.com/files/signed_document.pdf",
  "signature_document": {
    "id": "9f2c1d3e-7a4b-4c8d-9e1f-2a3b4c5d6e7f",
    "external_id": "DOC-1001",
    "name": "Consent judgment",
    "description": null,
    "contexts": [
      "global",
      "payment_plan_checkout"
    ],
    "debt_account": {
      "id": "debt-account-uuid",
      "external_id": "ACC-12345"
    },
    "signed_documents_count": 2,
    "views_count": 3,
    "created_at": "2026-09-28 09:00:00",
    "viewed_at": "2026-09-28 13:55:40",
    "cancelled_at": null
  }
}

←