Managing frames
A frame describes what is to be collected in a case: the list of its steps (photo, signature, text field, document…), their order, whether they are mandatory and their display conditions. A case or a Certilink is always created from a frame (see Creating a certificate and Certilink).
These endpoints let you list, create, update and delete your company's frames.
Authentication: Authorization: Bearer <your_token> (see Authentication).
| Operation | Endpoint |
|---|---|
| List frames | GET /certificall/api/frames |
| Create a frame | POST /certificall/api/frames |
| Update a frame | PATCH /certificall/api/frames/{frameId} |
| Delete a frame | DELETE /certificall/api/frames/{frameId} |
Each operation requires the matching permission on frames (read, create, update, delete). Without it, the API responds with 403.
List frames
GET /certificall/api/frames
Returns the frames to use when creating a case: your company's own frames, as well as those attached to it in its company hierarchy.
Parameters: none.
Example
curl -X GET 'https://admin.certificall.app/certificall/api/frames' \
-H 'accept: application/json' \
-H 'Authorization: Bearer xxxx'
200 response: an array of frames.
[
{
"id": 12,
"name": "État des lieux",
"steps": [
{
"id": 101,
"title": "Photo de la façade",
"description": "Prendre la photo depuis la rue",
"stepAction": "PHOTOGRAPHY",
"isMandatory": true,
"groupId": null,
"pos": 0,
"min": null,
"max": null,
"parameters": null,
"visibleIf": null,
"scoring": null
},
{
"id": 102,
"title": "Pièce d'identité",
"description": null,
"stepAction": "DOCUMENT_UPLOAD",
"isMandatory": false,
"groupId": 7,
"pos": 0,
"min": null,
"max": null,
"parameters": null,
"visibleIf": null,
"scoring": null
}
],
"groups": [
{
"id": 7,
"name": "Pièces justificatives",
"description": null,
"pos": 1,
"isMandatory": false,
"min": 1,
"max": 1,
"visibleIf": null,
"groups": []
}
]
}
]
Frame shape
| Field | Type | Description |
|---|---|---|
id | number | Frame identifier. |
name | string | Frame name. |
steps | array | All the steps of the frame, including those in groups. groupId gives the group that holds the step, null for a step outside any group. |
groups | array | The tree of groups, without their steps (these are in steps). |
When reading, steps contains every step, groups included. When writing (create, update), steps only contains the steps outside any group: the steps of a group are declared in that group's own steps.
Step shape
| Field | Type | Description |
|---|---|---|
id | number | Step identifier. |
title | string | Displayed title. |
description | string or null | Displayed instruction. |
stepAction | string | Step type (see Step types). |
isMandatory | boolean | Whether the step is mandatory. |
groupId | number or null | Group that holds the step, null if outside any group. |
pos | number | Position of the element in its container (the frame or its group). Steps and groups of the same container share the same numbering. |
min / max | number or null | Minimum / maximum number of repetitions of the step. |
parameters | object or null | Step-specific parameters (free-form JSON). |
visibleIf | object or null | Display conditions (see Display conditions). |
scoring | array or null | Scoring grid of the step, read-only. |
Group shape
| Field | Type | Description |
|---|---|---|
id | number | Group identifier. |
name | string | Group name. |
description | string or null | Group description. |
pos | number | Position of the group among the steps of its container. |
isMandatory | boolean | Whether the group is mandatory. |
min / max | number | Minimum / maximum number of repetitions of the group. |
visibleIf | object or null | Display conditions of the group. |
groups | array | Sub-groups. |
Other responses
401— missing or invalid token.403— your account is not allowed to read frames.429— request quota exceeded (see Rate limits).
Create a frame
POST /certificall/api/frames
Creates a frame for your company, with its steps and, if needed, its groups of steps.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
name | string | yes | Frame name. |
attachmentType | string | no | Attachment type of the frame: DOCX, LINK, PDF or PUBLIC_LINK. |
confirmBeforeClose | boolean | no | Asks for confirmation before closing the case. |
endSessionOnComplete | boolean | no | Ends the session once the case is complete. |
steps | array of steps | no | The steps outside any group, in display order. |
groups | array of groups | no | The groups of steps, in display order. They are displayed after the steps outside any group. |
A frame must contain at least one step, outside any group or inside a group. Otherwise the API responds with 400.
Step (items of steps)
| Name | Type | Required | Description |
|---|---|---|---|
id | number | no | Omit on creation. Provide to update an existing step (see Update a frame). |
title | string | yes | Step title. |
stepAction | string | yes | Step type (see Step types). |
description | string | no | Displayed instruction. |
isMandatory | boolean | no | Mandatory step. Default: false. |
min / max | number | no | Minimum / maximum number of repetitions of the step (integers, min ≥ 0 and max ≥ 1). |
parameters | object | no | Step-specific parameters (free-form JSON). |
visibleIf | object | no | Display conditions (see Display conditions). |
Group (items of groups)
| Name | Type | Required | Description |
|---|---|---|---|
id | number | no | Omit on creation, provide to update an existing group. |
name | string | yes | Group name. |
description | string | no | Group description. |
isMandatory | boolean | no | Mandatory group. Default: false. |
min / max | number | no | Minimum / maximum number of repetitions of the group. Default: 1. |
visibleIf | object | no | Display conditions of the group. |
steps | array of steps | no | The steps of the group, in display order. |
groups | array of groups | no | Sub-groups, same shape (without groups). Maximum depth: 2. |
Example
curl -X POST 'https://admin.certificall.app/certificall/api/frames' \
-H 'Authorization: Bearer xxxx' \
-H 'Content-Type: application/json' \
-d '{
"name": "État des lieux",
"confirmBeforeClose": true,
"steps": [
{
"title": "Photo de la façade",
"description": "Prendre la photo depuis la rue",
"stepAction": "PHOTOGRAPHY",
"isMandatory": true
}
],
"groups": [
{
"name": "Pièces justificatives",
"steps": [
{ "title": "Pièce d'\''identité", "stepAction": "DOCUMENT_UPLOAD" }
]
}
]
}'
Responses
201— the created frame, in the same shape as in the list.400— invalid body (missing field, value outside the allowed list, no step, groups nested more than 2 levels deep) or error during creation.401— missing or invalid token.403— missing permission to create frames.429— request quota exceeded.
Update a frame
PATCH /certificall/api/frames/{frameId}
Updates a frame's settings and/or its steps.
Path parameter
| Name | Type | Required | Description |
|---|---|---|---|
frameId | number | yes | Frame identifier. Only frames created by your company (or its child companies) can be updated. |
Request body: same fields as for creation, all optional. A missing field is left unchanged.
For steps and groups, the list you send replaces the existing one:
| In the list you send | Effect |
|---|---|
item with an id | updated |
item without an id | created |
| item of the frame missing from the list | deleted |
- The order of the arrays defines the display order (
posis recomputed). - A group missing from
groupsis deleted along with its steps. - The steps of a kept group are only replaced if its
stepsis provided: omitting it leaves them in place, providing it empty deletes them. - If
stepsorgroupsis omitted, that level is left untouched.
To change a single step, send back all the others with their id (retrieved with GET /frames). A step left out of the list is deleted.
Example: rename the frame and change a step's title, without deleting anything
curl -X PATCH 'https://admin.certificall.app/certificall/api/frames/12' \
-H 'Authorization: Bearer xxxx' \
-H 'Content-Type: application/json' \
-d '{
"name": "État des lieux d'\''entrée",
"steps": [
{ "id": 101, "title": "Façade (vue de la rue)", "stepAction": "PHOTOGRAPHY", "isMandatory": true }
],
"groups": [
{ "id": 7, "name": "Pièces justificatives" }
]
}'
Responses
200— the updated frame (same shape as in the list).400— invalid body, frame left without any step, or error during the update.401— missing or invalid token, or frame not created by your company.403— missing permission to update frames.404— frame not found.429— request quota exceeded.
Delete a frame
DELETE /certificall/api/frames/{frameId}
Deletes a frame. The deletion is logical (soft delete): the frame is no longer offered.
Path parameter
| Name | Type | Required | Description |
|---|---|---|---|
frameId | number | yes | Frame identifier. Only frames created by your company (or its child companies) can be deleted. |
Example
curl -X DELETE 'https://admin.certificall.app/certificall/api/frames/12' \
-H 'Authorization: Bearer xxxx'
200 response
{ "id": 12 }
Other responses
400— error during deletion.401— missing or invalid token, or frame not created by your company.403— missing permission to delete frames.404— frame not found.429— request quota exceeded.
Step types
Possible values of stepAction:
| Value | Step |
|---|---|
PHOTOGRAPHY | Photo |
VIDEO | Video |
SIGNATURE | Signature |
DOCUMENT_UPLOAD | Document upload |
TEXT_FIELD | Text field |
NUMBER_FIELD | Number field |
DATE_FIELD | Date field |
TIME | Time field |
EMAIL | Email address |
SELECT | Choice from a list |
Display conditions
visibleIf shows a step or a group only if a previous answer has a given value. Example: the step only appears if step 3 has the value CNI.
{ "allOf": [{ "stepId": 3, "operator": "equals", "value": "CNI" }] }
allOf requires all conditions to be true; anyOf requires at least one.
Scoring grid
A step's scoring field is returned read-only: the scoring grid is set in the frame editor of the administration interface. It is ignored on creation and update through the API.
Rate limits
These endpoints follow the default limit (60 requests per minute and per endpoint). See Rate limits.