Send documents for legally binding e-signature, collect the signed PDF and its audit trail, and optionally hold a signature until a payment succeeds. Signers can be your registered users, your business customers, external people, or your own company signing automatically.
Quickstart: send your first contract
Three steps, two API calls once the template is ready.
1. Prepare a template (once). Upload a PDF or DOCX and place the signature fields. The easiest way is the UrbanPay dashboard: upload the document, open it in the document builder, add a signer role (for example Investor) and at least one signature field. To do it over the API, call POST /api/v1/contracts/templates and then open the builder with POST /api/v1/contracts/templates/{id}/builder-session. A template cannot be sent until it has at least one signer role and one field.
2. Send it.
POST /api/v1/contracts/send
Authorization: Bearer <access_token>
Content-Type: application/json{
"template_version_id": "8c1d6a2e-...",
"project_id": "f3b0c9a4-...",
"signers": [
{ "role": "Investor", "source": "user", "user_id": "5e7a1b3c-..." },
{ "role": "Company", "source": "client_signing_profile" }
],
"variables": { "investment_amount": "10,000 EUR" }
}The investor receives a signing invitation by email. Once they sign, your company counter-signs automatically with your signing profile. The response is the contract request; keep its id.
3. Get the result. Subscribe to the contract.request.completed webhook (or poll GET /api/v1/contracts/requests/{id}), then download the signed PDF with GET /api/v1/contracts/requests/{id}/document and the audit trail with GET /api/v1/contracts/requests/{id}/audit-log.
Core concepts
| Concept | What it is |
|---|---|
| Template | An uploaded PDF or DOCX with signer roles and fields placed on it. Reusable. |
| Contract flow | A saved, reusable signing setup for one template: who signs, in what order, payment gate, emails. Called workflow in the API paths (/contracts/workflows). |
| Contract request | One contract sent to specific people. Created from a contract flow, or directly with POST /contracts/send. |
| Participant | A signer on a contract request, with its own status and signing link. |
| Signing profile | Your company's own signature identity, used to counter-sign automatically. |
| CC recipient | Someone who gets a read-only view link and status emails but never signs. |
Contract flows are separate from automation workflows (
/api/v1/workflows). Automation workflows can include a contract step, but the two are different resources.
Two ways to send
POST /contracts/send | Contract flow + POST /contracts/requests | |
|---|---|---|
| Best for | One-off contracts, or getting started | The same contract sent many times |
| Calls per contract | 1 | 1 (after creating the flow once) |
| Signers | Listed inline in signers | Defined once as participants; the people are supplied per request |
| Reuse | Pass save_as_flow: true to keep the setup as a contract flow | Built in |
Both paths produce the same contract request object, statuses and webhooks.
Sending from a contract flow
Create the flow once:
POST /api/v1/contracts/workflows{
"name": "Investment agreement",
"template_version_id": "8c1d6a2e-...",
"participants": [
{ "key": "investor", "source": "user", "role": "Investor", "expire_after_hours": 168 },
{ "key": "company", "source": "client_signing_profile", "role": "Company" }
],
"stages": [
{ "index": 1, "type": "signature", "participant": "investor", "delivery": "link" },
{ "index": 2, "type": "wait_transaction_success" },
{ "index": 3, "type": "signature", "participant": "company", "delivery": "autosign" }
],
"email_notifications": { "cc_emails": ["[email protected]"] }
}Then send it to specific people, as often as needed:
POST /api/v1/contracts/requests{
"workflow_id": "2d4f6b8a-...",
"project_id": "f3b0c9a4-...",
"participant_subjects": {
"investor": { "user_id": "5e7a1b3c-..." }
},
"transaction_id": "9a8b7c6d-...",
"variables": { "investment_amount": "10,000 EUR" }
}| Field | Required | Description |
|---|---|---|
workflow_id | Yes | The contract flow to send. Archived flows (or flows on an archived template) are rejected. |
participant_subjects | Yes, unless user_id / business_customer_id is used | Who signs, keyed by participant key. Each entry has exactly one of user_id, business_customer_id, or external: {name, email}. Every participant except client_signing_profile ones needs an entry. |
user_id / business_customer_id | Alternative to participant_subjects | Shorthand when one person or business fills every user / business_customer participant. Pass exactly one, and do not combine with participant_subjects. Not usable when the flow has an external participant, or both user and business_customer participants. |
project_id | No | Project the contract belongs to. Fills the project_name variable. |
transaction_id | No | Payment to link for a payment gate. Can also be linked later. See Payment gate. |
variables | No | Values for template variables. Override flow defaults and system variables. |
participant_overrides | No | Per participant key: name, email, field_values (pre-filled fields), expire_after_hours (signing window for this request only). |
metadata | No | Your own key-value data, returned on the request. |
Signers
Each signer has a source, which says who fills that role:
source | Who signs | How you identify them |
|---|---|---|
user | A registered user (individual) | user_id |
business_customer | A business customer (company) | business_customer_id |
external | Anyone else, for example a guarantor | external: { "name", "email" } |
client_signing_profile | Your own company | Nothing; uses your signing profile |
With POST /contracts/send, every signer role on the template must be covered by exactly one signer. Each participant signs once.
Delivery
delivery | Behavior |
|---|---|
link | The signer gets a signing link. By default UrbanPay emails it. While it is that signer's turn, the link is also returned as signer_url on the participant (and as active_signing_url on the request), so you can show it in your own app instead (set email_notifications.invitation to false). When several people sign at the same time, read each one's participants[].signer_url. |
autosign | Your company signs automatically with the signing profile. Only for client_signing_profile signers. |
With POST /contracts/send the delivery is chosen for you: autosign for client_signing_profile, link for everyone else.
Signing order
Stages run in order of index, starting at 1 with no gaps. Stages that share the same index run at the same time (parallel signing). With POST /contracts/send, signers sign in list order; set parallel_with_previous: true on a signer to let them sign together with the one before.
Signing window
expire_after_hours (1 to 2160) gives a signer a deadline that starts when it becomes their turn. If they miss it, the contract moves to expired. Leave it out for no deadline. Signers who sign at the same time must share the same window, and it cannot be set on auto-signing signers. Override it for a single request with participant_overrides.{key}.expire_after_hours.
Signing profile (auto-sign)
Before any autosign stage can run, set up your signing profile once with PUT /api/v1/contracts/signing-profile: a display name, a signer email and a signature image (initials image optional). Without a usable profile, sending with a client_signing_profile signer fails: POST /contracts/send returns 422, and creating a contract flow or contract request returns 400 (also when the profile has no signature image).
Payment gate
Add a wait_transaction_success stage to hold the contract until a payment succeeds, for example "investor signs, pays, then the company counter-signs". With POST /contracts/send, pass "payment_gate": { "after_role": "Investor" }.
- Link the payment with
transaction_idwhen sending, or later withPOST /api/v1/contracts/requests/{id}/bind-transaction. - While no payment is linked the request is
awaiting_transaction_binding; once linked but not yet successful it isawaiting_transaction. When the payment reachessuccess, the next stage starts. - One payment funds one live contract. Linking a transaction that already belongs to another active or completed contract returns
400. A transaction freed by a canceled, declined or expired contract can be reused.
Template variables
DOCX templates can contain [[variable_name]] placeholders that are filled in when the contract is sent. The template's detected_variables lists them, and variables_fillable tells you whether this template supports filling them. Values are merged in this order, later wins:
- System variables, filled automatically (below).
- Contract flow defaults (
variableson the flow). - Request values (
variableson the send or request call).
System variables
Always available:
| Variable | Value |
|---|---|
client_name, client_legal_name | Your company name |
client_email | Your company email |
project_name | Name of the linked project, when project_id is given |
contract_date | Date the contract was created (UTC, YYYY-MM-DD) |
Filled when the contract has exactly one registered signer (a user or a business customer):
| Signer is a user | Signer is a business customer |
|---|---|
subject_type = user | subject_type = business |
subject_name, subject_email | subject_name, subject_email |
investor_name, investor_full_name, investor_email | business_legal_name, business_registration_number |
user_full_name, user_email | business_country, business_email |
With several registered signers, or external signers only, pass these values yourself in variables.
Emails and CC recipients
email_notifications on a contract flow (or on POST /contracts/send) controls the emails UrbanPay sends:
| Field | Default | Description |
|---|---|---|
invitation | true | Email the signing link when a signer's turn starts |
completed / declined / expired | true | Notify participants when the contract ends that way |
completed_attach_document | true | Attach the signed PDF to the completion email |
completed_attach_audit_log | false | Attach the audit trail to the completion email |
completed_extra_emails | [] | Up to 10 more addresses that receive the completion email |
cc_emails | [] | Up to 10 view-only recipients. Each gets a read-only link when the contract is sent, plus the completed/declined/expired emails above. They cannot sign. |
cc_view_link_days | 30 | Days the CC links keep working after the contract ends (1 to 365). Canceling closes them at once. |
The request lists its CC recipients under cc_recipients, each with its view_url and view_expires_at.
Statuses
Contract request
| Status | Meaning |
|---|---|
created | Recorded, about to start the first stage |
awaiting_signature | Waiting for one or more signers |
awaiting_transaction_binding | Reached a payment gate and no payment is linked yet |
awaiting_transaction | Payment linked, waiting for it to succeed |
completed | Everyone signed. The signed PDF and audit trail are available. Final. |
declined | A signer declined. Final. |
canceled | You canceled it. Final. |
expired | A signer missed their signing window. Final. |
Participant
| Status | Meaning |
|---|---|
created | Added to the contract, not yet scheduled |
pending | Waiting for an earlier stage to finish |
sent | Their turn: the signing link is live |
opened | Opened the signing link |
completed | Signed |
declined | Declined to sign |
canceled | The contract was canceled before they signed |
expired | The contract expired before they signed (their own signing window, or an earlier signer's, ran out) |
Webhooks
Subscribe to these events on your webhook destination. They use the standard event envelope described in the Webhook event catalog; the fields below are in data.
| Event | When | data fields |
|---|---|---|
contract.request.status_changed | The request status changes | contract_request_id, request_status, current_stage_index, current_participant_key |
contract.participant.status_changed | A signer's status changes | contract_request_id, participant_id, participant_key, participant_status, signing_submitter_id |
contract.request.completed | Everyone signed | contract_request_id, completed_at |
At most one event is emitted per status, but a delivery can be retried, so make your handler idempotent. Fetch the request for the full picture.
Getting the signed document
Available once the request is completed (earlier calls return 409):
GET /api/v1/contracts/requests/{id}/document: the signed PDF.GET /api/v1/contracts/requests/{id}/audit-log: the audit trail (certificate of signature) PDF.POST /api/v1/contracts/requests/{id}/document-links: a download URL that needs noAuthorizationheader and expires after 5 minutes, for tools that fetch a file by URL (for example an attachment field in a spreadsheet or no-code tool).
Endpoint map
| Area | Endpoints |
|---|---|
| Send | POST /contracts/send, POST /contracts/requests |
| Track | GET /contracts/requests, GET /contracts/requests/{id}, GET /contracts/requests/summary |
| Manage a request | POST .../{id}/cancel, POST .../{id}/bind-transaction, POST .../{id}/reconcile, DELETE .../{id}/cc-recipients |
| Signed files | GET .../{id}/document, GET .../{id}/audit-log, POST .../{id}/document-links |
| Templates | POST/GET /contracts/templates, GET/DELETE /contracts/templates/{id}, POST .../{id}/builder-session, POST .../{id}/refresh, GET .../{id}/preview, POST .../{id}/archive, POST .../{id}/unarchive |
| Contract flows | POST/GET /contracts/workflows, GET/PUT/DELETE /contracts/workflows/{id}, POST .../{id}/archive, POST .../{id}/unarchive |
| Signing profile | GET/PUT /contracts/signing-profile, DELETE .../signature-image, DELETE .../initials-image |
| Dashboard only | POST .../{id}/participants/{participant_id}/resend-invitation, POST .../{id}/resend-completion-email (not available to API credentials) |
Templates and contract flows that are already used by a sent contract cannot be deleted; archive them instead.
Errors
Authenticated contract endpoints return 403 when contract signing is not enabled for your account. Endpoint-specific errors are listed on each endpoint page; 401, 403 (permission or role) and 429 are described in the Error reference.