Key concepts

A few rules hold for every endpoint. Read them once and the field tables make more sense.


_id and externalId

_id is Hyfin's id for the record, and every create returns it. Save it, and send it back whenever you update that record.

externalId is your own id for the record, such as your invoice or customer number. Hyfin returns it when you read the record. A write without _id that sends an externalId you already used updates that record instead of creating a new one.

Payment webhooks refer to invoices by _id only, so an integration that skips saving it cannot match a payment to its invoice.

Money is in cents

Every amount in 4.0 is a whole number of cents, in requests and in responses. Send 4599 for $45.99. Payment webhooks use cents too for sites on webhook version 4.0, the default for new sites.

Dates and timestamps

A Date field is a calendar day with no time, written YYYY-MM-DD, such as 2026-10-23. A time or time zone sent with it is dropped, not converted, so the date stays as written. Invoice responses return invoiceDate and dueDate as a timestamp at midnight UTC on that date, such as 2026-10-23T00:00:00.000Z.

A Timestamp field is a moment in time in ISO 8601, with milliseconds and a time zone: YYYY-MM-DDTHH:mm:ss.SSSZ, such as 2026-10-23T15:04:05.123Z. Responses return timestamps in UTC. The updated_after query parameter accepts only this exact format.

Who owns which record

Your software owns customers, contacts, items, invoices and subscriptions. Send them to Hyfin when they are created or change. Hyfin owns payments: it takes them, then tells you through the payment webhook. To record a payment taken outside Hyfin, such as a check, use Add/Update Payment.

Payment statuses

The payment webhook sends one call each time a payment reaches a new status, so one payment can arrive more than once, for example as captured and later as settled. Match on the payment's _id and update the payment you already have rather than adding a new one.

Customers and contacts

A customer is the account you invoice. A contact is a person at that customer who receives the texts and emails. One customer can have several contacts: send them in primaryContact and contacts, or with Add/Update Contact.