Skip to main content
These conventions apply across the API. Endpoint references document their request fields, responses, and any additional requirements.

Identifiers

Objects carry an external ID made up of a short prefix, an underscore, and 24 lowercase alphanumeric characters, for example acct_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 created and updated, plus created_by and updated_by.
  • Audit actors: created_by and updated_by carry the literal string hop_admin when Hop made the change.
  • Countries are ISO 3166-1 alpha-2 codes, such as US or SG.
  • US states: on an account identity or associated person address with country US, region is required and must be the two-letter USPS code: one of the 50 states, DC, AS, GU, MP, PR or VI. CA is accepted (lowercase is uppercased); California returns 422 VALIDATION_ERROR. Outside the US, region is 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 returns 413 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 returns 404. List Webhook Endpoints is an exception: it includes deleted endpoints with deleted_at set.