Customers

A Customer is a buyer record scoped to your business. Customer ids are HL Hunt record ids: 25-character strings that start with the letter c (for example c1m9k2x7e0001qz8f4h2b6n3p) with no cus_ or cust_ prefix. Every create and retrieve response carries the id in the id field; there is no customer_id field on the customer object. Saved cards and bank accounts link to a customer through customer_id on POST /v1/payment-methods or by paying through a Checkout Session.

POST
/v1/customers

Create a Customer

Create a customer. Only name is required.

Request body

FieldTypeRequiredDescription
namestringrequiredNon-empty. Trimmed.
emailstringoptionalBuyer email.
phonestringoptionalBuyer phone.
companystringoptionalCompany name.
addressobjectoptionalFree-form address object, stored as given.
metadataobjectoptionalYour own keys and values, stored as given and returned on retrieve.

Response

FieldTypeDescription
idstringCustomer id (c… record id). Use it as customer_id elsewhere.
objectstring"customer".
name / email / phone / companystring | nullAs stored.
createdstringISO 8601.
metadataobjectAs sent, or {}.
  • HTTP 201. 400 missing_required_param when name is missing or blank.
  • Emits customer.created.
curl -X POST https://api.hlhunt.org/v1/customers \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jenny Rosen",
    "email": "jenny@example.com",
    "phone": "+1-555-555-5555",
    "company": "Acme Inc",
    "metadata": { "crm_id": "A-1001" }
  }'
GET
/v1/customers

List Customers

Paginated list of the business's customers.

Parameters

FieldTypeRequiredDescription
limitinteger (query)optional1–100, default 25.
offsetinteger (query)optionalRows to skip, default 0.
searchstring (query)optionalFree-text match on the customer record.

Response

FieldTypeDescription
objectstring"list".
dataarray{ id, object, name, email, phone, company, created }.
totalintegerTotal matching customers.
has_morebooleanoffset + limit < total.
curl -X GET "https://api.hlhunt.org/v1/customers?limit=20&offset=0" \
  -H "Authorization: Bearer sk_live_your_api_key"
GET
/v1/customers/{customer_id}

Retrieve a Customer

Fetch one customer. Includes address, updated and metadata, which the list omits.

Parameters

FieldTypeRequiredDescription
customer_idstring (path)requiredThe customer's id.

Response

FieldTypeDescription
id / object / name / email / phone / companyAs on create.
addressobject | nullAs stored.
created / updatedstringISO 8601.
metadataobjectAs stored, or {}.
  • 404 resource_not_found when the customer is unknown or belongs to another business.
curl -X GET https://api.hlhunt.org/v1/customers/c1m9k2x7e0001qz8f4h2b6n3p \
  -H "Authorization: Bearer sk_live_your_api_key"
PUT
/v1/customers/{customer_id}

Update a Customer

Update any of the writable fields. Only the fields you send change.

Request body

FieldTypeRequiredDescription
namestringoptionalNon-empty if sent (400 invalid_param otherwise).
email / phone / companystringoptionalSend an empty string to clear.
addressobjectoptionalReplaces the stored address.
metadataobjectoptionalReplaces the stored metadata (not merged).
notesstringoptionalInternal notes shown in the dashboard.

Response

FieldTypeDescription
(customer object)Same shape as GET /v1/customers/{customer_id}.
  • 400 missing_required_param when the body is empty or has no writable field · 404 resource_not_found.
  • Emits customer.updated.
curl -X PUT https://api.hlhunt.org/v1/customers/c1m9k2x7e0001qz8f4h2b6n3p \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+1-555-000-1234", "metadata": { "crm_id": "A-1001", "tier": "gold" } }'