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

Concept	Description
Template	A DOCX document uploaded to the platform containing `[[variable]]` placeholders and defined signature roles
Workflow	A published, reusable signing configuration that defines participants and the sequence of stages
Contract Request	A single signing instance created from a workflow for a specific user and project
Participant	A signer within the workflow — either the end user (investor) or the client's own signing profile
Stage	A single step in the workflow sequence — either a signature step or a transaction wait step

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": "john@example.com",
      "phone": "+1234567890"
    }
  },
  "metadata": {}
}

Field	Required	Description
`workflow_id`	✅	ID of a published workflow
`user_id`	✅	ID of the investor/end user
`project_id`	✅	ID of the associated project
`transaction_id`	❌	Payment transaction to link. Can also be bound later via `POST /api/v1/contracts/requests/{id}/bind-transaction`
`variables`	❌	Custom template variables. Merged with system-injected values (see below)
`participant_overrides`	❌	Override name, email, phone, or field values per participant key
`metadata`	❌	Arbitrary key-value metadata attached to the request

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)

Variable	Source
`client_name`	Client display name
`client_legal_name`	Client legal name
`client_email`	Client email
`investor_name`	User full name or email
`investor_full_name`	User full name or email
`investor_email`	User email
`user_full_name`	User full name or email
`user_email`	User email
`project_name`	Project name
`contract_date`	Current UTC date (ISO format)

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:

Source	Description
`user`	The end user (investor). Signing link is delivered to them
`client_signing_profile`	The client's own signing identity. Used for auto-signing

Stage Types

`signature`

A signing step assigned to one participant.

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

`delivery`	Behavior
`link`	A signing link is sent to the participant. The workflow pauses until they complete it
`autosign`	The system automatically signs on behalf of the client using the configured Client Signing Profile

`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:

You call POST /api/v1/contracts/requests with the workflow ID and the investor's user ID.
The investor receives a signing link and completes their signature.
The system immediately auto-signs on behalf of the client — no manual action required.
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

Status	Description
`pending`	Request created, workflow advancing
`awaiting_signature`	Waiting for a participant to sign
`awaiting_transaction_binding`	A `wait_transaction_success` stage reached but no transaction is linked yet
`awaiting_transaction`	Transaction is linked but has not yet reached `success`
`completed`	All stages finished successfully
`declined`	A participant declined to sign
`canceled`	Canceled by the client
`expired`	Signing link expired before completion

Webhook Events

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

Event	Trigger
`contract.request.status_changed`	Request status changes
`contract.request.completed`	All stages completed successfully
`contract.participant.status_changed`	A participant's signing status changes

Other Endpoints

Method	Endpoint	Description
`GET`	`/api/v1/contracts/requests`	List contract requests
`GET`	`/api/v1/contracts/requests/{id}`	Get a single contract request
`POST`	`/api/v1/contracts/requests/{id}/bind-transaction`	Link a transaction after request creation
`POST`	`/api/v1/contracts/requests/{id}/cancel`	Cancel a request
`PUT`	`/api/v1/contracts/signing-profile`	Configure the client signing profile

Error Responses

Status Code	Description
`400`	Invalid request payload, unknown workflow, or misconfigured stage
`401`	Unauthorized — missing or invalid access token
`403`	Insufficient role for the requested operation
`404`	Workflow, user, or project not found
`409`	Duplicate contract request or state conflict