Custom Properties

What are Custom Properties?

Custom Properties are organization-defined fields attached to Signature Requests to capture structured business data. Admins configure them once at the organization level; all users fill them during Signature Request preparation.

Two field types are available:

• text: Open-ended free-text input (e.g., a case ID, an invoice number)
• list: A predefined set of selectable options, single or multi-select (e.g., document type)

Each property can be marked as required, meaning the application blocks sending until the field is filled. This is enforced in the application only — Signature Requests created or activated via API are not blocked when required properties are missing. Properties can also be restricted to specific workspaces, so different teams only see the fields relevant to them.

Manage Custom Properties

You can manage your organization's Custom Properties using the API or from the application under Organization Settings > Signature Settings.

Custom Properties are environment-scoped: properties created in Sandbox can only be used on Sandbox Signature Requests, and properties created in Production can only be used on Production Signature Requests.

Create a Custom Property

Use POST /custom_properties with a type of text or list. The type cannot be changed after creation.

For list properties, define the selectable options in an options array. The response includes an id for each option: store these, as you will need them when setting list values on Signature Requests:

{
  "name": "Case ID",
  "type": "text"
}

{
  "name": "Document type",
  "type": "list"
  "options": [
    { "value": "Quote", "is_default": true, "position": 0 },
    { "value": "Contract", "is_default": false, "position": 1 },
    { "value": "Amendment", "is_default": false, "position": 2 }
  ]
}

Optional parameters: required, default_value (text) or is_default on options (list), workspace_ids to restrict visibility to specific workspaces.

Other endpoints

• List: GET /custom_properties (supports filtering by type and workspace_id)
• Get: GET /custom_properties/{customPropertyId}
• Update: PATCH /custom_properties/{customPropertyId}
• Delete: DELETE /custom_properties/{customPropertyId} - permanent, removes values from all existing Signature Requests

Set values on a Signature Request

Pass a custom_properties array when creating or updating a Signature Request. Use value for text properties and value_ids for list properties:

{
  "name": "NDA - John Doe",
  "delivery_mode": "email",
  "custom_properties": [
    {
      "id": "9a93d3b5-fb3b-4abf-9e70-26315b33506c",
      "value_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
    },
    {
      "id": "d4e5f6a7-b8c9-0123-defa-345678901234",
      "value": "REF-001"
    }
  ]
}

For multi-select list properties (multiple_answer_allowed: true), pass multiple IDs in value_ids.

To update values on an existing Signature Request, use PATCH /signature_requests/{signatureRequestId} with the same structure. Provided values replace existing ones; properties not included in the array are left unchanged. To clear a value: "value": null for text, "value_ids": [] for list.

Retrieve custom property values

From a single Signature Request

The custom_properties array is included in GET /signature_requests/{signatureRequestId}:

{
  "id": "...",
  "name": "NDA - John Doe",
  "status": "ongoing",
  "custom_properties": [
    {
      "id": "9a93d3b5-fb3b-4abf-9e70-26315b33506c",
      "name": "Document type",
      "type": "list",
      "value_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
      "values": ["Quote"]
    },
    {
      "id": "d4e5f6a7-b8c9-0123-defa-345678901234",
      "name": "Case ID",
      "type": "text",
      "value": "REF-001"
    }
  ]
}

Properties with no value set are omitted from the array. The same structure is included automatically in Signature Request webhook events.

From the Signature Request list

Filter Signature Requests by custom property value using query parameters on GET /signature_requests:

• Filter by text value (contains match): ?custom_property_value[contains]={customPropertyId}:{search_term}
• Filter by list option ID: ?custom_property_value_id={optionId} (repeatable, OR logic)

Custom Properties, Labels, and Metadata: which to use?

Use Labels for lightweight, flexible tagging with no admin setup required.

Use Custom Properties when you need consistent, structured data across Signature Requests: enforced field types, predefined dropdown options, required fields, and the ability to filter by value.

Use Metadata to attach technical context to a Signature Request (e.g., a CRM record ID, an internal reference) that only your system needs. Metadata is managed via its own dedicated endpoints, is not visible in the application, and cannot be filtered or searched.