Skip to main content

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>
Base URL

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​

StatusMeaningReschedulable
READYScheduled, not launched yetYes
CREATEDLaunched by the person in chargeNo
INITIATEDThe guest has joined the video callNo
COMPLETEDVideo call endedNo
ERRORVideo call in errorNo

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:

FieldTypeRequiredDescription
assigneeEmailStringyesEmail of the person in charge: a user of your company or of one of its subsidiaries
firstNameStringyesGuest's first name (100 characters max.)
lastNameStringyesGuest's last name (100 characters max.)
phoneNumberStringyesGuest's phone number (30 characters max.)
emailStringnoGuest's email
scheduledAtStringnoDate and time of the video call, ISO 8601 format (e.g. 2026-11-02T09:00:00Z)
reportTokenStringnoReport identifier to attach the video call's case to (100 characters max.)
expectedAddressStringnoExpected address of the video call location: street, 5-digit postal code and city
expectedLatitudeStringnoLatitude of the expected address
expectedLongitudeStringnoLongitude 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.

Invitations sent automatically

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 scheduled
  • 400 Bad Request: missing or invalid field (including a missing assigneeEmail)
  • 403 Forbidden: scheduling right missing
  • 422 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):

NameTypeDescription
statusStringFilter on a status (READY, CREATED, INITIATED, COMPLETED, ERROR)
scheduledFromStringVideo calls scheduled from this date (ISO 8601, inclusive)
scheduledToStringVideo calls scheduled up to this date (ISO 8601, inclusive)
limitNumberNumber of video calls per page, from 1 to 200 (default: 50)
offsetNumberNumber 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 returned
  • 400 Bad Request: invalid parameter (including scheduledFrom later than scheduledTo)
  • 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 returned
  • 403 Forbidden: viewing right missing
  • 404 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):

FieldTypeDescription
scheduledAtString or nullNew date (ISO 8601), or null to remove the date
assigneeEmailStringEmail 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.

Notifying participants

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 rescheduled
  • 400 Bad Request: no field to change, or invalid field
  • 403 Forbidden: rescheduling right missing
  • 404 Not Found: unknown video call, or outside your scope
  • 409 Conflict: video call already launched; it stays unchanged
  • 422 Unprocessable Entity: person in charge not found in your company or its subsidiaries

Errors common to all routes​

CodeCause
401 Unauthorized or 403 ForbiddenMissing, invalid or expired token
403 ForbiddenVideo call right missing for this route
423 LockedAPI access suspended for your company (unpaid invoice): contact your administrator
429 Too Many RequestsRate 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​

MethodEndpointDescription
POST/v2/certificall/api/visio-sessionsSchedule a video call
GET/v2/certificall/api/visio-sessionsList the video calls of your company and its subsidiaries
GET/v2/certificall/api/visio-sessions/:idView a video call
PATCH/v2/certificall/api/visio-sessions/:idReschedule a video call (date and/or person in charge)