Use this guide to pick the right identifier field on each request and avoid common integration errors.
Why Identifiers Matter
- Most integration failures come from using the wrong identifier field for an endpoint.
- Juvonno uses multiple identifier styles (`id`, `num`, `code`), and they are not interchangeable in every request.
- Different endpoints can expect different names for similar concepts, so identifier handling must be explicit.
Types of Identifiers
### `customer_id` vs `customer_num`
What it represents:
- `customer_id`: numeric internal identifier for a customer record.
- `customer_num`: customer number value used by some endpoint payloads.
Where it is typically used:
- `customer_id` appears in many request/response payloads and path-based operations.
- `customer_num` appears as an alternate accepted field in some request models.
When to prefer it:
- Prefer `customer_id` after lookup/create when available.
- Use `customer_num` only when an endpoint explicitly expects or allows it.
### `branch_id` vs `branch_code` vs `branch_num`
What it represents:
- `branch_id`: numeric internal branch (clinic) identifier.
- `branch_code`: readable clinic code.
- `branch_num`: branch number naming used in some request/query fields.
Where it is typically used:
- `branch_code` and `branch_id` both appear in appointment/customer-related operations.
- `branch_num` appears in some query patterns (for example commissions) and is also listed in some required-field definitions.
When to prefer it:
- Prefer `branch_code` for readability when endpoint accepts it.
- Use `branch_id` if the endpoint requires numeric ID.
- Treat `branch_num` as endpoint-specific and verify before use; do not assume it is interchangeable with `branch_code`.
### `staff_num`
What it represents:
- Practitioner/staff number identifier.
Where it is typically used:
- Appointment creation (`attendants`) and related staff filtering patterns.
When to prefer it:
- Use `staff_num` when endpoint payload expects staff identifiers by number.
### `appointment_id`
What it represents:
- Numeric identifier for a specific appointment record.
Where it is typically used:
- Retrieval/update operations that target a single appointment.
When to prefer it:
- Always capture it from create/search responses and reuse it for follow-up operations.
Real Examples (from Golden Path)
Reference: Golden Path Integration Example
Customer lookup/create:
- capture `CUSTOMER_ID` from search or create response
- reuse `CUSTOMER_ID` in appointment creation
Branch selection:
- capture `BRANCH_CODE` (preferred) or `BRANCH_ID` from branch lookup
- pass the correct branch identifier in appointment payload
Appointment confirmation:
- capture `APPOINTMENT_ID` from create response
- use `APPOINTMENT_ID` to retrieve and confirm the appointment
Common Mistakes
- Using `customer_num` where `customer_id` is expected.
- Mixing `branch_code` and `branch_id` without checking endpoint requirements.
- Assuming field naming is consistent across endpoints.
- Failing to store identifiers returned from create responses.
How to Choose the Right Identifier
- Start with endpoint requirements first: check which identifier fields that endpoint accepts.
- If you already have a record, send `*_id` by default.
- For branch references, send `branch_code` when accepted; switch to `branch_id` only when required.
- Use `*_num` fields only when that endpoint explicitly expects or allows them.
Verify the choice with a live request before release.
Best Practices
- Store identifiers immediately after creation.
- Reuse stored identifiers instead of repeating lookup calls unnecessarily.
- Normalize identifier handling in your own integration layer (for example, map all accepted inputs to a canonical internal field).
During development, log identifier values used in requests and returned in responses to speed up debugging.
Gotchas
Handle these defensively in code and tests, because they can vary by endpoint.
Inconsistent naming exists (`customerId` vs `customer_id`).
- A concrete example is encounters APIs, where one route uses `customerId` and another uses `customer_id`.
- `id` vs `num` vs `code` can be ambiguous without endpoint-specific checks.
Request and response identifier fields do not always use the same naming patterns.
Summary
- Check accepted identifier fields per endpoint before implementation.
- Prefer `*_id` once you have it; use `*_num` only when needed.
- Prefer `branch_code` for readability, but fall back to `branch_id` if required.
- Store and log identifiers during development to catch mapping errors early.