Schedule and track certified video calls
This API lets you schedule certified video calls from your own tools, retrieve those of your company and reschedule them, without going through the Certificall interface.
A video call is run by a person in charge: a user of your company (or of one of its subsidiaries) who will launch it from Certificall. The guest is the person who joins the video call.
Prerequisites
Before you start, make sure that:
- You have a JWT authentication token (see Authentication).
- Your API account holds the required video call rights (schedule, view, reschedule). If not, contact your Certificall administrator.
- Video calls are enabled for your company (or inherited from your parent company).
Every request carries the header:
Authorization: Bearer <your_token>
The routes on this page share the base URL of the rest of the Certificall API: https://admin.certificall.app/v2/certificall/api.
Scope: your company and its subsidiaries
You can see, schedule and reschedule the video calls of your company and all its descendants (subsidiaries, subsidiaries of subsidiaries, and so on). A video call of another company is not found for you (404).
The person in charge must also belong to this scope.
Video call lifecycle
| Status | Meaning | Reschedulable |
|---|---|---|
READY | Scheduled, not launched yet | Yes |
CREATED | Launched by the person in charge | No |
INITIATED | The guest has joined the video call | No |
COMPLETED | Video call ended | No |
ERROR | Video call in error | No |
A video call only moves forward in this lifecycle: it never goes back to a previous status.
1. Schedule a video call
- Endpoint:
POST /v2/certificall/api/visio-sessions - Required right: schedule a video call
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
assigneeEmail | String | yes | Email of the person in charge: a user of your company or of one of its subsidiaries |
firstName | String | yes | Guest's first name (100 characters max.) |
lastName | String | yes | Guest's last name (100 characters max.) |
phoneNumber | String | yes | Guest's phone number (30 characters max.) |
email | String | no | Guest's email |
scheduledAt | String | no | Date and time of the video call, ISO 8601 format (e.g. 2026-11-02T09:00:00Z) |
reportToken | String | no | Report identifier to attach the video call's case to (100 characters max.) |
expectedAddress | String | no | Expected address of the video call location: street, 5-digit postal code and city |
expectedLatitude | String | no | Latitude of the expected address |
expectedLongitude | String | no | Longitude of the expected address |
expectedLatitude and expectedLongitude are given together, and only with expectedAddress.
Request example:
curl -X POST https://admin.certificall.app/v2/certificall/api/visio-sessions \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"assigneeEmail": "operator@your-company.com",
"firstName": "Jeanne",
"lastName": "Martin",
"phoneNumber": "+33612345678",
"email": "jeanne.martin@example.com",
"scheduledAt": "2026-11-02T09:00:00Z",
"expectedAddress": "12 Rue de la Paix, 75002 Paris"
}'
Response example (201 Created):
{
"id": "VIS-1761210000000-6f1c2b9e-3d4a-4f5b-8c7d-1e2f3a4b5c6d",
"status": "READY",
"companyId": 123,
"caseId": null,
"guest": {
"firstName": "Jeanne",
"lastName": "Martin",
"phoneNumber": "+33612345678",
"email": "jeanne.martin@example.com"
},
"assigneeEmail": "operator@your-company.com",
"scheduledAt": "2026-11-02T09:00:00.000Z",
"expectedAddress": "12 Rue de la Paix, 75002 Paris",
"expectedLatitude": null,
"expectedLongitude": null,
"createdAt": "2026-10-23T09:00:00.000Z",
"updatedAt": null
}
Keep the id: you need it to view and reschedule the video call. assigneeEmail is the email of the person in charge; it is null if that user no longer exists.
When the video call is dated, the guest receives an invitation (if they have an email) and the person in charge receives a confirmation with a calendar file (.ics).
Response codes:
201 Created: video call scheduled400 Bad Request: missing or invalid field (including a missingassigneeEmail)403 Forbidden: scheduling right missing422 Unprocessable Entity: person in charge not found in your company or its subsidiaries, or video calls not enabled for your company
2. List video calls
- Endpoint:
GET /v2/certificall/api/visio-sessions - Required right: view video calls
Video calls are sorted from the most recently created to the oldest.
Query parameters (all optional):
| Name | Type | Description |
|---|---|---|
status | String | Filter on a status (READY, CREATED, INITIATED, COMPLETED, ERROR) |
scheduledFrom | String | Video calls scheduled from this date (ISO 8601, inclusive) |
scheduledTo | String | Video calls scheduled up to this date (ISO 8601, inclusive) |
limit | Number | Number of video calls per page, from 1 to 200 (default: 50) |
offset | Number | Number of video calls to skip (default: 0) |
Request example:
curl "https://admin.certificall.app/v2/certificall/api/visio-sessions?status=READY&limit=20&offset=0" \
-H "Authorization: Bearer $TOKEN"
Response example:
{
"items": [
{
"id": "VIS-1761210000000-6f1c2b9e-3d4a-4f5b-8c7d-1e2f3a4b5c6d",
"status": "READY",
"companyId": 123,
"caseId": null,
"guest": {
"firstName": "Jeanne",
"lastName": "Martin",
"phoneNumber": "+33612345678",
"email": "jeanne.martin@example.com"
},
"assigneeEmail": "operator@your-company.com",
"scheduledAt": "2026-11-02T09:00:00.000Z",
"expectedAddress": "12 Rue de la Paix, 75002 Paris",
"expectedLatitude": null,
"expectedLongitude": null,
"createdAt": "2026-10-23T09:00:00.000Z",
"updatedAt": null
}
],
"total": 1
}
total is the total number of video calls matching the filters, across all pages.
Response codes:
200 OK: list returned400 Bad Request: invalid parameter (includingscheduledFromlater thanscheduledTo)403 Forbidden: viewing right missing
3. View a video call
- Endpoint:
GET /v2/certificall/api/visio-sessions/:id - Required right: view video calls
Request example:
curl https://admin.certificall.app/v2/certificall/api/visio-sessions/VIS-1761210000000-6f1c2b9e-3d4a-4f5b-8c7d-1e2f3a4b5c6d \
-H "Authorization: Bearer $TOKEN"
The response has the same shape as a video call in the list.
Response codes:
200 OK: video call returned403 Forbidden: viewing right missing404 Not Found: unknown video call, or one belonging to a company outside your scope
4. Reschedule a video call
- Endpoint:
PATCH /v2/certificall/api/visio-sessions/:id - Required right: reschedule a video call
Changes the date and/or the person in charge of a video call that has not been launched yet (status READY).
Request body (at least one field):
| Field | Type | Description |
|---|---|---|
scheduledAt | String or null | New date (ISO 8601), or null to remove the date |
assigneeEmail | String | Email of the new person in charge (your company or its subsidiaries) |
The person in charge cannot be removed: assigneeEmail: null is rejected.
Request example:
curl -X PATCH https://admin.certificall.app/v2/certificall/api/visio-sessions/VIS-1761210000000-6f1c2b9e-3d4a-4f5b-8c7d-1e2f3a4b5c6d \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"scheduledAt": "2026-11-03T14:30:00Z",
"assigneeEmail": "other.operator@subsidiary.com"
}'
The response is the updated video call.
A new date sends an updated invitation to the guest and a confirmation to the person in charge. A change of person in charge on a dated video call sends a confirmation to the new person in charge.
Response codes:
200 OK: video call rescheduled400 Bad Request: no field to change, or invalid field403 Forbidden: rescheduling right missing404 Not Found: unknown video call, or outside your scope409 Conflict: video call already launched; it stays unchanged422 Unprocessable Entity: person in charge not found in your company or its subsidiaries
Errors common to all routes
| Code | Cause |
|---|---|
401 Unauthorized or 403 Forbidden | Missing, invalid or expired token |
403 Forbidden | Video call right missing for this route |
423 Locked | API access suspended for your company (unpaid invoice): contact your administrator |
429 Too Many Requests | Rate limit reached (see below) |
Excerpt of an error body:
{
"statusCode": 409,
"message": "Session VIS-… is in status CREATED: it can no longer be modified once the video call has started",
"codeError": "visioSession.notEditable",
"requestId": "b3f1c2e4-...",
"details": {
"header": "Error on request: b3f1c2e4-..."
}
}
The message is written in the language of the Accept-Language header (French, English or Spanish). To react to an error in your code, rely on statusCode and codeError, never on the message text. Share the requestId with support if you need help.
Rate limits
Each route accepts 60 requests per minute per company. Counting and headers (Retry-After, X-RateLimit-*) follow the same rules as the rest of the API: see Rate limits.
Endpoints summary
| Method | Endpoint | Description |
|---|---|---|
POST | /v2/certificall/api/visio-sessions | Schedule a video call |
GET | /v2/certificall/api/visio-sessions | List the video calls of your company and its subsidiaries |
GET | /v2/certificall/api/visio-sessions/:id | View a video call |
PATCH | /v2/certificall/api/visio-sessions/:id | Reschedule a video call (date and/or person in charge) |