Identifiers
Objects carry an external ID made up of a short prefix, an underscore, and 24 lowercase alphanumeric characters, for exampleacct_9f2a7c1e6a2b4f3c9b8d2e5a.
For deposit instructions,
di_ prefixes the instruction’s id. The required payment reference is returned separately in memo; copy that value exactly when sending funds. Use the returned memo to determine whether a reference is required. See Deposit Flows.
Data formats
- Amounts are JSON strings, not numbers, and are returned at the precision of their currency. See Handling currencies.
- Timestamps are ISO 8601, UTC. Objects carry
createdandupdated, pluscreated_byandupdated_by. - Audit actors:
created_byandupdated_bycarry the literal stringhop_adminwhen Hop made the change. - Countries are ISO 3166-1 alpha-2 codes, such as
USorSG. - US states: on an account identity or associated person address with
countryUS,regionis required and must be the two-letter USPS code: one of the 50 states,DC,AS,GU,MP,PRorVI.CAis accepted (lowercase is uppercased);Californiareturns422 VALIDATION_ERROR. Outside the US,regionis optional free text.
Request limits
Request bodies are capped at 1 MB, except Update Account and Upload Document, which accept 21 MB because they carry base64 documents. Over the limit returns413 REQUEST_TOO_LARGE with details.max_bytes.
For per-key request frequency limits and 429 responses, see Rate limits.
Request IDs
X-Request-ID is an optional request header, echoed in every error as request_id. Omit it and Hop generates a UUID. Log request_id and include it when contacting support.
Deleted resources
Deletes are soft. A deleted object is excluded from ordinary reads and its Get endpoint returns404. List Webhook Endpoints is an exception: it includes deleted endpoints with deleted_at set.