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.