A user is an individual enrollee registered under your reseller account — the person who holds a pass, books sessions, and checks in at providers. The Users section lets you retrieve a user record, read their credit balance, keep their contact details in step with your own records, and attach a client ID to a user that does not have one yet.What you can do#
Retrieve a user by client ID or user ID
Retrieve a user's credit balance and recent transactions
Update a user's contact details
Attach a client ID to a user that does not have one
Key concepts#
Every user is addressable by two identifiers, and both are accepted wherever an endpoint takes a client ID:| Identifier | Origin | Notes |
|---|
id | Assigned by you | The enrollee's member ID in your system. Unique within your account. Not always present |
user_id | Assigned by Bardge | Stable and always present, e.g. usr_10482. Use it when the user has no client ID yet |
A client ID is the identifier for the individual in your system — it is not your company or reseller ID. Users who signed up directly by email, or who are being migrated from a previous system, may have no client ID at all; user_id is how you reach them until one is attached.Updating a user is a partial operation: only the fields you send are changed, and anything you omit is left exactly as it was. Sending a field with a blank value is rejected rather than clearing the stored value.Email addresses must be unique within your account, and phone numbers are unique across Bardge — a collision is rejected with 409 conflict, and a malformed value with 422 invalid_email or 422 invalid_phone. Supply calling_code alongside a phone number so its length can be validated; it defaults to +234 when omitted. The label field replaces the user's existing labels rather than adding to them.A request that sets every field to the value already stored is accepted and returns the unchanged user with the message No changes applied.The client ID is the anchor for the record and cannot be changed by an update. To give a user their first client ID, use the set-client-ID endpoint instead.Setting a client ID is permanentIdentify the user with user_id (preferred) or email. An email must resolve to exactly one user in your account; if it matches none the request is a 404, and if it matches several it is rejected with 409 ambiguous_email rather than guessed at.Client IDs are set once and cannot be changed:| Situation | Result |
|---|
| User has no client ID | 200 — the client ID is attached |
| User already has this exact client ID | 200 — no change made, safe to retry |
| User already has a different client ID | 409 client_id_already_set |
| Client ID is already held by another user | 409 client_id_taken |
Attaching a client ID never affects the user's existing bookings, passes or credits, and does not invalidate access codes that have already been issued.Both write endpoints accept an Idempotency-Key header. A replayed request returns the original response with X-Idempotent-Replayed: true; reusing a key with a different request body is rejected with 409 conflict.Passes — issue a pass to a user once their record exists
Credits — purchase credits that top up the balance returned here
Bookings — list the bookings a user has made
Access Codes — generate a check-in code for a user's visit
Modified at 2026-08-31 14:53:27
