These endpoints are required in order to use the BYOSP feature. All paths are relative to the endpointUrl you configured in Ironclad Setup.

{id} is the Ironclad signature request ID, a UUID that Ironclad generates at initiation, sends as signatureRequestId in the initiate body, and passes as a path segment on every call after it.

Endpoint Summary

Non-2xx responses and timeouts are surfaced to Ironclad as middleware errors. Status, cancel, and remind must respond within 5 seconds; initiate and document fetch within 15 seconds.

Initiate

POST {endpointUrl}

Sent as multipart/form-data with these parts:

Request Body

Example:

{
  "signatureRequestId": "3f0c8b12-5e44-4c1a-9d77-2b91f0a4de21",
  "routingType": "sequential",
  "signers": [
    {
      "roleName": "Buyer",
      "name": "Kim Lam",
      "email": "[email protected]",
      "title": "",
      "routingOrder": 0
    },
    {
      "roleName": "Seller",
      "name": "Jimothy Kim",
      "email": "[email protected]",
      "title": "General Counsel",
      "routingOrder": 1
    }
  ],
  "cc": [],
  "fields": [
    {
      "type": "signature",
      "roleName": "Buyer",
      "x": 72,
      "y": 640,
      "page": 1,
      "width": 150,
      "height": 30,
      "required": true,
      "pageWidth": 612,
      "pageHeight": 792,
      "tagOrigin": "embedded",
      "tagId": "2gbqtjl"
    },
    {
      "type": "signature",
      "roleName": "Seller",
      "x": 320,
      "y": 640,
      "page": 1,
      "width": 150,
      "height": 30,
      "required": true,
      "pageWidth": 612,
      "pageHeight": 792,
      "tagOrigin": "placed"
    }
  ],
  "documentHashes": ["e3b0c44298fc1c14..."],
  "expiresAt": "2026-02-01T00:00:00.000Z",
  "fromName": "Ironclad",
  "emailSettings": {
    "subject": "Please sign: Mutual NDA",
    "body": "Your signature is requested on the attached agreement."
  }
}

documentHashes is how document integrity is bound to the request signature: the signature covers the JSON body string, the body contains documentHashes, and each hash is the SHA-256 of the corresponding document_N part. See Document Integrity.

Expected Response

Example:

{
  "status": "pending",
  "signatures": [
    {
      "roleName": "Buyer",
      "signer": {
        "name": "Kim Lam",
        "email": "[email protected]"
      },
      "status": "awaiting_signature"
    },
    {
      "roleName": "Seller",
      "signer": {
        "name": "Jimothy Kim",
        "email": "[email protected]"
      },
      "status": "awaiting_signature"
    }
  ]
}

Ironclad validates this response. Unknown keys are ignored rather than rejected, so a misspelled field is silently dropped, while a missing or malformed required field fails the call.

signer.title and signer.routingOrder are sent to you at initiation but cannot be updated from the middleware, so they are not expected back. Omit them from signer here and on status pushes.

Status

GET {endpointUrl}/{id}/status

Returns the same response shape as Initiate, except that status may be any of the following:

Ironclad trusts the request-level status field over any inference from individual signer states. If every signer has signed but you return pending, the signature request stays open.

As with initiate, return the full signatures array on every response. A signer omitted from the array is removed from the signature request.

Cancel

POST {endpointUrl}/{id}/cancel

Terminate the signature request with your provider.

Request body: {}

Expected response: any 2xx. The response body is ignored.

Remind

POST {endpointUrl}/{id}/remind

Remind an outstanding signer.

Ironclad only reminds signers who have not signed on an open signature request, and today always targets a single signer, so roleName is always present in practice. It is documented as optional for forward compatibility. If you ever receive it omitted, remind all outstanding signers.

Expected response: any 2xx. The response body is ignored.

Document

GET {endpointUrl}/{id}/document

Return the signed PDF with Content-Type: application/pdf. Ironclad enforces the following constraints on the response:

• Content type must start with application/pdf, or the response is rejected.
• Size cap of 50 MB, checked against Content-Length for a fast fail and again against the buffered body length.
• An empty body is rejected. If your provider cannot return a document mid-signing, returning an error or empty body during a partial or preview read is tolerated, and Ironclad falls back to the unsigned packet. A read after the signature request has completed must return the signed PDF.
• The document is antivirus-scanned on arrival. Infected or unscannable files are rejected (fail-closed).