Contracts Signing

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

ConceptWhat it is
TemplateAn uploaded PDF or DOCX with signer roles and fields placed on it. Reusable.
Contract flowA saved, reusable signing setup for one template: who signs, in what order, payment gate, emails. Called workflow in the API paths (/contracts/workflows).
Contract requestOne contract sent to specific people. Created from a contract flow, or directly with POST /contracts/send.
ParticipantA signer on a contract request, with its own status and signing link.
Signing profileYour company's own signature identity, used to counter-sign automatically.
CC recipientSomeone 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/sendContract flow + POST /contracts/requests
Best forOne-off contracts, or getting startedThe same contract sent many times
Calls per contract11 (after creating the flow once)
SignersListed inline in signersDefined once as participants; the people are supplied per request
ReusePass save_as_flow: true to keep the setup as a contract flowBuilt 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" }
}
FieldRequiredDescription
workflow_idYesThe contract flow to send. Archived flows (or flows on an archived template) are rejected.
participant_subjectsYes, unless user_id / business_customer_id is usedWho 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_idAlternative to participant_subjectsShorthand 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_idNoProject the contract belongs to. Fills the project_name variable.
transaction_idNoPayment to link for a payment gate. Can also be linked later. See Payment gate.
variablesNoValues for template variables. Override flow defaults and system variables.
participant_overridesNoPer participant key: name, email, field_values (pre-filled fields), expire_after_hours (signing window for this request only).
metadataNoYour own key-value data, returned on the request.

Signers

Each signer has a source, which says who fills that role:

sourceWho signsHow you identify them
userA registered user (individual)user_id
business_customerA business customer (company)business_customer_id
externalAnyone else, for example a guarantorexternal: { "name", "email" }
client_signing_profileYour own companyNothing; 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

deliveryBehavior
linkThe 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.
autosignYour 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_id when sending, or later with POST /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 is awaiting_transaction. When the payment reaches success, 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:

  1. System variables, filled automatically (below).
  2. Contract flow defaults (variables on the flow).
  3. Request values (variables on the send or request call).

System variables

Always available:

VariableValue
client_name, client_legal_nameYour company name
client_emailYour company email
project_nameName of the linked project, when project_id is given
contract_dateDate 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 userSigner is a business customer
subject_type = usersubject_type = business
subject_name, subject_emailsubject_name, subject_email
investor_name, investor_full_name, investor_emailbusiness_legal_name, business_registration_number
user_full_name, user_emailbusiness_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:

FieldDefaultDescription
invitationtrueEmail the signing link when a signer's turn starts
completed / declined / expiredtrueNotify participants when the contract ends that way
completed_attach_documenttrueAttach the signed PDF to the completion email
completed_attach_audit_logfalseAttach 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_days30Days 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

StatusMeaning
createdRecorded, about to start the first stage
awaiting_signatureWaiting for one or more signers
awaiting_transaction_bindingReached a payment gate and no payment is linked yet
awaiting_transactionPayment linked, waiting for it to succeed
completedEveryone signed. The signed PDF and audit trail are available. Final.
declinedA signer declined. Final.
canceledYou canceled it. Final.
expiredA signer missed their signing window. Final.

Participant

StatusMeaning
createdAdded to the contract, not yet scheduled
pendingWaiting for an earlier stage to finish
sentTheir turn: the signing link is live
openedOpened the signing link
completedSigned
declinedDeclined to sign
canceledThe contract was canceled before they signed
expiredThe 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.

EventWhendata fields
contract.request.status_changedThe request status changescontract_request_id, request_status, current_stage_index, current_participant_key
contract.participant.status_changedA signer's status changescontract_request_id, participant_id, participant_key, participant_status, signing_submitter_id
contract.request.completedEveryone signedcontract_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 no Authorization header 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

AreaEndpoints
SendPOST /contracts/send, POST /contracts/requests
TrackGET /contracts/requests, GET /contracts/requests/{id}, GET /contracts/requests/summary
Manage a requestPOST .../{id}/cancel, POST .../{id}/bind-transaction, POST .../{id}/reconcile, DELETE .../{id}/cc-recipients
Signed filesGET .../{id}/document, GET .../{id}/audit-log, POST .../{id}/document-links
TemplatesPOST/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 flowsPOST/GET /contracts/workflows, GET/PUT/DELETE /contracts/workflows/{id}, POST .../{id}/archive, POST .../{id}/unarchive
Signing profileGET/PUT /contracts/signing-profile, DELETE .../signature-image, DELETE .../initials-image
Dashboard onlyPOST .../{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.