contactId you pass when
creating a booking,
to create the customer when they are new, and to keep their details current.
You can still create a booking without touching these endpoints by sending an
inline
customer object, which is matched to a contact by email. That path is
unchanged and remains supported. Prefer contactId whenever you can resolve
it, because it is explicit about which person the booking is for.Search contacts
Requires thecontacts:read scope.
search(optional) - matches on name, email, or phone, up to 120 characters. An empty value is treated as no search.limit(optional) - 1 to 100, defaults to 25offset(optional) - defaults to 0
total counts every contact matching the filters, ignoring pagination, so you can
tell whether more pages exist. Results are ordered by name.
uuid- a stable, unguessable identifier. Prefer it overidwhen you store a reference.type- the derived contact type, for examplecontact,member, orlead.archivedmarks a retired contact.pipelineStageId,sourceId,assignedToId- the sales pipeline stage the contact is in, where they came from, and the staff member following them up. See Pipeline stages and contact sources.
Matching is case-insensitive and cross-script
Search normalizes the query and also matches transliterated forms, soivan finds
Иван and Иван finds Ivan. Accents are stripped too, so pena matches Peña.
This is the same matching the gym’s staff see in the admin CRM, so an integration
resolving a name lands on the same people a staff member would.
Archived contacts are never returned.
Open a contact
Requires thecontacts:read scope.
404 means no contact with that id exists in your organization.
Pass include=overview to also get overview: what staff see on the contact’s
profile before serving them - alerts such as an Amount Due or a required document
left unsigned, the money they owe and hold, activity counts and the last visit, and
the contact details the record lacks. The money needs transactions:read and gear
on loan needs products:read, on top of contacts:read. Without them the rest is
still returned, and withheld names what was left out and the scope it needs.
Create a contact
Requires thecontacts:write scope.
firstName(required)lastName(optional)email(optional)phone(optional) - stored in international form (for example+359877762016) when it is a valid number for the organization’s country, and as given otherwisepipelineStageId(optional) - put the contact in the sales pipeline at this stagesourceId(optional) - where the contact came fromassignedToId(optional) - the staff member following them up
email or phone is required, so the person stays reachable and
findable. Email is normalized to lower case.
Response (201 Created) is the created contact.
Creating a contact accepts an Idempotency-Key, so a retry after a timeout cannot
produce a second record. See Idempotency.
Update a contact
Requires thecontacts:write scope. Send only what changes: null clears lastName, email, phone, pipelineStageId, sourceId, or assignedToId, and an omitted field is left alone.
- The display
nameis always recomputed fromfirstNameandlastName, and the phone is canonicalized as on create. - A contact must keep at least one of
emailorphone. - An
emailalready used by another contact in the organization is a409. - The
emailof a contact whose address is also their 1club login cannot be changed (400). The person changes it themselves. - Clearing a field the organization marks as required for staff is a
400naming the field. - An archived contact cannot be edited.
pipelineStageIdmoves the contact in the sales pipeline, andnulltakes them out of it. A contact who has never been a customer is a lead while they are in the pipeline, so this can changetype.
Archive a contact
Requires thecontacts:delete scope. contacts:write alone cannot archive, because archiving cancels things that restoring the contact does not bring back.
type: "archived". Archiving also releases everything they hold on the forward schedule: active memberships, bookings they organized, and bookings they are only a player on. Restoring the contact in 1club does not restore any of these.
- Paid future bookings. When the cancellation policy would keep money from a paid future booking, pass
keepCancellationCharge:falserefunds it in full, andtrueapplies the policy. Without it, such an archive is refused with409andcode: "CANCELLATION_CHARGE_DECISION_REQUIRED", and nothing changes. - Refused contacts. A staff member or owner who can reach the admin portal, an instructor whose profile still has upcoming classes, and a contact paying part of a split bill on a future booking are refused with
409andcode: "CONFLICT". Resolve those in 1club first. - Partial release. If a membership or booking fails to release, the contact is still archived, and the response is
409withcode: "ARCHIVE_INCOMPLETE"and the unreleased items indetails.outstanding. Repeat the same request to finish the job. Readcodeto tell this apart from a refusal: one means nothing happened, the other means the archive did.
Pipeline stages and contact sources
Requires thecontacts:read scope. These list the values pipelineStageId and sourceId refer to. Each returns { "data": [...] } with no paging.
GET /v1/platform/pipeline-stages- each stage hasid,name,color,kind(openorcold),isDefault(the stage new leads start in),sortOrder, andcontactCount.GET /v1/platform/contact-sources- each source hasid,name,color,isActive, andsortOrder.
Resolving a customer before booking
1
Search by what you know
Call Search contacts with the customer’s name, email, or phone.
2
Decide
One match is your customer. Several matches need a human to choose. No match
means they are new.
3
Create when new
Call Create a contact with at least an email or a phone.
4
Book with the id
Pass the resolved
contactId on Create a
booking.What this API does not do
- No hard deletes. Archiving retires a contact and keeps their history. Restoring an archived contact is done in 1club.
- No merging. If duplicates appear, they are resolved inside 1club.
- One-way sync. 1club never pushes contact changes back to you.
- Archived contacts cannot be booked. Archiving is how a gym retires a contact. An archived contact is hidden from search and rejected as the person a booking is for, or as a player on one.