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.

​
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 stops appearing in reads and returns 404 on any further call.