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
trainerrole 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: nulland cannot be addressed until you set one withPOST /employees:link. An External ID of.or..cannot be used; these return400. - 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 yourpartner_user_id. - Members are your users. A member is identified by the same
partner_user_idas 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
traineris rejected withrequires_trainer. - A trainer can have up to 200 members.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /employees | List employees, with search and a role filter. |
| POST | /employees | Create an employee without portal access. |
| POST | /employees:invite | Create an employee and invite them as a trainer. Sends an email. |
| POST | /employees:link | Set the External ID of an employee created in the Partner Portal. |
| GET | /employees/{external_id} | Get one employee. |
| POST | /employees/{external_id}/invitation | Invite 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}/members | List a trainer’s members. |
| PUT | /employees/{external_id}/members | Replace 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:batch | Add 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, thenPOST /employees/{external_id}/invitation. - Take away or restore access — Use
PATCH /employees/{external_id}. - Adopt employees created in the Partner Portal — Use
POST /employees:linkonce per employee to set their External ID. - Full sync — Use
PUT /employees/{external_id}/membersto make a trainer’s member list match your system exactly, for example in a nightly job. - Incremental sync — Use
POST /employees/members:batchto send the changes since your last sync across many trainers in one request. - Single change — Use
PUTorDELETEon/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, notdata.metahas the samelimitandnext_cursor. - A page holds at most 200 items, whatever
limityou send. A page can also hold fewer items thanlimitwhile more pages follow. Keep requesting pages untilmeta.next_cursorisnull. - With
cursor, omitlimitto keep the limit of the first page, or send the same value. A differentlimitreturns400.
List employees
GET /employeesQuery parameters
| Parameter | Type | Description |
|---|---|---|
q | string | Optional. Case-insensitive search by name, email, and External ID. Up to 200 characters. |
portal_role | string | Optional. One of admin, manager, trainer. |
limit | integer | Optional. 1 to 1000, default 100. |
cursor | string | Optional. 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:
| Field | Type | Description |
|---|---|---|
id | string (UUID) | The employee’s ID in the Partner Portal. Send it to POST /employees:link. |
external_id | string | null | Your External ID for the employee. null if none is set. |
full_name | string | The employee’s name. |
preferred_name | string | null | The name the employee goes by. |
email | string | null | The employee’s email. |
job_title | string | null | The employee’s job title. |
specialty | string | null | The employee’s specialty. |
photo_url | string | null | URL of the employee’s photo. |
portal_role | string | null | admin, manager, or trainer. null if the employee has no portal role. |
access_state | string | Partner Portal access: NO_ACCESS, INVITATION_PENDING, ACTIVE, or DISABLED. |
member_count | integer | Number of members linked to the employee. |
created_at | string (date-time) | When the employee was created, in UTC. |
updated_at | string (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 /employeesCreates 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
| Field | Type | Description |
|---|---|---|
external_id | string | Required. Your identifier for the employee, 1 to 255 characters, not . or ... |
full_name | string | Required. 1 to 200 characters. |
preferred_name | string | Optional. Up to 200 characters. |
email | string | Optional. A valid email. You need it before you can invite the employee. |
job_title | string | Optional. 1 to 200 characters. |
specialty | string | Optional. Up to 200 characters. |
photo_url | string | Optional. 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:inviteCreates 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:
| Field | Type | Description |
|---|---|---|
email | string | Required. Where the invitation is sent. |
portal_role | string | Required. Only trainer is accepted. Any other value returns 403 with role_not_allowed. |
Responses
- 201 — The created and invited employee, with
portal_roletrainer. - 400 — Invalid body: a missing
emailorportal_role, an invalid email, a value over its limit, or an unknown field. Nothing is created. - 403 —
role_not_allowed: only thetrainerrole can be granted through the API. - 409 —
external_id_takenoremail_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}/invitationInvites 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:
| Field | Type | Description |
|---|---|---|
portal_role | string | Only 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_stateINVITATION_PENDING. - 400 —
role_required:portal_roleis 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.., return400without acode. - 403 —
role_not_allowed: only thetrainerrole 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
| Field | Type | Description |
|---|---|---|
access_state | string | Required. 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:linkSets 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
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Required. The employee’s id from GET /employees. |
external_id | string | Required. 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 longexternal_id, or an unknown field. - 404 — No employee with this
idexists 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}/membersTakes 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
limitorcursor, 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}/membersSets the trainer’s member list to exactly the members you send. Members not in the request are unlinked.
Request body
| Field | Type | Description |
|---|---|---|
items | array of strings | Required. 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.
itemsholds the trainer’s members after the change. - 400 — Invalid body: missing
items, more than 200 IDs, a repeated or unknownpartner_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
}
]
}Link one member
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.orMember not found.: no employee with this External ID, or no member with thispartner_user_idin 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"
}Unlink one member
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"Add or remove links in a batch
POST /employees/members:batchApplies up to 500 link changes, across any number of employees, in request order.
Request body
| Field | Type | Description |
|---|---|---|
items | array | Required. 1 to 500 items. |
items[].employee_external_id | string | Required. The employee’s External ID, 1 to 255 characters, not . or ... |
items[].partner_user_id | string | Required. The member’s partner_user_id, 1 to 255 characters. |
items[].op | string | Required. 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:
result | Meaning |
|---|---|
added | The member is now linked to the trainer. |
removed | The member is no longer linked to the employee. |
unchanged | Nothing 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_found | No employee with this External ID exists in your Partner Portal. |
member_not_found | add only: no member with this partner_user_id in your partner account. |
requires_trainer | add only: the employee is not a trainer. |
member_limit | add 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
codenext todetailwhen the Partner Portal rejects the request:role_requiredandemail_missingon400,role_not_allowedon403. Errors without acodeare unchanged. - 409 — The change conflicts with the employee’s role, member limit or an existing employee. The body adds a machine-readable
codenext todetail:requires_trainer,member_limit,external_id_taken,email_taken,already_has_access, orrequires_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:inviteandPOST /employees/{external_id}/invitationsend 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 repeatPOST /employees:inviteorPOST /employees/{external_id}/invitationbefore you check the state withGET /employees/{external_id}: a repeated invite sends a second email. RepeatingPOST /employeesorPOST /employees:invitefor an employee that was created returns409external_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 /employeesshows the ones that are missing; set them withPOST /employees:link. - Members must exist — Only members returned by
GET /userscan be linked. For anyone else,addreturnsmember_not_foundand replace returns400. - Rate limits — If you receive
429, wait for theRetry-Afterseconds 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).