Skip to main content

Item Management

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

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.