Company Management
This document details the operation and usage of the endpoints for managing companies in the Certificall application.
Company listing
Endpoint: GET /companies
Description
The endpoint retrieves your company and the whole hierarchy of linked companies.
Authentication
Access to this endpoint requires valid authentication. Include a JWT (JSON Web Token) in the header of your HTTP request as follows:
Authorization: Bearer <Your_JWT_Token>
HTTP Request
Method: GET
URL: /companies
Example:
curl -X 'GET' \
'https://admin.certificall.app/certificall/api/companies' \
-H 'accept: application/json' \
-H 'Authorization: Bearer xxxx'
Responses
200 OK: Returns a list of companies with their Id, their name, the parent company's ID and the depth level.
Response example:
{
"descendants": [
{
"id": 1,
"name": "Ent1",
"parentId": null,
"niveau": 0
},
{
"id": 2,
"name": "Ent2",
"parentId": 1,
"niveau": 1
},
{
"id": 6,
"name": "Ent6",
"parentId": 1,
"niveau": 1
}
]
}
400 Bad Request: The request is invalid, usually due to missing or incorrect parameters.
500 Internal Server Error: Internal server error preventing request processing.
Consumption
Endpoint: GET /companies/consumption
Description
The endpoint returns the consumption of your company and of all its child companies over a period: number of photos, videos and signatures. One line per company in the hierarchy, yours included, plus a consolidated total.
The counting rules are those of our internal tracking: an element is counted when it is closed and created within the period. Signatures are counted separately here; on the invoice, they are counted together with photos.
This endpoint lets you track your actual consumption from your own information system, and break it down by report or by your business dimensions. The full journey, from capture to reconciliation, is described in Tracking your actual consumption.
Authentication
Access to this endpoint requires valid authentication. Include a JWT (JSON Web Token) in the header of your HTTP request as follows:
Authorization: Bearer <Your_JWT_Token>
HTTP Request
Method: GET
URL: /companies/consumption
Example:
curl -X 'GET' \
'https://admin.certificall.app/certificall/api/companies/consumption?startDate=2026-08-01&endDate=2026-08-31' \
-H 'accept: application/json' \
-H 'Authorization: Bearer xxxx'
Query parameters
- startDate (String, required): start of the period, inclusive. ISO 8601 with timezone, or date only (
2026-08-01, read as midnight UTC). - endDate (String, required): end of the period, inclusive. A date only is extended to the end of the UTC day. Maximum range: 31 days between
startDateandendDate; beyond that, the request is rejected (400) with a reminder of the limit and of the requested period. For a quarter, chain three calls. - reportToken (String, optional): only counts the cases linked to this report.
- metadata (Object, optional): only counts the cases carrying all of these metadata, as supplied in the case's
metadatafield on creation (POST /cases/create, Certilink or SDK). Syntax:metadata[site]=Paris&metadata[zone]=A1. Same limits as the field: 20 keys, 40 characters per key, 500 per value. Metadata sent incaseContextis not taken into account.
Required Permissions
- The user must have the API > Consumption > Consult permission.
Responses
200 OK: the period used, the total over the whole hierarchy and one line per company. A company with no consumption over the period appears with zeros.
{
"period": { "startDate": "2026-08-01T00:00:00.000Z", "endDate": "2026-08-31T23:59:59.999Z" },
"total": { "photos": 128, "videos": 9, "signatures": 41 },
"companies": [
{ "id": 1, "name": "Ent1", "parentId": null, "photos": 100, "videos": 9, "signatures": 30 },
{ "id": 2, "name": "Ent2", "parentId": 1, "photos": 28, "videos": 0, "signatures": 11 },
{ "id": 6, "name": "Ent6", "parentId": 1, "photos": 0, "videos": 0, "signatures": 0 }
]
}
400 Bad Request: missing period, startDate after endDate, range above 31 days, or metadata out of bounds.
403 Forbidden: API > Consumption > Consult permission missing.
429 Too Many Requests: limit exceeded — 30 calls per minute and per company on this endpoint.
Company options
Endpoint: GET /company-options
Description
The endpoint returns the options of your token's company, including the webhook configuration. Secrets are never returned: only their presence is indicated.
HTTP Request
Method: GET
URL: /company-options
Example:
curl -X 'GET' \
'https://admin.certificall.app/certificall/api/company-options' \
-H 'accept: application/json' \
-H 'Authorization: Bearer xxxx'
Required Permissions
- The user must have the API > My company > Consult permission.
Responses
200 OK:
{
"companyId": 42,
"apiSettings": [
{
"apiName": "caseHook",
"endpoints": { "sendCase": "https://your-domain.com/webhooks/certificall/case" },
"authorizationHeader": "authorization",
"hasCredentials": true
}
],
"pdfOptions": {},
"lang": "fr",
"casesSharable": true
}
| Field | Type | Description |
|---|---|---|
companyId | Number | Company identifier. |
apiSettings | Array | Configured integrations, including the webhook (caseHook). |
apiSettings[].apiName | String | Integration name. |
apiSettings[].endpoints | Object | URLs called by Certificall. |
apiSettings[].authorizationHeader | String | Authentication method: authorization or security-token. |
apiSettings[].hasCredentials | Boolean | true if a token is registered. The token itself is never returned. |
pdfOptions | Object | Settings of the company's PDF certificate. |
lang | String | Company language. |
casesSharable | Boolean | true if the company's cases can be shared through a link. |
To change the webhook configuration, use POST /company-options/api-settings.
403 Forbidden: API > My company > Consult permission missing.
404 Not Found: no options registered for this company.
Creating a child company
Endpoint: POST /companies
Description
The endpoint creates a company directly attached to yours: the parent company is always the one of your token, never a parameter. It is meant for resellers and integrators who open a Certificall account for each of their customers without going through the admin interface.
The created company consumes your company's credits. It then appears in the hierarchy returned by GET /companies.
- Create the child company (
POST /companies) and keep itsid. - Create its users (
POST /users) with thiscompanyId. - Create its cases with
POST /cases/create:userMailof a user of the child company, orchildCompanyIdfor a case through Certilink.
HTTP Request
Method: POST
URL: /companies
Example:
curl -X 'POST' \
'https://admin.certificall.app/certificall/api/companies' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer xxxx' \
-d '{ "name": "Dupont Builders" }'
Request body
- name (String, required): name of the child company, 255 characters at most.
An unknown field is rejected (400), never ignored. Replaying the request creates a second company: call it only once per customer.
Required Permissions
- The user must have the API > Subsidiary companies > Create permission.
Responses
201 Created:
{ "id": 1234, "name": "Dupont Builders" }
400 Bad Request: missing or empty name, or unknown field.
403 Forbidden: API > Subsidiary companies > Create permission missing.
Creating a user
Endpoint: POST /users
Description
The endpoint creates a user in your company or one of your child companies. The account is active right away, with the supplied password: the user signs in to the app and to the admin interface with their email and this password. No admin permission is required from your integration account.
HTTP Request
Method: POST
URL: /users
Example:
curl -X 'POST' \
'https://admin.certificall.app/certificall/api/users' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer xxxx' \
-d '{
"email": "paul.dupont@example.com",
"firstname": "Paul",
"lastname": "Dupont",
"password": "Chosen-password-123",
"companyId": 1234
}'
Request body
- email (String, required): sign-in email, unique across the whole platform.
- firstname, lastname (String, required).
- password (String, required): account password.
- companyId (Number, required): your company or one of your child companies.
Permissions cannot be chosen: a body containing roleToAdd is rejected (400).
The created user can access the mobile app and the admin interface. They can view, create and edit frames, cases, their company and its users, and add videos to frames. They can neither delete nor validate cases, and cannot use the API.
Your integration account does not need to hold these permissions: the API > User > Create permission is enough.
Required Permissions
- The user must have the API > User > Create permission.
Responses
201 Created:
{
"id": 5678,
"email": "paul.dupont@example.com",
"firstname": "Paul",
"lastname": "Dupont",
"roles": ["r_app:user", "r_bo:user", "p_bo:frame:read", "…", "p_bo:option:video"],
"companyId": 1234
}
The roles field lists, for information only, the permissions granted automatically to the user.
400 Bad Request: missing or invalid field, unknown field, or presence of roleToAdd.
403 Forbidden: API > User > Create permission missing, or a companyId that is neither your company nor one of your child companies.
409 Conflict: email already in use.