---
title: "API Overview"
description: "How the SignatureAPI REST API works: base URL, request anatomy, HTTP methods and status codes, the endpoint list, and the versioning policy."
canonical: "https://signatureapi.com/docs/api/overview"
source: "https://signatureapi.com/docs/api/overview.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T11:48:47Z"
---

# API Overview

How the SignatureAPI REST API works: base URL, request anatomy, HTTP methods and status codes, the endpoint list, and the versioning policy.

_Last verified against API version 1.18.0._

SignatureAPI API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and methods.

Your backend calls the API with an [API key](https://signatureapi.com/docs/api/authentication). Recipients sign in a ceremony, and [webhooks](https://signatureapi.com/docs/api/webhooks) report each change back to your backend.

**How SignatureAPI fits in your stack**

Parts:

- **Your backend** (Your systems): Holds the API key and creates envelopes.
- **Webhook endpoint** (Your systems): Receives events and verifies their signatures.
- **API** (SignatureAPI): Checks the API key in X-API-Key and validates each request.
- **Envelope** (SignatureAPI): Holds the documents and recipients and moves through its lifecycle.
- **Event** (SignatureAPI): Records each status change of an envelope, recipient or deliverable.
- **Ceremony** (Your recipients): Opened from the signing email or embedded in your app.

Connections:

- Your backend to API: HTTPS requests
- API to Envelope: creates
- Envelope to Ceremony: signing link
- Envelope to Event: status changes
- Event to Webhook endpoint: webhooks

### Base URL

The base URL is `https://api.signatureapi.com` for both [test and live modes](https://signatureapi.com/docs/api/test-mode).

For example, to create an envelope, you do a `POST` request to `https://api.signatureapi.com/v1/envelopes`.

### Anatomy of a request

Every request sends the API key in the `X-API-Key` header. Requests with a body send JSON with `Content-Type: application/json`. The numbered notes explain each part of a request and its response.

**Request**

```http
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "title": "Service Agreement",
  "documents": [
    {
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/acme-service-agreement.pdf",
      "places": [
        {
          "key": "client_signs_here",
          "type": "signature",
          "recipient_key": "client"
        },
        {
          "key": "provider_signs_here",
          "type": "signature",
          "recipient_key": "provider"
        }
      ]
    }
  ],
  "recipients": [
    {
      "type": "signer",
      "key": "client",
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    },
    {
      "type": "signer",
      "key": "provider",
      "name": "John Smith",
      "email": "john.smith@example.com"
    }
  ]
}
```

1. **Method and path** (line 1: `POST /v1/envelopes HTTP/1.1`): Creating an envelope is a `POST` to `/v1/envelopes`.
2. **Authentication** (line 3: `X-API-Key: YOUR_API_KEY`): Send your API key in the `X-API-Key` header. A test key creates test-mode envelopes.
3. **Body** (lines 6-39): Three fields are required: `title`, `documents` (at least one, each with a public file `url`) and `recipients` (at least one). Each place ties a placeholder in the PDF to a recipient `key`.

**Response**

```http
HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
  "status": "processing",
  "mode": "test"
}
```

4. **Status** (line 1: `HTTP/1.1 201 Created`): `201 Created` means the envelope was created and is being processed.
5. **Result** (lines 4-8): The envelope `id` is a plain UUID. It starts in `processing` and moves to `in_progress`.

### HTTP Semantics

We use HTTP methods GET, POST, DELETE as defined in RFC 9110, and PATCH as defined in RFC 5789.

We use the following HTTP Status codes for successful responses:

| Status Code      | Description                                                                                                                                       |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200 OK`         | Request succeeded for a GET, POST, or PATCH call.                                                                                                 |
| `201 Created`    | Request succeeded for a POST request that created a new resource. The response includes a Location header pointing to the newly created resource. |
| `204 No Content` | Request succeeded for a DELETE request. The response has no body.                                                                                 |

Failed requests return a `4XX` or `5XX` status with a problem details body. See [Errors](https://signatureapi.com/docs/api/errors).

### Endpoints

#### Envelopes

- [`GET /v1/envelopes`](https://signatureapi.com/docs/api/resources/envelopes/list): List envelopes
- [`POST /v1/envelopes`](https://signatureapi.com/docs/api/resources/envelopes/create): Create an envelope
- [`GET /v1/envelopes/{envelope_id}`](https://signatureapi.com/docs/api/resources/envelopes/get): Retrieve an envelope
- [`PATCH /v1/envelopes/{envelope_id}`](https://signatureapi.com/docs/api/resources/envelopes/update): Update an envelope
- [`DELETE /v1/envelopes/{envelope_id}`](https://signatureapi.com/docs/api/resources/envelopes/delete): Delete an envelope
- [`POST /v1/envelopes/{envelope_id}/cancel`](https://signatureapi.com/docs/api/resources/envelopes/cancel): Cancel an envelope

#### Events

- [`GET /v1/envelopes/{envelope_id}/events`](https://signatureapi.com/docs/api/resources/events/envelope): List envelope events
- [`GET /v1/events`](https://signatureapi.com/docs/api/resources/events/all): List all events
- [`GET /v1/recipients/{recipient_id}/events`](https://signatureapi.com/docs/api/resources/events/recipient): List recipient events

#### Deliverables

- [`GET /v1/deliverables/{deliverable_id}`](https://signatureapi.com/docs/api/resources/deliverables/get): Retrieve a deliverable
- [`GET /v1/envelopes/{envelope_id}/deliverables`](https://signatureapi.com/docs/api/resources/deliverables/list): List deliverables
- [`POST /v1/envelopes/{envelope_id}/deliverables`](https://signatureapi.com/docs/api/resources/deliverables/create): Create a deliverable

#### Recipients

- [`GET /v1/recipients/{recipient_id}`](https://signatureapi.com/docs/api/resources/recipients/get): Retrieve a recipient
- [`POST /v1/recipients/{recipient_id}/ceremonies`](https://signatureapi.com/docs/api/resources/ceremonies/create): Create ceremony for recipient
- [`POST /v1/recipients/{recipient_id}/replace`](https://signatureapi.com/docs/api/resources/recipients/replace): Replace a recipient
- [`POST /v1/recipients/{recipient_id}/resend`](https://signatureapi.com/docs/api/resources/recipients/resend): Resend request to recipient

#### Uploads

- [`POST /v1/uploads`](https://signatureapi.com/docs/api/resources/uploads/create): Create an upload
- [`GET /v1/uploads/{upload_id}`](https://signatureapi.com/docs/api/resources/uploads/get): Retrieve an upload
- [`POST /v1/uploads/{upload_id}/store`](https://signatureapi.com/docs/api/resources/uploads/store): Store an upload
- [`GET /v1/uploads/{upload_id}/structure`](https://signatureapi.com/docs/api/resources/uploads/structure): Retrieve the structure of an upload

#### Senders

- [`POST /v1/senders`](https://signatureapi.com/docs/api/resources/senders/create): Create a sender
- [`GET /v1/senders/{sender_id}`](https://signatureapi.com/docs/api/resources/senders/get): Retrieve a sender
- [`DELETE /v1/senders/{sender_id}`](https://signatureapi.com/docs/api/resources/senders/delete): Delete a sender

### Versioning

The current version of the API is **v1**. We will increment the version number if we make a change that breaks backward compatibility.

These are not breaking changes:

- Any additive change, such as adding endpoints, optional arguments, or enum values.
- Making a required request parameter optional.
- Making a validation less restrictive.
- Changes to error responses.
- Changes to the order of fields returned in a response.
- Changes to the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings.
- Adding new event types.
