Contracts API Reference

Access and track agreements, terms, pricing, and signature status for contracts inside your Hermon workspace.

List Contracts

Retrieve a paginated list of contracts. Results can be filtered by status, lead, and assigned setter, closer, or triager.

GET/api/external/contracts

Query Parameters

Parameter	Type	Required	Description
page	integer	Optional	Page number for pagination. Default: 1
limit	integer	Optional	Number of items per page. Default: 10, Max: 100
status	string	Optional	Filter by contract status (e.g. DRAFT, SENT, VIEWED, SIGNED, VOIDED, WITHDRAWN).
setter	string	Optional	Filter by assigned setter email.
closer	string	Optional	Filter by assigned closer email.
triage	string	Optional	Filter by assigned triager email.
lead_id	string (UUID)	Optional	Filter by associated lead UUID.

Code Examples

curl -X GET "https://api.hermon.io/api/external/contracts?page=1&limit=10&status=VOIDED&setter=sales-setter@mailinator.com&closer=hermon@mailinator.com&triage=triager@mailinator.com&lead_id=e799c30f-9da7-4fd7-9552-83b96a9bfac2" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_your_key_here"

Response Example

json

{
  "status": "success",
  "message": "Contracts fetched successfully",
  "data": [
    {
      "id": "d5e0fb5d-5b14-45cf-81d8-2a0eb7a49224",
      "lead": {
        "id": "21775958-3969-4172-97c9-4a4d44d5e856",
        "first_name": "George",
        "last_name": null,
        "email": "georgeableson@aol.com"
      },
      "program": {
        "name": "Larges Transactions"
      },
      "total_amount": 5000,
      "collected_amount": 0,
      "next_due_date": "2026-06-14T04:30:00.000Z",
      "closer": {
        "first_name": "Mitul",
        "last_name": "Kanani",
        "profile_image_url": "https://img.clerk.com/eyJ0eXBlIjoicHJveHkiLCJzcmMiOiJodHRwczovL2ltYWdlcy5jbGVyay5kZXYvdXBsb2FkZWQvaW1nXzM5cUpIazFNeG5haHkxUWVGWFpYZXlodElLbiJ9",
        "id": "user_39btCx7wm2Vwgr2eHmhRLxNanxI",
        "role": "org:owner"
      },
      "setter": {
        "first_name": "sale",
        "last_name": "satter",
        "profile_image_url": "https://img.clerk.com/eyJ0eXBlIjoiZGVmYXVsdCIsImlpZCI6Imluc18zN0lDNG9PRFg5cEdnYzdHOEdZa3ZObXJXRloiLCJyaWQiOiJ1c2VyXzNBWXExakpNRFZkSGtxdGEyVGpnbGVnUUx3eCIsImluaXRpYWxzIjoiU1MifQ",
        "id": "user_3AYq1jJMDVdHkqta2TjglegQLwx",
        "role": "org:sales_setter"
      },
      "triager": {
        "first_name": "triager",
        "last_name": "hermon",
        "profile_image_url": "https://img.clerk.com/eyJ0eXBlIjoiZGVmYXVsdCIsImlpZCI6Imluc18zN0lDNG9PRFg5cEdnYzdHOEdZa3ZObXJXRloiLCJyaWQiOiJ1c2VyXzNEWnFMUDh4SmJCOVZFSU1jRHl5VmZ5d1U0eSIsImluaXRpYWxzIjoiVEgifQ",
        "id": "user_3DZqLP8xJbB9VEIMcDyyVfywU4y",
        "role": "org:triager"
      },
      "currency": "usd",
      "contract_status": "VOIDED",
      "contract_type": "PP",
      "subscription_status": null,
      "to_be_collected": 5000,
      "created_at": "2026-05-14T11:34:06.740Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 13,
    "totalPages": 2,
    "hasNext": true,
    "hasPrev": false
  }
}

Get Contract Details

Fetch detailed information for a single contract by its unique UUID.

GET/api/external/contracts/:id

Path Parameters

:idRequired. The unique contract UUID.

Contract Object Fields

Field	Type	Description
id	string (UUID)	Unique identifier for the contract.
created_with_template	boolean	Whether the contract was created using a template [Details API Only].
currency	string	ISO 4217 currency code (e.g. usd, eur).
lead	object	Associated lead summary details (id, first_name, last_name, email, and optionally phone_country, phone_e164, sales_status).
program	object	Associated program summary details (name, and details like id, template_name, price, type, co_signer).
closer	object \| null	Assigned closer summary details.
setter	object \| null	Assigned setter summary details.
triager	object \| null	Assigned triager summary details.
contract_status	string	Current state of the contract (e.g. DRAFT, SENT, VIEWED, SIGNED, VOIDED, WITHDRAWN) [List API Only].
contract_type	string	Billing type structure (e.g. PP, PIF, SUBSCRIPTION) [List API Only].
status	string	Current state of the contract (e.g. DRAFT, SENT, VIEWED, SIGNED, VOIDED, WITHDRAWN) [Details API Only].
type	string	Billing type structure (e.g. PP, PIF, SUBSCRIPTION) [Details API Only].
total_amount	number	Total contract amount [List API Only].
collected_amount	number	Aggregated paid transaction amount.
to_be_collected	number \| null	Remaining contract value to collect [List API Only].
total_value	number	Total financial contract value [Details API Only].
remaining_amount	number	Remaining balance to be paid [Details API Only].
next_due_date	string \| null	ISO 8601 timestamp of next planned installment payment [List API Only].
subscription_status	string \| null	Status of active recurring subscription if applicable.
voided_at	string \| null	ISO 8601 timestamp when contract was voided [Details API Only].
voided_reason	string \| null	Text explanation of void status [Details API Only].
voided_by_details	object \| null	Summary details of user who voided the contract [Details API Only].
payments	array	Scheduled/paid transactions linked to this contract (id, type, amount, date, status, payment_provider, is_mandate_payment, active_payment_link) [Details API Only].
notes	string \| null	Custom internal contract notes [Details API Only].
sign_page_url	string \| null	Direct page link for lead to sign the contract [Details API Only].
esign_preview_pdf_url	string \| null	PDF generated document preview link [Details API Only].
created_at	string	ISO 8601 timestamp of contract creation.
updated_at	string	ISO 8601 timestamp of last modification [Details API Only].

Code Examples

curl -X GET "https://api.hermon.io/api/external/contracts/d5e0fb5d-5b14-45cf-81d8-2a0eb7a49224" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_your_key_here"

Response Example

json

{
  "status": "success",
  "message": "Contract fetched successfully",
  "data": {
    "id": "d5e0fb5d-5b14-45cf-81d8-2a0eb7a49224",
    "created_with_template": true,
    "currency": "usd",
    "lead": {
      "id": "21775958-3969-4172-97c9-4a4d44d5e856",
      "first_name": "George",
      "last_name": null,
      "email": "georgeableson@aol.com",
      "phone_country": "GB",
      "phone_e164": "+447851607407",
      "sales_status": {
        "id": "bf2a1bad-4a98-4cae-838e-6e58f9c0d7cc",
        "name": "Won",
        "text_color": "#0BD050",
        "bg_color": "#E9FBF0"
      }
    },
    "status": "VOIDED",
    "signed_at": null,
    "voided_at": "2026-05-14T11:48:22.300Z",
    "voided_reason": "hfggh",
    "voided_by_details": {
      "first_name": "Mitul",
      "last_name": "Kanani",
      "profile_image_url": "https://img.clerk.com/eyJ0eXBlIjoicHJveHkiLCJzcmMiOiJodHRwczovL2ltYWdlcy5jbGVyay5kZXYvdXBsb2FkZWQvaW1nXzM5cUpIazFNeG5haHkxUWVGWFpYZXlodElLbiJ9",
      "id": "user_39btCx7wm2Vwgr2eHmhRLxNanxI",
      "role": "org:owner"
    },
    "type": "PP",
    "closer": {
      "first_name": "Mitul",
      "last_name": "Kanani",
      "profile_image_url": "https://img.clerk.com/eyJ0eXBlIjoicHJveHkiLCJzcmMiOiJodHRwczovL2ltYWdlcy5jbGVyay5kZXYvdXBsb2FkZWQvaW1nXzM5cUpIazFNeG5haHkxUWVGWFpYZXlodElLbiJ9",
      "id": "user_39btCx7wm2Vwgr2eHmhRLxNanxI",
      "role": "org:owner"
    },
    "setter": {
      "first_name": "sale",
      "last_name": "satter",
      "profile_image_url": "https://img.clerk.com/eyJ0eXBlIjoiZGVmYXVsdCIsImlpZCI6Imluc18zN0lDNG9PRFg5cEdnYzdHOEdZa3ZObXJXRloiLCJyaWQiOiJ1c2VyXzNBWXExakpNRFZkSGtxdGEyVGpnbGVnUUx3eCIsImluaXRpYWxzIjoiU1MifQ",
      "id": "user_3AYq1jJMDVdHkqta2TjglegQLwx",
      "role": "org:sales_setter"
    },
    "triager": {
      "first_name": "triager",
      "last_name": "hermon",
      "profile_image_url": "https://img.clerk.com/eyJ0eXBlIjoiZGVmYXVsdCIsImlpZCI6Imluc18zN0lDNG9PRFg5cEdnYzdHOEdZa3ZObXJXRloiLCJyaWQiOiJ1c2VyXzNEWnFMUDh4SmJCOVZFSU1jRHl5VmZ5d1U0eSIsImluaXRpYWxzIjoiVEgifQ",
      "id": "user_3DZqLP8xJbB9VEIMcDyyVfywU4y",
      "role": "org:triager"
    },
    "program": {
      "id": "f81af254-bedf-41d2-ba37-840099bc8bc4",
      "name": "Larges Transactions",
      "notes": null,
      "template_name": "Sample Service Agreement",
      "price": 5,
      "type": "ONE_TIME",
      "co_signer": null
    },
    "total_value": 5000,
    "collected_amount": 0,
    "remaining_amount": 0,
    "payments": [
      {
        "id": "32d6bd06-1a03-4584-8760-44140d821452",
        "type": "FIRST_PAYMENT",
        "amount": 1000,
        "date": "2026-05-14T04:30:00.000Z",
        "status": "FAILED",
        "payment_provider": "MOLLIE",
        "is_mandate_payment": false,
        "active_payment_link": null
      },
      {
        "id": "1594bb79-7170-44ba-8dff-8fd8bda7dade",
        "type": "DEPOSIT",
        "amount": 1000,
        "date": "2026-05-13T04:30:00.000Z",
        "status": "LOST",
        "payment_provider": "MOLLIE",
        "is_mandate_payment": false,
        "active_payment_link": null
      },
      {
        "id": "d558cf40-7cdf-486d-8c9b-641270f50892",
        "type": "INSTALMENT",
        "amount": 1500,
        "date": "2026-06-14T04:30:00.000Z",
        "status": "LOST",
        "payment_provider": "MOLLIE",
        "is_mandate_payment": true,
        "active_payment_link": null
      },
      {
        "id": "4f019f3a-af14-4419-8aa8-de454beae75d",
        "type": "INSTALMENT",
        "amount": 1500,
        "date": "2026-07-14T04:30:00.000Z",
        "status": "LOST",
        "payment_provider": "MOLLIE",
        "is_mandate_payment": true,
        "active_payment_link": null
      }
    ],
    "notes": null,
    "sign_page_url": null,
    "esign_preview_pdf_url": null,
    "created_at": "2026-05-14T11:34:06.740Z",
    "updated_at": "2026-05-14T11:48:22.308Z"
  }
}

Error Responses

401Missing or invalid API key

json

{
  "status": "error",
  "message": "Invalid or revoked API key"
}

404Resource not found

json

{
  "status": "error",
  "message": "Resource not found"
}

429Rate limit exceeded

json

{
  "status": "error",
  "message": "Too many requests"
}