Programs API Reference

Fetch details of sales programs, template configurations, pricing structures, and signing redirects.

Date & Timezone Handling: All timestamps in responses are UTC, formatted as ISO 8601 (2026-01-15T10:30:00.000Z). Date-range filters accept either date-only YYYY-MM-DD (which expands to UTC day boundaries) or full ISO 8601 timestamps.
Amounts: All monetary values are in major currency units (e.g. 2997.00 for $2,997). The currency field is returned as an ISO 4217 code (e.g. USD, EUR).

List Programs

Retrieve a paginated list of programs. Results can be filtered by name search, archive status, billing type, and modification date.

GET/api/external/programs

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
search	string	Optional	Case-insensitive substring match on the program name.
is_archived	boolean	Optional	Filter by archived state. Accepts "true" or "false". Omit to return both.
payment_type	string	Optional	Filter by payment type. See Payment Type Values.
created_from	string	Optional	Lower bound for created_at. Accepts YYYY-MM-DD or ISO 8601.
created_to	string	Optional	Upper bound for created_at. Accepts YYYY-MM-DD or ISO 8601.
updated_from	string	Optional	Lower bound for updated_at. Same format rules as created_from.
updated_to	string	Optional	Upper bound for updated_at. Same format rules as created_to.

Code Examples

curl -X GET "https://api.hermon.io/api/external/programs?page=1&limit=10&search=Prosacco&is_archived=true&payment_type=ONE_TIME" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_your_key_here"

Response Example

json

{
  "success": true,
  "message": "Programs fetched successfully",
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "12-Week Coaching Program",
      "price": 2997.0,
      "currency": "USD",
      "program_type": "ONE_TIME",
      "billing_interval": null,
      "billing_period": null,
      "commission_rate": null,
      "notes": "Includes weekly calls and accountability check-ins.",
      "is_archived": false,
      "send_without_payment": false,
      "co_signer_type": "NONE",
      "co_signer": null,
      "template_id": "tpl_abc123",
      "template_name": "Standard Coaching Contract",
      "contract_language": "ENGLISH",
      "confirmation_url": "https://example.com/thank-you",
      "confirmation_payment_types": ["FIRST_PAYMENT"],
      "duration_days": 84,
      "has_engagement": true,
      "created_at": "2026-01-15T10:30:00.000Z",
      "updated_at": "2026-03-22T14:45:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1,
    "hasNext": false,
    "hasPrev": false
  }
}

Get Program Details

Fetch detailed information for a single program configuration by its unique UUID.

GET/api/external/programs/:id

Path Parameters

:idRequired. The unique program UUID.

Program Object Fields

Field	Type	Description
id	string (UUID)	Unique identifier for the program.
name	string	Display name of the program.
price	number	Price in major currency units (e.g. 2997.00 for $2,997). Converted from internal minor units using organization base currency.
currency	string \| null	ISO 4217 currency code (e.g. "USD", "EUR"). Present when a base currency is configured.
program_type	string (enum)	Payment structure. See Payment Type Values.
billing_interval	string (enum) \| null	Subscription billing cadence. null for non-subscription programs. See Billing Interval Values.
billing_period	string (enum) \| null	Contract billing period. null when not applicable. See Billing Interval Values.
commission_rate	number \| null	Commission percentage (0–100). Present only when program_type is COMMISSION.
notes	string \| null	Internal notes about the program.
is_archived	boolean	Whether the program is archived and no longer actively used.
send_without_payment	boolean	When true, contracts for this program can be sent without requiring payment.
co_signer_type	string (enum)	Who co-signs contracts for this program. See Co-Signer Type Values.
co_signer	object \| null	Co-signer user details. null when co_signer_type is NONE. See Co-Signer Object.
template_id	string \| null	ID of the linked contract template.
template_name	string \| null	Name of the linked contract template.
contract_language	string (enum)	Language of the contract document. See Contract Language Values.
confirmation_url	string (URL) \| null	Custom redirect URL shown to the client after successful payment. null when not configured.
confirmation_payment_types	string[]	Payment event types that trigger the confirmation_url redirect.
duration_days	integer \| null	Program duration in days. null when no fixed duration is set.
has_engagement	boolean	When true, signing a contract automatically creates a delivery engagement.
created_at	string (ISO 8601)	UTC timestamp when the program was created.
updated_at	string (ISO 8601)	UTC timestamp when the program was last updated.

Code Examples

curl -X GET "https://api.hermon.io/api/external/programs/dbdd435a-6bd4-42d8-9814-248c0f5ca761" \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk_live_your_key_here"

Response Example

json

{
  "success": true,
  "message": "Program fetched successfully",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "12-Week Coaching Program",
    "price": 2997.0,
    "currency": "USD",
    "program_type": "ONE_TIME",
    "billing_interval": null,
    "billing_period": null,
    "commission_rate": null,
    "notes": "Includes weekly calls and accountability check-ins.",
    "is_archived": false,
    "send_without_payment": false,
    "co_signer_type": "NONE",
    "co_signer": null,
    "template_id": "tpl_abc123",
    "template_name": "Standard Coaching Contract",
    "contract_language": "ENGLISH",
    "confirmation_url": "https://example.com/thank-you",
    "confirmation_payment_types": ["FIRST_PAYMENT"],
    "duration_days": 84,
    "has_engagement": true,
    "created_at": "2026-01-15T10:30:00.000Z",
    "updated_at": "2026-03-22T14:45:00.000Z"
  }
}

Values Reference

Payment Type Values

Value	Description
ONE_TIME	Single upfront payment
SUBSCRIPTION	Recurring subscription billing
COMMISSION	Commission-based (percentage of revenue)

Billing Interval Values

Value	Description
WEEKLY	Every week
MONTHLY	Every month
QUARTERLY	Every three months
YEARLY	Every year

Co-Signer Type Values

Value	Description
NONE	No co-signer. co_signer field is null.
ASSIGNED_CLOSER	The closer assigned to the contract co-signs.
TEAM_MEMBER	A specific team member co-signs.

Contract Language Values

Value	Description
ENGLISH	Contract document in English
DUTCH	Contract document in Dutch

Nested Objects Reference

Co-Signer Object Fields

Field	Type	Description
first_name	string	First name
last_name	string	Last name
profile_image_url	string	Profile image URL (null if none)
id	string	Clerk user ID of the co-signer
role	string	Organization role

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"
}