Get Signature Request Status

Retrieve the current status of a signature request, including overall status, per-signer status and assigned documents.

Authentication

This endpoint requires a bearer token. See Authentication and API Keys.

Headers

Header	Required	Description
Authorization	required	`Bearer <BEARER_TOKEN>`

Parameters

Parameter	Type	Description
package_guid required	string	The package GUID returned when the request was created (e.g. `7A8F1-92D3E-810A2-9E47A`).

Request body

Request body: None.

Request example

curl -X GET "https://toolkit.undersign.app/api/v1.1/signature-requests/<package-guid>" \
  -H "Authorization: Bearer <BEARER_TOKEN>"

Response

A successful response returns the request's overall status, its signers, and the documents assigned to each signer. While the request status is Pending, files is null; when Completed, it carries the completion certificate and signed documents as Base64 PDFs.

Successful response

{
  "success": true,
  "request_id": "...",
  "timestamp": "...",
  "data": {
    "package_guid": "AD95C-C39D9-C5467-CBF1A",
    "external_id": null,
    "metadata": null,
    "created_at": "...",
    "overall_status": "...",
    "signers": [
      {
        "signer_name": "John Doe",
        "signer_email": "<signer-email-1>",
        "signer_status": "...",
        "signing_link": "...",
        "assigned_documents": [
          {
            "document_title": "...",
            "role": "...",
            "status": "..."
          }
        ]
      }
    ],
    "files": {
      "certificate": "<base64-pdf-blob>",
      "signed_documents": [
        {
          "document_title": "...",
          "file_name": "...",
          "base64": "<base64-pdf-blob>"
        }
      ]
    }
  }
}

Response fields

Field	Description
success	Whether the request succeeded.
request_id	API request / correlation identifier.
timestamp	API response timestamp.
data.package_guid	Public / package GUID.
data.external_id	External business identifier, if supplied.
data.metadata	Metadata associated with the request, if supplied.
data.created_at	When the request was created.
data.overall_status	The request's current status.
data.signers	Array of signer status records.
signers.signer_name	Signer's name.
signers.signer_email	Signer's email address.
signers.signer_status	Signer's current status.
signers.signing_link	The signer's secure signing link.
signers.assigned_documents	Documents assigned to this signer.
assigned_documents.document_title	Document title.
assigned_documents.role	The role assigned for this document.
assigned_documents.status	The document's status for this signer.
data.files	Completed files. `null` while the request is `Pending`.
files.certificate	Completion certificate represented as a Base64 PDF blob (when `Completed`).
files.signed_documents	Array of signed documents (when `Completed`).
signed_documents.document_title	Document title.
signed_documents.file_name	Server file name of the signed document.
signed_documents.base64	Signed document represented as a Base64 PDF blob.

Response status & error codes

Code	Error code	Description
`200 OK`	`-`	Status and files retrieved.
`404`	`PACKAGE_NOT_FOUND`	Signature request not found.
`429`	`RATE_LIMIT_EXCEEDED`	Too many requests (limit: 100/min). See Rate Limits.

Implementation guidance

Inspect overall_status for the request, then signer_status for each signer and the per-document status in assigned_documents.
To follow each signer's progress, use the signing_link returned for that signer.
Decode files.certificate from Base64 to obtain the PDF completion certificate.
Avoid aggressive polling, prefer webhooks for event-driven tracking.

Create Signature Request

Create the request you check the status of.

Signature Requests

How requests combine templates, signers and configuration.