Contracts Signing

UrbanpayX (UrbanSign) provides a contract signing feature that allows clients to send, collect, and manage signed documents from their investors. The system supports multi-stage workflows, automatic variable injection, and optional payment gating.

Core Concepts

Endpoint

Create a Contract Request

POST /api/v1/contracts/requests
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "workflow_id": "uuid",
  "user_id": "uuid",
  "project_id": "uuid",
  "transaction_id": "uuid|null",
  "variables": {
    "custom_variable": "value"
  },
  "participant_overrides": {
    "investor": {
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+1234567890"
    }
  },
  "metadata": {}
}

Template Variables

Variables replace [[variable_name]] placeholders inside your DOCX template during signing. They are resolved from three layers in the following priority order:

system variables  ←  automatically injected
      +
workflow variables  ←  defined in the workflow definition
      +
request variables  ←  passed in the API call  (highest priority)

System Variables (auto-injected, no action required)

Any additional [[variable]] defined in your template that is not in the list above must be passed in the variables field of the API call.

Workflows & Stages

A workflow defines the participants and the ordered sequence of stages that must be completed to fulfill a contract request.

Participants

Each participant has a key (unique identifier within the workflow) and a source:

Stage Types

signature

A signing step assigned to one participant.

{
  "index": 0,
  "type": "signature",
  "participant": "investor",
  "delivery": "link"
}

wait_transaction_success

Pauses the workflow until the linked transaction reaches success status. Can be placed at any position in the stage sequence. Omit this stage entirely if payment gating is not required.

{
  "index": 1,
  "type": "wait_transaction_success"
}

Execution Flow

Stages execute sequentially. Each stage must complete before the next begins. If a participant declines or the transaction fails, the request moves to a terminal state.

Common Use Case: Investor Signs, Client Auto-Signs

The simplest recommended workflow — the investor signs via link, and the client counter-signs automatically:

Workflow Definition

{
  "participants": [
    {
      "key": "investor",
      "source": "user",
      "docuseal_role": "Investor"
    },
    {
      "key": "client",
      "source": "client_signing_profile",
      "docuseal_role": "Company"
    }
  ],
  "stages": [
    {
      "index": 0,
      "type": "signature",
      "participant": "investor",
      "delivery": "link"
    },
    {
      "index": 1,
      "type": "signature",
      "participant": "client",
      "delivery": "autosign"
    }
  ]
}

How it works:

1. You call POST /api/v1/contracts/requests with the workflow ID and the investor's user ID.
2. The investor receives a signing link and completes their signature.
3. The system immediately auto-signs on behalf of the client — no manual action required.
4. The request status moves to completed and a contract.request.completed webhook event is fired.

Prerequisite for auto-sign: A Client Signing Profile must be configured via PUT /api/v1/contracts/signing-profile with a display name, signer email, and signature image before auto-sign stages can execute.

If counter-signing by the client is not needed, simply remove stage index 1 from the workflow.

Contract Request Statuses

Webhook Events

The following events are emitted during the lifecycle of a contract request. See the Webhooks documentation for payload schemas.

Other Endpoints

Error Responses