Contacts

A Contact is a relationship between an Uptivo user and the club selected by the Club API Key. It is distinct from an Athlete membership. The same UserId identifies the person if their relationship changes, but a Contact does not give your integration access to that user’s training or engagement data.

The Club API lets you read Contacts and update their club-specific commercial stage. It does not create contacts, update their shared user profile, or remove contacts. Demo users are excluded.

Before importing contacts, call GET /Profile and verify the selected club as described in the Club guide.

Choose an operation

Need	API reference
List contacts	GET /Contacts
Find a contact by email	GET /Contacts/ByEmail
Read one contact by UserId	GET /Contacts/{userId}
Set the club commercial stage	PUT /Contacts/{userId}/ClientStage

Import and reconcile contacts

Start a complete forward scan with fromId=1:

curl --request GET \
  --url "https://api-gw.uptivo.fit/club/Contacts?fromId=1&count=500" \
  --header "X-Sub-Key: <subscription-key>" \
  --header "Authorization: Bearer <club-api-key>"

The default page size is 500, capped at 1,000. Repeat all parameters from the first request and continue with the returned opaque token:

GET /Contacts?fromId=1&count=500&cursor=<NextCursor>

NextCursor moves to larger UserId values and PrevCursor to smaller ones.

An ID checkpoint discovers newly created contacts, but not profile updates or contacts removed or converted to Athletes. Subscribe to the Contact events and periodically repeat a complete scan to reconcile missed events. See Pagination and synchronization for the checkpoint and recovery pattern.

Read a contact

Use UserId for a direct lookup:

curl --request GET \
  --url https://api-gw.uptivo.fit/club/Contacts/300001 \
  --header "X-Sub-Key: <subscription-key>" \
  --header "Authorization: Bearer <club-api-key>"

If you have only an email address, call GET /Contacts/ByEmail?email=... with the complete, URL-encoded value. Encode a plus sign as %2B. The lookup trims surrounding whitespace; it does not create a user or club relationship.

Both lookups return 404 Not Found when the user is absent, outside the selected club, a demo user, or associated with this club only as an Athlete. Use the Athletes guide for Athlete lookups instead.

Interpret the response

ClubContactDTO identifies both the club and the shared user through ClubId and UserId. It contains basic contact details, not private notes or health data. CreatedAt records when the club Contact relationship began; JoinedAt is the original joining date when the user was previously an Athlete. ClientStage is club-specific and may be null when unassigned. See the Contacts API reference for the complete schema.

Set the commercial stage

PUT /Contacts/{userId}/ClientStage changes ClientStage only for this club’s Contact relationship. It does not invite the user, make them an Athlete, or change their global Uptivo profile:

curl --request PUT \
  --url https://api-gw.uptivo.fit/club/Contacts/300001/ClientStage \
  --header "Content-Type: application/json" \
  --header "X-Sub-Key: <subscription-key>" \
  --header "Authorization: Bearer <club-api-key>" \
  --data '{"ClientStage":"Prospect"}'

Send one of Lead, Qualified, Prospect, or Client. The request cannot set ClientStage to null, even though an unassigned Contact may return null. A successful call returns the updated ClubContactDTO with 200 OK. Repeating the current value succeeds without publishing another event; a real change publishes Contact.Updated.

A missing or invalid body returns 400; an absent, out-of-club, or demo Contact returns 404. The write requires ReadWrite access and returns 403 for an inactive license or insufficient permission.

Reads require a Club API Key with Read or ReadWrite access. A missing or invalid credential returns 401; an inactive license or insufficient key permission returns 403.