Skip to main content

Item Management

This document details the different methods for adding items (data elements) to a case in the Certificall application.


v2 contract — naming the depositing application​

The POST /items/... endpoints without the /v2 prefix are deprecated

They keep working exactly as before and their URLs do not change: no existing integration is broken. They no longer appear in the Swagger and will eventually be removed. Migrate to /v2 when you can.

Why​

When a file is captured by your application and then deposited through our API, Certificall sees neither the device nor the actual time of capture. The certificate therefore carries an "Origin of the capture" panel naming the depositing application and stating who is responsible for what:

Certificall attests to the receipt and timestamping of this file. The capture is the act of the depositing application.

For a deposit without a file (text, date, time, email, number, select), nothing is timestamped: the clause reads "Certificall attests to the receipt of this data. Its entry is the act of the depositing application." Qualified timestamping applies to items carrying a file — photo, video, signature, document.

Without your application's name, that panel names no one — and a certificate that does not identify who performed the capture protects neither you nor your customer.

Three required fields​

FieldFormatWhat it becomes on the certificate
clientAppNametextApplication name, under "Depositing application"
clientAppVersiontextVersion shown after the name — lets you date an incident and recall a fleet
frontCreatedAtISO 8601Declared capture time. When absent, the line is not displayed

The userDevice* fields remain required as in v1 and feed "Declared environment". The IP address printed on the certificate is the one observed by our servers, never a value sent in the request body.

Endpoints​

MethodURLPurpose
POST/v2/items/createNon-media item (text, select, date, email, number, time)
POST/v2/items/:caseIdPhoto, video, signature or document
POST/v2/items/:caseId/documentDocument only, with the API > File > Create permission

Request bodies, permissions and response codes are identical to their v1 counterparts, apart from the three fields above.

Example​

curl -X POST 'https://admin.certificall.app/v2/certificall/api/items/798' \
-H 'Authorization: Bearer <Your_JWT_Token>' \
-F 'file=@meter.jpg' \
-F 'createItemDto={
"stepId": 1,
"data": "meter.jpg",
"clientAppName": "AquaReleve Web",
"clientAppVersion": "3.8.2",
"frontCreatedAt": "2026-08-21T14:29:41+02:00",
"userDeviceManufacturer": "Samsung",
"userDeviceModel": "SM-S928B",
"userDeviceName": "field-survey",
"userDevicePlatform": "Chrome 141",
"userDeviceOs": "Android",
"userDeviceOsVersion": "15",
"geolocLatitude": "47.393210",
"geolocLongitude": "0.689410",
"companyId": 25,
"caseId": 798
}'

Contract errors​

A missing field returns a 400 that names the field and states what to send:

{
"message": "Missing required field(s) in createItemDto: clientAppName, clientAppVersion. The certificate must name the application that performed the capture. Send clientAppName (your application name), clientAppVersion (its version) and frontCreatedAt (capture date, ISO 8601)."
}

A malformed capture date also returns a 400, restating the expected format.

Migrating from v1​

  1. Prefix the URL with /v2
  2. Add clientAppName, clientAppVersion and frontCreatedAt to createItemDto

Nothing else changes. Until you migrate, deposits made on the old endpoints display your API account identifier instead of the application name.


Creating an Item without a file​

Endpoint: POST /v2/items/create​

Description​

This endpoint lets users create items in a case. Allowed item types are: text, select, date, email, number and time. Media types (photo, video, signature) and documents (file upload) are not allowed through this endpoint.

Request​

  • URL: /v2/certificall/api/items/create

  • HTTP Method: POST

  • Required headers:

    Authorization: Bearer <Your_JWT_Token>
    Content-Type: application/json

Request Body (Payload)​

  • caseId (Number, required): Identifier of the case to add the item to.
  • stepId (Number, required): Step identifier (obtained from the /frames endpoint).
  • data (String, required): Item data (the format depends on the step type).
  • clientAppName (String, required): Name of the application that entered the data.
  • clientAppVersion (String, required): Version of the application.
  • frontCreatedAt (ISO 8601 String, required): Date and time of the entry.
  • pos (Number, optional): Position of the item in a multi-step (default: 0).

Request body example for a text field:

{
"caseId": 12345,
"stepId": 101,
"data": "Comment: Compliant installation",
"clientAppName": "AquaReleve Web",
"clientAppVersion": "3.8.2",
"frontCreatedAt": "2026-08-21T14:29:41+02:00",
"pos": 0
}

For a date or a number, only data changes: "2024-01-15", "42.5".

cURL Request Example​

curl -X POST "https://admin.certificall.app/v2/certificall/api/items/create" \
-H "Authorization: Bearer your_jwt_token" \
-H "Content-Type: application/json" \
-d '{
"caseId": 12345,
"stepId": 102,
"data": "2024-01-15",
"clientAppName": "AquaReleve Web",
"clientAppVersion": "3.8.2",
"frontCreatedAt": "2026-08-21T14:29:41+02:00"
}'

Allowed Item Types​

The following item types are allowed:

  • TEXT_FIELD: Free text field
  • SELECT: Selection list
  • DATE_FIELD: Date
  • EMAIL: Email address
  • NUMBER_FIELD: Number
  • TIME: Time

The following types are forbidden and must use the /v2/items/:caseId endpoint:

  • PHOTOGRAPHY: Photo
  • VIDEO: Video
  • SIGNATURE: Signature
  • DOCUMENT_UPLOAD: Document — use /v2/items/:caseId/document (API > File > Create permission, see below) or /v2/items/:caseId

Required Permissions​

  • Permission API > File > Create.

Responses​

Successful response:

  • Status Code: 200 OK
  • Description: The item was created successfully.

Successful response example:

{
"id": 98765,
"cfRef": "ITM-98765"
}

Error responses:

  • Status Code: 400 Bad Request

  • Description: The request is invalid (v2 contract field missing or malformed, missing Step ID, or maximum limit reached).

  • Status Code: 403 Forbidden

  • Description: Type not allowed through this endpoint (photo/video/signature/document).

  • Status Code: 404 Not Found

  • Description: The specified case or step does not exist.

Use Cases​

Use this endpoint to add non-media data to a case:

  • Text comments
  • Drop-down list selections
  • Intervention dates
  • Email contacts
  • Numeric measurements
  • Intervention times

Adding an Item with a File​

Endpoint: POST /v2/items/:caseId​

Description​

This endpoint lets users add an item to a case with a file upload. It is particularly suited to photos, videos, signatures and documents.

Request​

  • URL: /v2/certificall/api/items/:caseId

  • HTTP Method: POST

  • Path parameters:

    • caseId: number - The unique identifier of the case.
  • Required headers:

    Authorization: Bearer <Your_JWT_Token>
    Content-Type: multipart/form-data

Request Body (Multipart Form-Data)​

The request must be sent as multipart/form-data and contain the following fields:

file field (optional):

  • Type: Binary file (image, video, etc.)
  • Description: The file to upload (required for photo, video, signature and document items)

createItemDto field (required):

  • Type: Stringified JSON
  • Description: JSON object holding the item information

createItemDto structure:

  • companyId (Number, required): Company identifier.
  • stepId (Number, required): Step identifier (obtained from /frames).
  • data (String, required): Item data, or the file name for photos.
  • clientAppName (String, required): Name of the application that performed the capture.
  • clientAppVersion (String, required): Version of that application.
  • frontCreatedAt (ISO 8601 String, required): Actual date and time of the capture (for instance for an offline capture).
  • caseId (Number, optional): Case identifier (can be omitted since it is already in the URL).
  • userDeviceManufacturer (String, required): Device manufacturer.
  • userDeviceModel (String, required): Device model.
  • userDeviceName (String, required): Device name.
  • userDevicePlatform (String, required): Device platform (iOS, Android, etc.).
  • userDeviceOs (String, required): Operating system.
  • userDeviceOsVersion (String, required): Operating system version.
  • userDeviceCarrierIpAddress (String, optional): Mobile network IP address.
  • userDeviceWifiIpAddress (String, optional): WiFi network IP address.
  • geolocLatitude (String, optional): Latitude (required for photos).
  • geolocLongitude (String, optional): Longitude (required for photos).
  • geolocAccuracy (String, optional): Geolocation accuracy.

cURL Request Example​

curl -X POST "https://admin.certificall.app/v2/certificall/api/items/12345" \
-H "Authorization: Bearer your_jwt_token" \
-F "file=@/path/to/photo.jpg" \
-F 'createItemDto={
"companyId": 1,
"stepId": 101,
"data": "front_photo.jpg",
"clientAppName": "AquaReleve Web",
"clientAppVersion": "3.8.2",
"frontCreatedAt": "2026-05-28T10:30:00+02:00",
"userDeviceManufacturer": "Apple",
"userDeviceModel": "iPhone 13",
"userDeviceName": "John's iPhone",
"userDevicePlatform": "iOS",
"userDeviceOs": "iOS",
"userDeviceOsVersion": "16.0",
"geolocLatitude": "48.8566",
"geolocLongitude": "2.3522",
"geolocAccuracy": "5.0"
}'

Responses​

Successful response:

  • Status Code: 200 OK
  • Description: The item was created and the file uploaded successfully.

Successful response example:

{
"id": 98765,
"cfRef": "ITM-98765",
"fileUrl": "https://certificall.app/files/front_photo.jpg"
}

Error responses:

  • Status Code: 400 Bad Request

  • Description: The request is invalid (v2 contract field missing, missing or incorrect parameters).

  • Status Code: 403 Forbidden

  • Description: You do not have the required permissions, or the case does not belong to your company.

  • Status Code: 413 Payload Too Large

  • Description: The uploaded file is too large.

Required Permissions​

  • Permission API > Item > Create.
  • The case must belong to your company.
  • Your company must be allowed to use this API; contact Certificall to find out whether it is.

Supported Item Types​

This endpoint supports every item type, including:

  • PHOTOGRAPHY: Photos with geolocation
  • VIDEO: Videos
  • SIGNATURE: Signatures
  • DOCUMENT_UPLOAD: Documents
  • TEXT_FIELD, SELECT, DATE_FIELD, EMAIL, NUMBER_FIELD, TIME: Non-media items

Use Cases​

Use this endpoint to:

  • Add photos with location metadata
  • Upload inspection videos
  • Capture digital signatures
  • Add any type of item with full device traceability

Uploading a Document (case creation permission)​

Endpoint: POST /v2/items/:caseId/document​

Description​

Uploads a document (PDF, JPEG, PNG) to a DOCUMENT_UPLOAD step with the API > File > Create permission alone — without the API > Item > Create media permission (reserved for photos, videos and signatures).

This endpoint only accepts DOCUMENT_UPLOAD steps (403 otherwise, 404 if the step does not exist). Same file constraints as the general endpoint: max size ~10 MB, actual file type checked. If the step has document analysis configured, it is triggered automatically and asynchronously.

The request format (multipart file + createItemDto, including the three v2 contract fields) is identical to POST /v2/items/:caseId above.

Detailed documentation (examples, error codes, retrieving the analysis result): see API — Document analysis.


v1 endpoints (deprecated)​

To migrate

These URLs still work exactly as before, but they no longer appear in the Swagger and will eventually be removed. Deposits made through them display your API account identifier instead of the application name on the certificate. See Migrating from v1.

v1 endpoint (deprecated)Replaced by
POST /certificall/api/items/createPOST /v2/certificall/api/items/create
POST /certificall/api/items/:caseIdPOST /v2/certificall/api/items/:caseId
POST /certificall/api/items/:caseId/documentPOST /v2/certificall/api/items/:caseId/document

The v1 request body is the same as the v2 one, without clientAppName or clientAppVersion; frontCreatedAt is optional there.


Security and Best Practices​

  • First fetch the list of available steps through the /frames endpoint to get valid stepId values.
  • Make sure the data format matches the expected step type.
  • For photos, geolocation (geolocLatitude, geolocLongitude) is required.
  • Always include full device information to ensure traceability.
  • Limit the size of uploaded files to avoid timeout errors.
  • Check that the case is not closed yet before adding items.
  • Interactions with the Certificall API must always go through a secure connection (HTTPS).

By following these instructions, you can safely add items to your cases through the Certificall API.