Core resources

Clients

A client is a customer you bill. Create them, read one back, or list them — newest first.

Create a client#

POST/v1/clients

Creates a client in your workspace.

Field	Type	Description
namereq	string	The client's display name.
email	string	Email address. Requires `emailConsent: true`.
phone	string	Phone in any format; normalized to E.164. Requires `smsConsent: true`.
company	string	Optional company name.
usageType	"consumer" \| "commercial"	Determines the applicable usury cap. Defaults to consumer.
address	object	Optional. `line1`, `line2`, `city`, `state` (2-letter), `postalCode`, `country`.
timezone	string	IANA timezone, e.g. America/New_York.
notes	string	Free-form internal notes.
emailConsent	boolean	Attest you have permission to email this client. Required when email is set.
smsConsent	boolean	Attest you have TCPA-compliant SMS consent. Required when phone is set.

Consent is enforced: sending an email without emailConsent: true (or a phone without smsConsent: true) returns 422 validation_failed. Consent supplied here is recorded as imported evidence.

Request

curl https://paytrum.com/api/v1/clients \
  -H "Authorization: Bearer ak_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Co",
    "email": "ar@acme.com",
    "emailConsent": true,
    "usageType": "commercial"
  }'

201 Created

{
  "object": "client",
  "id": "66f1a2b3c4d5e6f7a8b9c0d1",
  "name": "Acme Co",
  "company": null,
  "email": "ar@acme.com",
  "phone": null,
  "usageType": "commercial",
  "status": "active",
  "address": { "line1": null, "line2": null, "city": null, "state": null, "postalCode": null, "country": null },
  "timezone": "America/New_York",
  "notes": null,
  "emailConsent": true,
  "smsConsent": false,
  "createdAt": "2026-06-09T17:04:21.000Z",
  "updatedAt": "2026-06-09T17:04:21.000Z"
}

The client object#

Field	Type	Description
id	string	Unique client id.
name / company / email / phone	string \| null	Contact fields you supplied.
usageType	"consumer" \| "commercial"	As set on create.
status	"active" \| "inactive"	Inactive = archived.
address	object	Structured address (camelCase fields, nulls when unset).
emailConsent / smsConsent	boolean	Whether consent is on file for each channel.
createdAt / updatedAt	string	ISO-8601 timestamps.

Retrieve a client#

GET/v1/clients/{id}

curl https://paytrum.com/api/v1/clients/66f1a2b3c4d5e6f7a8b9c0d1 \
  -H "Authorization: Bearer ak_live_your_key"

Returns 404 not_found if no client with that id exists in your workspace.

List clients#

GET/v1/clients

Cursor-paginated, newest first. Query params: limit (1–100, default 25), startingAfter (an id), and status (active or inactive).

curl "https://paytrum.com/api/v1/clients?limit=50&status=active" \
  -H "Authorization: Bearer ak_live_your_key"

{
  "object": "list",
  "data": [ { "object": "client", "id": "…", "name": "Acme Co" } ],
  "hasMore": false
}