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

Field	Format	What it becomes on the certificate
`clientAppName`	text	Application name, under "Depositing application"
`clientAppVersion`	text	Version shown after the name — lets you date an incident and recall a fleet
`frontCreatedAt`	ISO 8601	Declared 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

Method	URL	Purpose
`POST`	`/v2/items/create`	Non-media item (text, select, date, email, number, time)
`POST`	`/v2/items/:caseId`	Photo, video, signature or document
`POST`	`/v2/items/:caseId/document`	Document only, with the `p_api:case: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

Prefix the URL with /v2
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

Endpoint: `POST /items/create`

Description

This API endpoint allows users to create items in a case. The authorized item types are: text, selection, date, email, number, and time. Media types (photo, video, signature) are not authorized via this endpoint.

Request

URL: /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 via the /frames endpoint).
data (String, required): Item data (format depends on the step type).
pos (Number, optional): Item position in a multi-step (default: 0).

Request body example for a text field:

{
  "caseId": 12345,
  "stepId": 101,
  "data": "Comment: Installation compliant",
  "pos": 0
}

Request body example for a date:

{
  "caseId": 12345,
  "stepId": 102,
  "data": "2024-01-15",
  "pos": 0
}

Request body example for a number:

{
  "caseId": 12345,
  "stepId": 103,
  "data": "42.5",
  "pos": 0
}

Authorized Item Types

The following item types are authorized:

TEXT_FIELD: Free text field
SELECT: Selection list
DATE: Date
EMAIL: Email address
NUMBER: Number
TIME: Time

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

PHOTOGRAPHY: Photo
VIDEO: Video
SIGNATURE: Signature

Responses

Successful response:

Status Code: 200 OK
Description: The item has been created successfully.

Successful response example:

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

Error response:

Status Code: 400 Bad Request
Description: The request is invalid (missing Step ID or maximum limit reached).
Status Code: 403 Forbidden
Description: Media type not authorized (photo/video/signature).
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
Dropdown list selections
Intervention dates
Email contact information
Numeric measurements
Intervention times

Adding an Item with File

Endpoint: `POST /items/:caseId`

Description

This API endpoint allows users to add an item to a case with file upload. This endpoint is particularly suited for photos, videos, signatures, and other item types requiring a file.

Request

URL: /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 item types)

createItemDto field (required):

Type: Stringified JSON
Description: JSON object containing item information

createItemDto structure:

companyId (Number, required): Company identifier.
stepId (Number, required): Step identifier (obtained via /frames).
data (String, required): Item data or file name for photos.
caseId (Number, optional): Case identifier (can be omitted as 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/certificall/api/items/12345" \
  -H "Authorization: Bearer your_jwt_token" \
  -F "file=@/path/to/photo.jpg" \
  -F 'createItemDto={
    "companyId": 1,
    "stepId": 101,
    "data": "facade_photo.jpg",
    "userDeviceManufacturer": "Apple",
    "userDeviceModel": "iPhone 13",
    "userDeviceName": "Jean 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 has been created and the file uploaded successfully.

Successful response example:

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

Error response:

Status Code: 400 Bad Request
Description: The request is invalid (missing or incorrect parameters).
Status Code: 403 Forbidden
Description: You do not have the necessary 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

The case must belong to your company.
Your company must be authorized to use this API, contact Certificall to find out if this is the case.

Supported Item Types

This endpoint supports all item types, including:

PHOTOGRAPHY: Photos with geolocation
VIDEO: Videos
SIGNATURE: Signatures
TEXT_FIELD, SELECT, DATE, EMAIL, NUMBER, 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

Security and Best Practices

First retrieve the list of available steps via the /frames endpoint to get valid stepId values.
Ensure that the data format matches the expected step type.
For photos, geolocation (geolocLatitude, geolocLongitude) is required.
Always include complete device information to ensure traceability.
Limit uploaded file sizes to avoid timeout errors.
Verify that the case is not yet closed before adding items.
Interactions with the Certificall API must always be performed via a secure connection (HTTPS).

By following these instructions, you will be able to securely add items to your cases via the Certificall API.

v2 contract — naming the depositing application​

Why​

Three required fields​

Endpoints​

Example​

Contract errors​

Migrating from v1​

Creating an Item​

Endpoint: POST /items/create​

Description​

Request​

Request Body (Payload)​

Authorized Item Types​

Responses​

Use Cases​

Adding an Item with File​

Endpoint: POST /items/:caseId​

Description​

Request​

Request Body (Multipart Form-Data)​

cURL Request Example​

Responses​

Required Permissions​

Supported Item Types​

Use Cases​

Security and Best Practices​

v2 contract — naming the depositing application

Why

Three required fields

Endpoints

Example

Contract errors

Migrating from v1

Creating an Item

Endpoint: `POST /items/create`

Description

Request

Request Body (Payload)

Authorized Item Types

Responses

Use Cases

Adding an Item with File

Endpoint: `POST /items/:caseId`

Description

Request

Request Body (Multipart Form-Data)

cURL Request Example

Responses

Required Permissions

Supported Item Types

Use Cases

Security and Best Practices