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"
    ],
    "metadata": {
      "crm_contact": "cust_8842",
      "order_id": "A-123"
    },
    "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"
  ],
  "metadata": {
    "crm_contact": "cust_8842",
    "order_id": "A-123"
  },
  "signers": [
    {
      "email": "jean.dupont@example.com",
      "first_name": "Jean",
      "last_name": "Dupont",
      "ref": 1,
      "reminder_days": [
        3,
        7
      ]
    }
  ]
}

Vos métadonnées (metadata)¶

Le champ optionnel metadata est un dictionnaire qui vous appartient : VoidSign le stocke, vous le restitue à la lecture et le renvoie dans les payloads de webhook, sans jamais l'interpréter. C'est là que vous inscrivez la correspondance entre une demande VoidSign et l'enregistrement équivalent dans votre propre système : l'identifiant de commande, la référence CRM, le numéro de dossier. Vos webhooks deviennent alors auto-suffisants : plus besoin d'un GET de rattrapage pour savoir de quel dossier il s'agit.

Le format est volontairement étroit :

En cas de dépassement d'une limite, la réponse 422 porte un tableau details dont le champ field désigne la clé fautive.

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}?expand=events,emails" \
  -H "X-VoidSign-Key: vs_live_API_KEY"

Parameters¶

Inclure les événements et les e-mails (expand)¶

Par défaut, cet endpoint renvoie un résumé : statut de la demande, horodatages et tableau des signataires. Le paramètre de requête optionnel expand permet d'y ajouter, à la demande, la chronologie des événements de la demande et la liste des e-mails que VoidSign a envoyés en votre nom. C'est le moyen, au moment du polling, de répondre à « l'invitation est-elle réellement partie, et quand ? » sans quitter l'API.

Deux syntaxes sont acceptées, indifféremment :

GET /api/v1/requests/{request_id}?expand=events&expand=emails
GET /api/v1/requests/{request_id}?expand=events,emails

Les segments vides sont ignorés et les doublons sont dédupliqués. La comparaison est sensible à la casse : ?expand=EVENTS renvoie une erreur 422 de code invalid_request, avec un details[].field valant expand. L'appel ne consomme qu'un seul jeton de limite de débit, que expand soit utilisé ou non.

Les champs event_type et email_type sont des énumérations fermées : les valeurs possibles (14 pour event_type, 6 pour email_type) sont énumérées dans le schéma de la réponse, et l'ajout d'une valeur fera l'objet d'une évolution annoncée de l'API. La liste des valeurs est décrite dans Événements de la demande.

Trois des valeurs de event_type (created, signer_signed et completed) décrivent l'état de la demande plutôt qu'un envoi : elles n'ont ni email_id ni link_expires_at, et leur occurred_at est respectivement le created_at de la demande, le signed_at du signataire et le signed_at de la demande.

Le champ email_id sert de clé de jointure entre les deux tableaux : un événement adossé à un e-mail porte l'email_id de la ligne correspondante de emails, et son occurred_at est égal au sent_at de cet e-mail. Seuls les e-mails effectivement remis au fournisseur d'envoi apparaissent dans emails ; un envoi en échec n'apparaît ni dans emails ni dans events. L'e-mail de code à usage unique (OTP) de signature n'y figure pas : il ne génère aucun événement de demande, et ce tableau est construit à partir des événements.

null n'est pas {}¶

Le champ metadata est toujours présent dans la réponse, et il n'est pas conditionné par expand : il accompagne systématiquement la demande.

Cette distinction est contractuelle et se retrouve à l'écriture : PATCH accepte {} (qui vide le dictionnaire) mais refuse null, qui reste réservé à l'état « jamais défini ».

Responses¶

{
  "created_at": "2025-01-15T10:00:00+00:00",
  "description": "Service agreement Q1 2025",
  "emails": [
    {
      "email_id": "c3d4e5f6-a7b8-9012-cdef-234567890abc",
      "email_type": "invite",
      "sent_at": "2025-01-15T10:00:03+00:00",
      "to_signer_id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890"
    }
  ],
  "events": [
    {
      "email_id": "c3d4e5f6-a7b8-9012-cdef-234567890abc",
      "event_type": "invite_sent",
      "link_expires_at": "2025-02-14T10:00:03+00:00",
      "occurred_at": "2025-01-15T10:00:03+00:00",
      "signer_id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890"
    }
  ],
  "metadata": {
    "crm_contact": "cust_8842",
    "order_id": "A-123"
  },
  "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:00+00:00",
      "signer_id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "status": "signed"
    }
  ],
  "status": "created"
}

Update request¶

PATCH /api/v1/requests/{request_id}

Update the customer-owned fields of a signature request: description and metadata. Only the fields present in the body are touched, and metadata is replaced wholesale. Allowed in any status, including completed and cancelled requests — these fields are yours, and are not part of the signed artefact.

curl -X PATCH \
  "https://api.voidsign.com/api/v1/requests/{request_id}" \
  -H "X-VoidSign-Key: vs_live_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Service agreement Q1 2025 (revised)",
    "metadata": {
      "invoice_id": "F-9",
      "order_id": "A-123"
    }
  }'

Parameters¶

Request body¶

Schema: PatchRequestBody

{
  "description": "Service agreement Q1 2025 (revised)",
  "metadata": {
    "invoice_id": "F-9",
    "order_id": "A-123"
  }
}

Ce qui est modifié, et ce qui ne l'est pas¶

Cet endpoint ne touche qu'aux deux champs qui vous appartiennent : description et metadata. Il ne modifie ni les documents, ni les signataires, ni le statut de la demande.

La règle tient en une phrase : un champ absent du corps de la requête n'est pas modifié. L'absence et la valeur null sont donc deux choses différentes, et le tableau ci-dessous est l'intégralité du contrat :

La réponse a exactement la même forme que celle de Get request status, avec les tableaux events et emails toujours à null (cet endpoint n'accepte pas de paramètre expand).

Responses¶

{
  "created_at": "2025-01-15T10:00:00+00:00",
  "description": "Service agreement Q1 2025",
  "emails": [
    {
      "email_id": "c3d4e5f6-a7b8-9012-cdef-234567890abc",
      "email_type": "invite",
      "sent_at": "2025-01-15T10:00:03+00:00",
      "to_signer_id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890"
    }
  ],
  "events": [
    {
      "email_id": "c3d4e5f6-a7b8-9012-cdef-234567890abc",
      "event_type": "invite_sent",
      "link_expires_at": "2025-02-14T10:00:03+00:00",
      "occurred_at": "2025-01-15T10:00:03+00:00",
      "signer_id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890"
    }
  ],
  "metadata": {
    "crm_contact": "cust_8842",
    "order_id": "A-123"
  },
  "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:00+00:00",
      "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, patch-request

GetRequestSignerResponse¶

Used by: get-request-status, patch-request

GetRequestEventResponse¶

Used by: get-request-status, patch-request

GetRequestEmailResponse¶

Used by: get-request-status, patch-request

PatchRequestBody¶

Used by: patch-request

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): a request body or a query parameter failed validation. Both share the invalid_request code, but the message differs by source.

A request body that 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: An email address must have an @-sign."
      }
    ]
  }
}

A query parameter that failed validation:

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request",
    "details": [
      {
        "field": "expand",
        "message": "unknown expand value 'bogus'. Allowed values are: events, emails"
      }
    ]
  }
}

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.