Skip to main content

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).

OperationEndpoint
List framesGET /certificall/api/frames
Create a framePOST /certificall/api/frames
Update a framePATCH /certificall/api/frames/{frameId}
Delete a frameDELETE /certificall/api/frames/{frameId}
Required permissions

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​

FieldTypeDescription
idnumberFrame identifier.
namestringFrame name.
stepsarrayAll the steps of the frame, including those in groups. groupId gives the group that holds the step, null for a step outside any group.
groupsarrayThe tree of groups, without their steps (these are in steps).
Reading and writing are not symmetrical

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​

FieldTypeDescription
idnumberStep identifier.
titlestringDisplayed title.
descriptionstring or nullDisplayed instruction.
stepActionstringStep type (see Step types).
isMandatorybooleanWhether the step is mandatory.
groupIdnumber or nullGroup that holds the step, null if outside any group.
posnumberPosition of the element in its container (the frame or its group). Steps and groups of the same container share the same numbering.
min / maxnumber or nullMinimum / maximum number of repetitions of the step.
parametersobject or nullStep-specific parameters (free-form JSON).
visibleIfobject or nullDisplay conditions (see Display conditions).
scoringarray or nullScoring grid of the step, read-only.

Group shape​

FieldTypeDescription
idnumberGroup identifier.
namestringGroup name.
descriptionstring or nullGroup description.
posnumberPosition of the group among the steps of its container.
isMandatorybooleanWhether the group is mandatory.
min / maxnumberMinimum / maximum number of repetitions of the group.
visibleIfobject or nullDisplay conditions of the group.
groupsarraySub-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

NameTypeRequiredDescription
namestringyesFrame name.
attachmentTypestringnoAttachment type of the frame: DOCX, LINK, PDF or PUBLIC_LINK.
confirmBeforeClosebooleannoAsks for confirmation before closing the case.
endSessionOnCompletebooleannoEnds the session once the case is complete.
stepsarray of stepsnoThe steps outside any group, in display order.
groupsarray of groupsnoThe groups of steps, in display order. They are displayed after the steps outside any group.
At least one step

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)

NameTypeRequiredDescription
idnumbernoOmit on creation. Provide to update an existing step (see Update a frame).
titlestringyesStep title.
stepActionstringyesStep type (see Step types).
descriptionstringnoDisplayed instruction.
isMandatorybooleannoMandatory step. Default: false.
min / maxnumbernoMinimum / maximum number of repetitions of the step (integers, min ≥ 0 and max ≥ 1).
parametersobjectnoStep-specific parameters (free-form JSON).
visibleIfobjectnoDisplay conditions (see Display conditions).

Group (items of groups)

NameTypeRequiredDescription
idnumbernoOmit on creation, provide to update an existing group.
namestringyesGroup name.
descriptionstringnoGroup description.
isMandatorybooleannoMandatory group. Default: false.
min / maxnumbernoMinimum / maximum number of repetitions of the group. Default: 1.
visibleIfobjectnoDisplay conditions of the group.
stepsarray of stepsnoThe steps of the group, in display order.
groupsarray of groupsnoSub-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

NameTypeRequiredDescription
frameIdnumberyesFrame 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 sendEffect
item with an idupdated
item without an idcreated
item of the frame missing from the listdeleted
  • The order of the arrays defines the display order (pos is recomputed).
  • A group missing from groups is deleted along with its steps.
  • The steps of a kept group are only replaced if its steps is provided: omitting it leaves them in place, providing it empty deletes them.
  • If steps or groups is omitted, that level is left untouched.
Send the full list

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

NameTypeRequiredDescription
frameIdnumberyesFrame 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:

ValueStep
PHOTOGRAPHYPhoto
VIDEOVideo
SIGNATURESignature
DOCUMENT_UPLOADDocument upload
TEXT_FIELDText field
NUMBER_FIELDNumber field
DATE_FIELDDate field
TIMETime field
EMAILEmail address
SELECTChoice 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.