Students
3 routes
GET /students
Active students: no demo student, no student waiting for approval. include_deleted has no effect: a student who leaves is in /students/departures.
- Scope students:read
- Scope students.contact:read
- 1 credit
- Read
- Stable
Parameters
| Name | Type | Description |
|---|---|---|
limitquery | integer1–200, default 50 | |
cursorquery | string | Opaque cursor: next_cursor of the previous page. |
sincequery | date-time | ISO 8601. Returns the objects with updated_at >= since. |
include_deletedquery | booleandefault false | |
tagquery | string |
curl "https://api.fitdistance.io/api/partner/v1/students?limit=50" \
-H "Authorization: Bearer fd_live_xxxxxxxx"200 · a page of Student
{
"data": [
{
"id": 4821,
"coach_id": 4821,
"first_name": "Camille",
"last_name": "Roux",
"email": "camille.roux@example.com",
"phone": "string",
"birth_date": "2026-10-24",
"joined_at": "2026-10-24T09:12:00Z",
"contract_status": "ACTIVE",
"contract_start_at": "2026-10-24T09:12:00Z",
"contract_end_at": "2026-10-24T09:12:00Z",
"tags": [
{
"id": "7c1d1e2a-9b3f-4c5d-8e6f-1a2b3c4d5e6f",
"name": "string",
"color": "string"
}
],
"updated_at": "2026-10-24T09:12:00Z"
}
],
"next_cursor": null,
"has_more": false
}403 · SCOPE_MISSING
{
"error": {
"name": "PARTNER_API",
"message": "SCOPE_MISSING"
}
}200 · a page of Student
| Name | Type | Description |
|---|---|---|
id required | integer | |
coach_id required | integer | The coach of the student: a trainer of the team with team:read. |
first_name required | string | |
last_name required | string | |
email | string | Present only with the students.contact:read scope. |
phone | string | null | Present only with the students.contact:read scope. |
birth_date required | date | null | |
joined_at required | date-time | Creation of the student account. |
contract_status required | string | nullone of ACTIVE, ENDING_SOON, EXPIRED, PAUSED | Status of the contract in use with the coach. |
contract_start_at required | date-time | null | |
contract_end_at required | date-time | null | |
tags required | object[] | The tags of the student's current coach. id is the tag uid, from students.tags_list. |
updated_at required | date-time | The latest change of the student, its user account or its contract in use. A time-driven contract status change (ENDING_SOON or EXPIRED, set by a nightly job) does not move it: derive it from contract_end_at. Any write on the user account (password, settings) moves it, so a sync can receive a student with no visible change. Every login of the student moves it too (last login time): a daily since sync receives again every student who logged in since the previous one. |
Errors
| Status | Code | When |
|---|---|---|
400 | VALIDATION | Invalid parameters or body.billed |
401 | UNAUTHORIZED | Key missing, unknown or revoked.not billed |
402 | CREDITS_EXHAUSTED | No credits left this month and no reserve.not billed |
403 | SCOPE_MISSING | The key doesn't have the required scope.not billed |
403 | PLAN_NOT_ELIGIBLE | Your plan doesn't include the API.not billed |
429 | RATE_LIMITED | Too many calls: 10 per second, 300 per minute, 60 writes and 20 deletes per minute.not billed |
GET /students/departures
Students who left the coach.
- Scope students:read
- 1 credit
- Read
- Stable
Parameters
| Name | Type | Description |
|---|---|---|
limitquery | integer1–200, default 50 | |
cursorquery | string | Opaque cursor: next_cursor of the previous page. |
sincequery | date-time | ISO 8601. Returns the objects with updated_at >= since. |
include_deletedquery | booleandefault false | |
student_idquery | integer≥ 1 |
curl "https://api.fitdistance.io/api/partner/v1/students/departures?limit=50" \
-H "Authorization: Bearer fd_live_xxxxxxxx"200 · a page of Departure
{
"data": [
{
"id": 4821,
"student_id": 4821,
"coach_id": 4821,
"left_at": "2026-10-24T09:12:00Z",
"reason": "unassigned",
"updated_at": "2026-10-24T09:12:00Z"
}
],
"next_cursor": null,
"has_more": false
}403 · SCOPE_MISSING
{
"error": {
"name": "PARTNER_API",
"message": "SCOPE_MISSING"
}
}200 · a page of Departure
| Name | Type | Description |
|---|---|---|
id required | integer | |
student_id required | integer | |
coach_id required | integer | |
left_at required | date-time | |
reason required | stringone of unassigned, student_deleted, contract_ended | |
updated_at required | date-time |
Errors
| Status | Code | When |
|---|---|---|
400 | VALIDATION | Invalid parameters or body.billed |
401 | UNAUTHORIZED | Key missing, unknown or revoked.not billed |
402 | CREDITS_EXHAUSTED | No credits left this month and no reserve.not billed |
403 | SCOPE_MISSING | The key doesn't have the required scope.not billed |
403 | PLAN_NOT_ELIGIBLE | Your plan doesn't include the API.not billed |
429 | RATE_LIMITED | Too many calls: 10 per second, 300 per minute, 60 writes and 20 deletes per minute.not billed |
GET /students/{id}
One student.
- Scope students:read
- Scope students.contact:read
- 1 credit
- Read
- Stable
Parameters
| Name | Type | Description |
|---|---|---|
id requiredpath | integer≥ 1 | The numeric id of the resource. |
curl "https://api.fitdistance.io/api/partner/v1/students/4821" \
-H "Authorization: Bearer fd_live_xxxxxxxx"200 · Student
{
"id": 4821,
"coach_id": 4821,
"first_name": "Camille",
"last_name": "Roux",
"email": "camille.roux@example.com",
"phone": "string",
"birth_date": "2026-10-24",
"joined_at": "2026-10-24T09:12:00Z",
"contract_status": "ACTIVE",
"contract_start_at": "2026-10-24T09:12:00Z",
"contract_end_at": "2026-10-24T09:12:00Z",
"tags": [
{
"id": "7c1d1e2a-9b3f-4c5d-8e6f-1a2b3c4d5e6f",
"name": "string",
"color": "string"
}
],
"updated_at": "2026-10-24T09:12:00Z"
}403 · SCOPE_MISSING
{
"error": {
"name": "PARTNER_API",
"message": "SCOPE_MISSING"
}
}200 · Student
| Name | Type | Description |
|---|---|---|
id required | integer | |
coach_id required | integer | The coach of the student: a trainer of the team with team:read. |
first_name required | string | |
last_name required | string | |
email | string | Present only with the students.contact:read scope. |
phone | string | null | Present only with the students.contact:read scope. |
birth_date required | date | null | |
joined_at required | date-time | Creation of the student account. |
contract_status required | string | nullone of ACTIVE, ENDING_SOON, EXPIRED, PAUSED | Status of the contract in use with the coach. |
contract_start_at required | date-time | null | |
contract_end_at required | date-time | null | |
tags required | object[] | The tags of the student's current coach. id is the tag uid, from students.tags_list. |
updated_at required | date-time | The latest change of the student, its user account or its contract in use. A time-driven contract status change (ENDING_SOON or EXPIRED, set by a nightly job) does not move it: derive it from contract_end_at. Any write on the user account (password, settings) moves it, so a sync can receive a student with no visible change. Every login of the student moves it too (last login time): a daily since sync receives again every student who logged in since the previous one. |
Errors
| Status | Code | When |
|---|---|---|
400 | VALIDATION | Invalid parameters or body.billed |
401 | UNAUTHORIZED | Key missing, unknown or revoked.not billed |
402 | CREDITS_EXHAUSTED | No credits left this month and no reserve.not billed |
403 | SCOPE_MISSING | The key doesn't have the required scope.not billed |
403 | PLAN_NOT_ELIGIBLE | Your plan doesn't include the API.not billed |
404 | NOT_FOUND | Nothing at this address.billed |
429 | RATE_LIMITED | Too many calls: 10 per second, 300 per minute, 60 writes and 20 deletes per minute.not billed |