Partner API

The Partner API is signID’s REST API for programmatic access. It’s how third-party developers and platforms create envelopes, check status, download sealed documents, and drive the whole signing workflow from their own backend.

Key characteristics:

• REST over HTTPS, JSON payloads
• Documented via OpenAPI 3.1 (interactive reference in-app)
• Bearer API keys (format sk_live_...)
• Base path: /api/v1/partner/v1/
• Rate-limited per endpoint and per key

signID’s product philosophy is “the documentation is the product”, meaning the API is a first-class surface, not a lesser add-on.

The Partner API is fully described by an OpenAPI 3.1 specification (also known as Swagger 3.1). The spec is auto-generated from the actual code, meaning it’s always in sync with what the API actually does.

What you get:

• Every endpoint’s URL, method, parameters, and request/response shapes
• Stable enum values (envelope statuses, field kinds) documented explicitly
• Example requests and responses
• Auth requirements per endpoint

You can import the OpenAPI spec into tools like Postman, Insomnia, or your favorite code generator to instantly get typed clients.

Go to Settings → Integrations → API keys and click Create key. Choose:

• A label (for your reference, e.g. “Production backend”)
• Optional scopes (limit the key to specific actions)

signID generates a key in the format sk_live_[12hex]_[base64url]. Copy it immediately. The full key is shown only once, subsequent views mask everything except the prefix.

Every API request must include the API key as a Bearer token in the Authorization header:

Authorization: Bearer sk_live_a1b2c3d4e5f6_...

Example with curl:

curl https://signid.brandid.app/api/v1/partner/v1/envelopes \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json"

Missing or invalid tokens return 401 Unauthorized. Insufficient permissions (e.g. viewer key trying to create) return 403 Forbidden.

The most common workflow is creating an envelope from your backend:

POST /api/v1/partner/v1/envelopes
{
  "title": "Partnership agreement",
  "pdfStorageKey": "uploads/abc123.pdf",
  "signers": [
    {"name": "Ali", "email": "[email protected]"}
  ],
  "signInOrder": false,
  "expiresAt": "2026-12-31T23:59:59Z"
}

The pdfStorageKey refers to a PDF you’ve already uploaded via the presigned upload endpoint. The response includes the new envelope’s ID, status, and a signing URL for each signer.

Full field list and options are in the OpenAPI spec.

To check on an envelope’s progress:

GET /api/v1/partner/v1/envelopes/{id}

Response includes:

• status: one of draft, pending, signed, declined, expired, cancelled
• signers: array with per-signer status (viewed, signed, etc.)
• documentSha256: the sealed document hash (populated once signed)
• pageCount: number of pages
• progress: how many signers have completed

To get access to the sealed PDF from your backend:

GET /api/v1/partner/v1/envelopes/{id}/file-access

The response contains a short-lived, presigned download URL. Fetch it before the URL expires.

You can also request:

• The original unsigned PDF
• The completion certificate
• The complete bundle (ZIP with audit JSON)

Include the artifact type as a query parameter. See the OpenAPI spec for exact options.

signID commits to stable enum values across API versions:

• Envelope status: draft, pending, signed, declined, expired, cancelled
• Field kinds: signature, date, initials, name, text, checkbox, radio

These strings will not change or be renamed within the current API version. If new values are added (e.g. a new field kind), it’s a non-breaking additive change and existing values continue to work.

The API is rate-limited per endpoint and per key, backed by Redis. Example limits:

• Create envelope: ~120 burst / 2 per second sustained
• Get envelope: ~300 burst / 5 per second sustained

Every response includes rate limit headers:

• X-RateLimit-Remaining: requests remaining in the current window
• X-RateLimit-Resource: the specific bucket being counted
• Retry-After: seconds until you can retry (on 429 only)

When you exceed a limit, the response is 429 Too Many Requests. Back off and retry per Retry-After.

Compromised key? Rotate it immediately:

1. Create a new key in Settings → Integrations → API keys
2. Update your backend to use the new key
3. Revoke the old key

Revocation is via the API or the UI:

POST /api/v1/integrations/api-keys/{id}/revoke

Revoked keys stop working immediately. Any in-flight request using a revoked key fails with 401 Unauthorized.

signID’s partner documentation includes a 5-step quick start designed to get a developer from zero to a successfully signed envelope in under 30 minutes:

1. Get an API key from Settings → Integrations
2. Upload a PDF via the presigned upload endpoint
3. Create an envelope via POST /envelopes with your PDF’s storage key
4. Send the signing URL to your signer (or embed it in an iframe)
5. Handle the webhook when the envelope is signed

The quick start includes copy-paste examples in curl, Node.js, and Python.

An interactive API reference is rendered in-app using Scalar, based on the OpenAPI spec. Access it from Settings → Integrations → API reference.

Features:

• Every endpoint documented with parameters, responses, and examples
• “Try it” button, run real API calls from the browser with your API key filled in
• Code examples in curl, JavaScript, Python, PHP, and more
• Search across endpoints

Great for exploring the API interactively before writing production code.