Skip to main content

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.

For API and SDK integrators

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 startDate and endDate; 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 metadata field 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 in caseContext is 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
}
FieldTypeDescription
companyIdNumberCompany identifier.
apiSettingsArrayConfigured integrations, including the webhook (caseHook).
apiSettings[].apiNameStringIntegration name.
apiSettings[].endpointsObjectURLs called by Certificall.
apiSettings[].authorizationHeaderStringAuthentication method: authorization or security-token.
apiSettings[].hasCredentialsBooleantrue if a token is registered. The token itself is never returned.
pdfOptionsObjectSettings of the company's PDF certificate.
langStringCompany language.
casesSharableBooleantrue 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.

Full journey
  1. Create the child company (POST /companies) and keep its id.
  2. Create its users (POST /users) with this companyId.
  3. Create its cases with POST /cases/create: userMail of a user of the child company, or childCompanyId for 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.