API Reference¶

Introduction¶

The VoidSign API lets you create signature requests, track their status, and download signed documents and audit trails programmatically. It follows REST conventions: resource-oriented URLs, standard HTTP methods, and JSON-encoded request and response bodies. Use it to integrate e-signature workflows directly into your application.

https://api.voidsign.com

X-VoidSign-Key: vs_live_...

Data Types¶

The API uses standard JSON types. Some string fields carry a format qualifier shown in parentheses in the schema tables:

Errors¶

All errors follow a unified format with a top-level error object containing code and message fields. Some errors also include a details array. See the Errors Table for the full list of error codes and examples.

Rate Limits¶

The API enforces a token-bucket rate limit of 60 requests per minute per API key. Every response includes standard RateLimit-* headers. When the limit is exceeded, the API returns a 429 error with a Retry-After header. For full details, see the Rate Limit Headers & Policy.

Update Policy¶

The API evolves in non-breaking ways for existing integrations. For details on what this means and how to stay informed about improvements, see the API Evolution Policy.

OpenAPI Specification¶

Download openapi.json

Getting Started¶

For a step-by-step walkthrough of creating your first signature request, choose your integration mode on Integration Modes and follow either the mail-flow tutorial or the embed-flow tutorial.

Create request¶

POST /api/v1/requests

Upload one or more PDF documents (up to 5) with positioned fields and send signature invitations to the specified signers. Each signer receives an email with a link to sign the documents.

curl -X POST \
  "https://api.voidsign.com/api/v1/requests" \
  -H "X-VoidSign-Key: vs_live_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "auth_method": "mail",
    "description": "Service agreement Q1 2025",
    "documents": [
      {
        "base64": "JVBERi0xLjQg...",
        "fields": [
          {
            "box_coordinate_system": "CS-ULP-GD",
            "box_height_ratio": 0.1,
            "box_width_ratio": 0.3,
            "box_x_ratio": 0.15,
            "box_y_ratio": 0.7,
            "page_number": 0,
            "signer_ref": 1,
            "type": "signature"
          }
        ]
      }
    ],
    "invitation_mode": "voidsign_mail",
    "locales": [
      "fr-FR"
    ],
    "signers": [
      {
        "email": "jean.dupont@example.com",
        "first_name": "Jean",
        "last_name": "Dupont",
        "ref": 1,
        "reminder_days": [
          3,
          7
        ]
      }
    ]
  }'

Request body¶

Schema: CreateRequestBody

{
  "auth_method": "mail",
  "description": "Service agreement Q1 2025",
  "documents": [
    {
      "base64": "JVBERi0xLjQg...",
      "fields": [
        {
          "box_coordinate_system": "CS-ULP-GD",
          "box_height_ratio": 0.1,
          "box_width_ratio": 0.3,
          "box_x_ratio": 0.15,
          "box_y_ratio": 0.7,
          "page_number": 0,
          "signer_ref": 1,
          "type": "signature"
        }
      ]
    }
  ],
  "invitation_mode": "voidsign_mail",
  "locales": [
    "fr-FR"
  ],
  "signers": [
    {
      "email": "jean.dupont@example.com",
      "first_name": "Jean",
      "last_name": "Dupont",
      "ref": 1,
      "reminder_days": [
        3,
        7
      ]
    }
  ]
}

Responses¶

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "signers": [
    {
      "email": "jean.dupont@example.com",
      "embed": {
        "expires_at": "2026-05-25T14:00:00+00:00",
        "iframe_url": "https://app.voidsign.com/sign/embed/eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
      },
      "signer_id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "status": "pending"
    }
  ],
  "status": "created"
}

Get request status¶

GET /api/v1/requests/{request_id}

Retrieve the current status of a signature request, including per-signer details and timestamps.

curl -X GET \
  "https://api.voidsign.com/api/v1/requests/{request_id}" \
  -H "X-VoidSign-Key: vs_live_API_KEY"

Parameters¶

Responses¶

{
  "created_at": "2025-01-15T10:00:00Z",
  "description": "Service agreement Q1 2025",
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "signed_at": null,
  "signers": [
    {
      "email": "jean.dupont@example.com",
      "first_name": "Jean",
      "last_name": "Dupont",
      "signed_at": "2025-01-15T14:30:00Z",
      "signer_id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "status": "signed"
    }
  ],
  "status": "created"
}

Refresh iframe token¶

POST /api/v1/requests/{request_id}/signers/{signer_id}/iframe_token

Mint a fresh sign_api token for a signer in a request that was created with invitation_mode="caller_embed". Previously-minted tokens are not invalidated; each one lives until its own JWT exp claim. Use this to resume a signing session hours/days after request creation or to recover from an expired token without recreating the request.

curl -X POST \
  "https://api.voidsign.com/api/v1/requests/{request_id}/signers/{signer_id}/iframe_token" \
  -H "X-VoidSign-Key: vs_live_API_KEY" \
  -H "Content-Type: application/json"

Parameters¶

Responses¶

{
  "expires_at": "2026-05-25T14:00:00+00:00",
  "iframe_url": "https://app.voidsign.com/sign/embed/eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Download signed PDF¶

GET /api/v1/requests/{request_id}/downloads/signed

Download the final signed document(s). The request must be fully signed (all signers have completed). The response payload depends on how many documents the request holds: a single-document request streams the lone signed PDF (application/pdf); a multi-document request streams a ZIP archive (application/zip) with one signed PDF entry per document. Inspect the Content-Type header to distinguish the two.

curl -X GET \
  "https://api.voidsign.com/api/v1/requests/{request_id}/downloads/signed" \
  -H "X-VoidSign-Key: vs_live_API_KEY" \
  --output signed.pdf

Parameters¶

Responses¶

{
  "error": {
    "code": "signature_request_not_completed",
    "message": "Signature request is not fully signed yet"
  }
}

Download audit trail¶

GET /api/v1/requests/{request_id}/downloads/audit-trail/{format}

Download the audit trail for a fully signed request. Available in JSON or PDF format.

curl -X GET \
  "https://api.voidsign.com/api/v1/requests/{request_id}/downloads/audit-trail/{format}" \
  -H "X-VoidSign-Key: vs_live_API_KEY" \
  --output audit-trail

Parameters¶

Responses¶

{
  "error": {
    "code": "signature_request_not_completed",
    "message": "Signature request is not fully signed yet"
  }
}

Annex¶

Schemas¶

CreateRequestBody¶

Used by: create-request

ApiDocument¶

Used by: create-request

ApiSfieldSignature¶

Signature field positioned using the CS-ULP-GD coordinate system (upper-left point + given dimensions).

Used by: create-request

ApiSfieldSignatureACPGD¶

Used by: create-request

ApiSfieldText¶

Static text field positioned using the CS-CP-AD coordinate system (center point + auto-derived dimensions).

Used by: create-request

ApiSfieldParaph¶

Paraph (initials) field positioned using the CS-CP-AD coordinate system (center point + auto-derived dimensions).

Used by: create-request

ApiSfieldDate¶

Automatic date field positioned using the CS-CP-AD coordinate system (center point + auto-derived dimensions).

Used by: create-request

ApiSigner¶

Used by: create-request

CreateRequestResponse¶

Used by: create-request

SignerStatusResponse¶

Used by: create-request

SignerEmbedTokenResponse¶

Used by: create-request

GetRequestResponse¶

Used by: get-request-status

GetRequestSignerResponse¶

Used by: get-request-status

RefreshIframeTokenResponse¶

Used by: refresh-iframe-token

Errors Table¶

All API errors share a consistent JSON envelope:

{
  "error": {
    "code": "...",
    "message": "...",
    "details": [...]
  }
}

Request errors (400/404): business-logic and resource errors:

{
  "error": {
    "code": "signature_request_not_completed",
    "message": "Signature request is not fully signed yet"
  }
}

Authentication errors (401/403): missing, invalid, or unauthorized API key:

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key"
  }
}

Validation errors (422): request body failed schema validation:

{
  "error": {
    "code": "invalid_request",
    "message": "Request body failed validation",
    "details": [
      {
        "field": "signers[0].email",
        "message": "Value is not a valid email address"
      }
    ]
  }
}

Server errors (500): unexpected internal failures:

{
  "error": {
    "code": "email_send_error",
    "message": "Failed to send signature invite emails"
  }
}

400: Bad Request¶

401: Unauthorized¶

403: Forbidden¶

404: Not Found¶

422: Validation Error¶

500: Server Error¶

What's Next¶

Now that you're familiar with the API surface, here are some useful next steps:

• Integration Modes: compare the mail and embed flows, then jump into the mail-flow tutorial or the embed-flow tutorial.
• Set Up Webhooks: receive real-time notifications when signature requests change status.
• API Evolution Policy: stay informed about new endpoints, fields, and improvements.