Skip to main content
In our API, resources can be identified by either an internal ID or a user-defined reference. We refer to these identifiers collectively as “keys”.

​
Key Types

  1. ID: Internally set UUID
    • Example: 123e4567-e89b-12d3-a456-426614174000
  2. Reference (ref): User-defined, unique identifier
    • Examples:
      • Accounts: internal:revenue:fx
      • Ledgers: ledger:customer_a
      • Transaction: txn:invoice_123
      • Asset Move: 83c6be5d-ebb8-41fc-8d12-d1f8ec4e2a90

​
Usage in API Endpoints

When a path parameter is described as a “key” in the documentation, you can use either an ID or a reference.

​
Path Parameter Syntax

  • For IDs: id:$id or simply $id
    • Example: /ledgers/id:123e4567-e89b-12d3-a456-426614174000
    • Example: /ledgers/123e4567-e89b-12d3-a456-426614174000
  • For references: ref:$ref
    • Example: /ledgers/ref:ledger:customer_a
Note: If no prefix is given, the system defaults to interpreting the value as an ID.

​
Key Points

  • References must be unique within their resource type.
  • The ref: prefix is required when using a reference in path parameters.
  • The id: prefix is optional for IDs in path parameters.