Skip to Content
APIEmployees and Trainers

Employees and Trainers

Create and invite the employees of your Partner Portal, manage their portal access, and choose which members each trainer works with. A trainer sees their members in the Partner Portal, so you can keep employees and assignments in sync with the system where your team plans its work.

How it works

  • Employees live in the Partner Portal. You can create them there or through the API. The API creates employees, invites them as trainers, disables and re-enables their access, and manages their members. It does not edit other profile fields or change roles.
  • Only the trainer role can be granted through the API. Admins and managers are set up in the Partner Portal.
  • The External ID is the key. Every endpoint that addresses one employee uses the employee’s External ID: the identifier you set for them in the Partner Portal (on the employee form or in a roster import) or send when you create them through the API. Employees created in the Partner Portal without an External ID appear in the list with external_id: null and cannot be addressed until you set one with POST /employees:link. An External ID of . or .. cannot be used; these return 400.
  • Employee emails are returned, member data is not. Employee responses include the employee’s email. A member’s email and Zing-internal ID are never returned; members are identified by your partner_user_id.
  • Members are your users. A member is identified by the same partner_user_id as in the Pull API. Only members of your partner account can be linked; removed members are not returned.
  • Only trainers have members. Linking a member to an employee whose portal role is not trainer is rejected with requires_trainer.
  • A trainer can have up to 200 members.

Endpoints

MethodPathDescription
GET/employeesList employees, with search and a role filter.
POST/employeesCreate an employee without portal access.
POST/employees:inviteCreate an employee and invite them as a trainer. Sends an email.
POST/employees:linkSet the External ID of an employee created in the Partner Portal.
GET/employees/{external_id}Get one employee.
POST/employees/{external_id}/invitationInvite or re-invite an employee as a trainer. Sends an email.
PATCH/employees/{external_id}Disable or re-enable a trainer’s portal access.
GET/employees/{external_id}/membersList a trainer’s members.
PUT/employees/{external_id}/membersReplace a trainer’s whole member list.
PUT/employees/{external_id}/members/{partner_user_id}Link one member to a trainer.
DELETE/employees/{external_id}/members/{partner_user_id}Unlink one member from an employee.
POST/employees/members:batchAdd or remove up to 500 links in one request.

All endpoints use the same base URL, API key authentication, and rate limits as the Pull API. Send request bodies as JSON with Content-Type: application/json.

When to use each

  • Add a trainer and give them access — Use POST /employees:invite. It creates the employee and sends the invitation in one atomic call.
  • Add an employee now, invite later — Use POST /employees, then POST /employees/{external_id}/invitation.
  • Take away or restore access — Use PATCH /employees/{external_id}.
  • Adopt employees created in the Partner Portal — Use POST /employees:link once per employee to set their External ID.
  • Full sync — Use PUT /employees/{external_id}/members to make a trainer’s member list match your system exactly, for example in a nightly job.
  • Incremental sync — Use POST /employees/members:batch to send the changes since your last sync across many trainers in one request.
  • Single change — Use PUT or DELETE on /employees/{external_id}/members/{partner_user_id} right after one assignment changes in your system.

Pagination

Both list endpoints use the cursor pagination of the Pull API, with these differences:

  • The page items are in items, not data. meta has the same limit and next_cursor.
  • A page holds at most 200 items, whatever limit you send. A page can also hold fewer items than limit while more pages follow. Keep requesting pages until meta.next_cursor is null.
  • With cursor, omit limit to keep the limit of the first page, or send the same value. A different limit returns 400.

List employees

GET /employees

Query parameters

ParameterTypeDescription
qstringOptional. Case-insensitive search by name, email, and External ID. Up to 200 characters.
portal_rolestringOptional. One of admin, manager, trainer.
limitintegerOptional. 1 to 1000, default 100.
cursorstringOptional. meta.next_cursor from the previous page. Send the same q and portal_role with it, or omit them.

Employee fields

Every employee endpoint returns the same object:

FieldTypeDescription
idstring (UUID)The employee’s ID in the Partner Portal. Send it to POST /employees:link.
external_idstring | nullYour External ID for the employee. null if none is set.
full_namestringThe employee’s name.
preferred_namestring | nullThe name the employee goes by.
emailstring | nullThe employee’s email.
job_titlestring | nullThe employee’s job title.
specialtystring | nullThe employee’s specialty.
photo_urlstring | nullURL of the employee’s photo.
portal_rolestring | nulladmin, manager, or trainer. null if the employee has no portal role.
access_statestringPartner Portal access: NO_ACCESS, INVITATION_PENDING, ACTIVE, or DISABLED.
member_countintegerNumber of members linked to the employee.
created_atstring (date-time)When the employee was created, in UTC.
updated_atstring (date-time)When the employee was last changed, in UTC.

Example

curl -sS \ -H "Authorization: Api-Key <API KEY>" \ "https://api.dev-ai.coach/v1/employees?portal_role=trainer&limit=50"

Example response:

{ "items": [ { "id": "0c9b6f0e-4d3a-4b52-9a51-2f0e8f1d7c41", "external_id": "coach-017", "full_name": "Marco Rossi", "preferred_name": "Marco", "email": "marco.rossi@example.com", "job_title": "Personal trainer", "specialty": "Strength", "photo_url": null, "portal_role": "trainer", "access_state": "ACTIVE", "member_count": 12, "created_at": "2026-10-12T08:30:00Z", "updated_at": "2026-11-03T14:05:12Z" } ], "meta": { "limit": 50, "next_cursor": null } }

Create an employee

POST /employees

Creates an employee without portal access. It sends no email and assigns no role; the employee starts with access_state NO_ACCESS. Use it when you want the employee in the Partner Portal before you invite them, or when they do not need to sign in.

Request body

FieldTypeDescription
external_idstringRequired. Your identifier for the employee, 1 to 255 characters, not . or ...
full_namestringRequired. 1 to 200 characters.
preferred_namestringOptional. Up to 200 characters.
emailstringOptional. A valid email. You need it before you can invite the employee.
job_titlestringOptional. 1 to 200 characters.
specialtystringOptional. Up to 200 characters.
photo_urlstringOptional. Up to 500 characters.

Any other field, such as portal_role or access_state, returns 400.

Responses

  • 201 — The created employee.
  • 400 — Invalid body: a missing field, a value over its limit, an invalid email, or an unknown field. Nothing is created.
  • 409 — external_id_taken: an employee with this External ID already exists. email_taken: an employee with this email already exists.

Example

curl -sS -X POST \ -H "Authorization: Api-Key <API KEY>" \ -H "Content-Type: application/json" \ -d '{"external_id": "coach-018", "full_name": "Anna Keller", "email": "anna.keller@example.com", "job_title": "Personal trainer"}' \ "https://api.dev-ai.coach/v1/employees"

Example response (201):

{ "id": "5d1f0a7e-9b2c-4c1e-8a3d-6e4b2f9c0a11", "external_id": "coach-018", "full_name": "Anna Keller", "preferred_name": null, "email": "anna.keller@example.com", "job_title": "Personal trainer", "specialty": null, "photo_url": null, "portal_role": "null", "access_state": "NO_ACCESS", "member_count": 0, "created_at": "2026-11-09T10:00:00Z", "updated_at": "2026-11-09T10:00:00Z" }

Create and invite a trainer

POST /employees:invite

Creates an employee and invites them to the Partner Portal as a trainer, in one atomic call. If the invitation cannot be created, the employee is not created. The employee starts with access_state INVITATION_PENDING and Zing sends the invitation email to email.

Request body

The same fields as Create an employee, with two differences:

FieldTypeDescription
emailstringRequired. Where the invitation is sent.
portal_rolestringRequired. Only trainer is accepted. Any other value returns 403 with role_not_allowed.

Responses

  • 201 — The created and invited employee, with portal_role trainer.
  • 400 — Invalid body: a missing email or portal_role, an invalid email, a value over its limit, or an unknown field. Nothing is created.
  • 403 — role_not_allowed: only the trainer role can be granted through the API.
  • 409 — external_id_taken or email_taken.

Example

curl -sS -X POST \ -H "Authorization: Api-Key <API KEY>" \ -H "Content-Type: application/json" \ -d '{"external_id": "coach-018", "full_name": "Anna Keller", "email": "anna.keller@example.com", "portal_role": "trainer"}' \ "https://api.dev-ai.coach/v1/employees:invite"

Example response (201):

{ "id": "5d1f0a7e-9b2c-4c1e-8a3d-6e4b2f9c0a11", "external_id": "coach-018", "full_name": "Anna Keller", "preferred_name": null, "email": "anna.keller@example.com", "job_title": "Personal trainer", "specialty": null, "photo_url": null, "portal_role": "trainer", "access_state": "INVITATION_PENDING", "member_count": 0, "created_at": "2026-11-09T10:00:00Z", "updated_at": "2026-11-09T10:00:00Z" }

Forbidden response (403):

{ "detail": "Only the trainer role can be granted or managed through the API.", "code": "role_not_allowed" }

Get an employee

GET /employees/{external_id}

Returns one employee. Use it to check the state of an employee, for example after a write that timed out.

Responses

  • 200 — The employee.
  • 400 — The External ID is . or ...
  • 404 — No employee with this External ID exists in your Partner Portal.

Example

curl -sS \ -H "Authorization: Api-Key <API KEY>" \ "https://api.dev-ai.coach/v1/employees/coach-018"

Invite or re-invite an employee

POST /employees/{external_id}/invitation

Invites an employee to the Partner Portal as a trainer, or resends a pending invitation. Zing sends the invitation email. A resent invitation cancels the previous link; the new link is valid for 7 days.

Request body

Optional. Send nothing, {}, or:

FieldTypeDescription
portal_rolestringOnly trainer is accepted; any other value returns 403 with role_not_allowed. Required unless an invitation is already pending. Without it, a pending trainer invitation is resent with the previous role.

The employee needs an email. A pending invitation for an admin or manager role returns 403 with role_not_allowed.

Responses

  • 200 — The invited employee, with access_state INVITATION_PENDING.
  • 400 — role_required: portal_role is required to invite this employee. email_missing: the employee has no email to send the invitation to. Other invalid bodies, and an External ID of . or .., return 400 without a code.
  • 403 — role_not_allowed: only the trainer role can be granted through the API.
  • 404 — No employee with this External ID exists in your Partner Portal.
  • 409 — already_has_access: the employee already has portal access. email_taken: another employee already has this email.

Example

curl -sS -X POST \ -H "Authorization: Api-Key <API KEY>" \ -H "Content-Type: application/json" \ -d '{"portal_role": "trainer"}' \ "https://api.dev-ai.coach/v1/employees/coach-018/invitation"

Disable or re-enable access

PATCH /employees/{external_id}

Disables or re-enables a trainer’s portal access. Disabling access keeps the trainer’s member links, so re-enabling restores the same members. Setting the state the employee already has changes nothing and returns 200. Only a trainer who already has a portal account can be changed: NO_ACCESS and INVITATION_PENDING employees return 409.

Request body

FieldTypeDescription
access_statestringRequired. ACTIVE or DISABLED.

Any other value, any other field, or an empty body returns 400.

Responses

  • 200 — The updated employee.
  • 400 — Invalid body, or an External ID of . or ...
  • 403 — role_not_allowed: the employee is not a trainer.
  • 404 — No employee with this External ID exists in your Partner Portal.
  • 409 — requires_portal_access: the employee has no portal account yet.

Example

curl -sS -X PATCH \ -H "Authorization: Api-Key <API KEY>" \ -H "Content-Type: application/json" \ -d '{"access_state": "DISABLED"}' \ "https://api.dev-ai.coach/v1/employees/coach-018"

Conflict response (409):

{ "detail": "The employee has no portal access yet.", "code": "requires_portal_access" }

Set the External ID of an employee

POST /employees:link

Sets the External ID of an employee created in the Partner Portal without one. Such employees appear in GET /employees and in employee.* webhook events with external_id: null. This is the only call where you send a Zing employee id; send the id from GET /employees.

It works for any role, because it changes only the identifier and not access. An existing different External ID is overwritten and cannot be cleared. Sending the same External ID again changes nothing and returns 200.

Request body

FieldTypeDescription
idstring (UUID)Required. The employee’s id from GET /employees.
external_idstringRequired. 1 to 255 characters, not blank, not . or ...

Responses

  • 200 — The employee with the new External ID. It can now be addressed as /employees/{external_id}.
  • 400 — Invalid body: a missing or invalid id, a missing, blank or too long external_id, or an unknown field.
  • 404 — No employee with this id exists in your Partner Portal.
  • 409 — external_id_taken: another employee already has this External ID.

Example

curl -sS -X POST \ -H "Authorization: Api-Key <API KEY>" \ -H "Content-Type: application/json" \ -d '{"id": "0c9b6f0e-4d3a-4b52-9a51-2f0e8f1d7c41", "external_id": "coach-017"}' \ "https://api.dev-ai.coach/v1/employees:link"

List a trainer’s members

GET /employees/{external_id}/members

Takes limit and cursor. Each item has the same fields as an item of GET /users: partner_user_id, first_name, and last_name (see Member Names).

Responses

  • 200 — A page of the employee’s members.
  • 400 — Invalid limit or cursor, or the External ID is . or ...
  • 404 — No employee with this External ID exists in your Partner Portal.

Example

curl -sS \ -H "Authorization: Api-Key <API KEY>" \ "https://api.dev-ai.coach/v1/employees/coach-017/members"

Example response:

{ "items": [ { "partner_user_id": "partner-usr-123", "first_name": "Jane", "last_name": "Doe" }, { "partner_user_id": "partner-usr-456", "first_name": null, "last_name": null } ], "meta": { "limit": 100, "next_cursor": null } }

Replace a trainer’s members

PUT /employees/{external_id}/members

Sets the trainer’s member list to exactly the members you send. Members not in the request are unlinked.

Request body

FieldTypeDescription
itemsarray of stringsRequired. 0 to 200 partner_user_id values, each 1 to 255 characters and at most once.

An empty items list unlinks every member. It works for any employee, including one who is no longer a trainer.

Validation is all or nothing

If any partner_user_id is repeated or is not a member of your partner account, the request returns 400 and nothing changes. The detail message lists the IDs, for example Unknown partner_user_id: partner-usr-999.

Responses

  • 200 — Replaced. items holds the trainer’s members after the change.
  • 400 — Invalid body: missing items, more than 200 IDs, a repeated or unknown partner_user_id, or an unknown field. Also returned for an External ID of . or ...
  • 404 — No employee with this External ID exists in your Partner Portal.
  • 409 — requires_trainer: the list is not empty and the employee is not a trainer.

Example

curl -sS -X PUT \ -H "Authorization: Api-Key <API KEY>" \ -H "Content-Type: application/json" \ -d '{"items": ["partner-usr-123", "partner-usr-456"]}' \ "https://api.dev-ai.coach/v1/employees/coach-017/members"

Example response:

{ "items": [ { "partner_user_id": "partner-usr-123", "first_name": "Jane", "last_name": "Doe" }, { "partner_user_id": "partner-usr-456", "first_name": null, "last_name": null } ] }
PUT /employees/{external_id}/members/{partner_user_id}

Send no request body; a body with any field returns 400. Linking a member who is already linked changes nothing and also returns 204.

Responses

  • 204 — The member is linked to the trainer.
  • 400 — The request has a body, or the External ID is . or ...
  • 404 — Employee not found. or Member not found.: no employee with this External ID, or no member with this partner_user_id in your partner account.
  • 409 — requires_trainer: the employee is not a trainer. member_limit: the trainer already has 200 members.

Example

curl -sS -X PUT \ -H "Authorization: Api-Key <API KEY>" \ "https://api.dev-ai.coach/v1/employees/coach-017/members/partner-usr-123"

Conflict response (409):

{ "detail": "A trainer can have at most 200 members.", "code": "member_limit" }
DELETE /employees/{external_id}/members/{partner_user_id}

Send no request body; a body with any field returns 400. Unlinking a member who is not linked, or a partner_user_id that is not a member of your partner account, changes nothing and also returns 204.

Responses

  • 204 — The member is not linked to the employee.
  • 400 — The request has a body, or the External ID is . or ...
  • 404 — No employee with this External ID exists in your Partner Portal.

Example

curl -sS -X DELETE \ -H "Authorization: Api-Key <API KEY>" \ "https://api.dev-ai.coach/v1/employees/coach-017/members/partner-usr-123"
POST /employees/members:batch

Applies up to 500 link changes, across any number of employees, in request order.

Request body

FieldTypeDescription
itemsarrayRequired. 1 to 500 items.
items[].employee_external_idstringRequired. The employee’s External ID, 1 to 255 characters, not . or ...
items[].partner_user_idstringRequired. The member’s partner_user_id, 1 to 255 characters.
items[].opstringRequired. add or remove.

Results per item

If the request is valid, it returns 200 with one result per item, in request order. Check result on each item:

resultMeaning
addedThe member is now linked to the trainer.
removedThe member is no longer linked to the employee.
unchangedNothing to do: the link already existed for add, or did not exist for remove. Also returned for remove when the partner_user_id is not a member of your partner account.
employee_not_foundNo employee with this External ID exists in your Partner Portal.
member_not_foundadd only: no member with this partner_user_id in your partner account.
requires_traineradd only: the employee is not a trainer.
member_limitadd only: the trainer already has 200 members.

An item that fails does not stop the others. A malformed request (missing or empty items, more than 500 items, a missing field, an unknown op, an External ID of . or .., or an unknown field) returns 400 and nothing changes.

Example

curl -sS -X POST \ -H "Authorization: Api-Key <API KEY>" \ -H "Content-Type: application/json" \ -d '{ "items": [ {"employee_external_id": "coach-017", "partner_user_id": "partner-usr-123", "op": "add"}, {"employee_external_id": "coach-017", "partner_user_id": "partner-usr-789", "op": "remove"}, {"employee_external_id": "coach-404", "partner_user_id": "partner-usr-456", "op": "add"} ] }' \ "https://api.dev-ai.coach/v1/employees/members:batch"

Example response:

{ "items": [ { "employee_external_id": "coach-017", "partner_user_id": "partner-usr-123", "op": "add", "result": "added" }, { "employee_external_id": "coach-017", "partner_user_id": "partner-usr-789", "op": "remove", "result": "unchanged" }, { "employee_external_id": "coach-404", "partner_user_id": "partner-usr-456", "op": "add", "result": "employee_not_found" } ] }

Errors

These endpoints return the Pull API error responses, plus:

  • 400 and 403 — The body adds a machine-readable code next to detail when the Partner Portal rejects the request: role_required and email_missing on 400, role_not_allowed on 403. Errors without a code are unchanged.
  • 409 — The change conflicts with the employee’s role, member limit or an existing employee. The body adds a machine-readable code next to detail: requires_trainer, member_limit, external_id_taken, email_taken, already_has_access, or requires_portal_access.
  • 503 — The service is temporarily unavailable. Nothing you can fix in the request; retry with backoff.
{ "detail": "Service temporarily unavailable, please retry." }

Considerations

  • Emails — Only POST /employees:invite and POST /employees/{external_id}/invitation send an email. The other writes never do.
  • Do not blindly retry employee writes — Zing never retries an employee write. After a timeout or a 503, do not repeat POST /employees:invite or POST /employees/{external_id}/invitation before you check the state with GET /employees/{external_id}: a repeated invite sends a second email. Repeating POST /employees or POST /employees:invite for an employee that was created returns 409 external_id_taken.
  • Member link retries — Every member link write is safe to retry. Linking a linked member, unlinking an unlinked one, or sending the same replace list again leaves the same state. In a batch, items already applied come back as unchanged.
  • Set External IDs first — Before you sync, make sure every trainer has an External ID. GET /employees shows the ones that are missing; set them with POST /employees:link.
  • Members must exist — Only members returned by GET /users can be linked. For anyone else, add returns member_not_found and replace returns 400.
  • Rate limits — If you receive 429, wait for the Retry-After seconds before retrying. Send batches one after another rather than in parallel.

For the full request and response schemas, see the Reference (opens in new window).

Last updated on