Skip to main content

Certificate Creation API User Guide

This guide details the steps necessary to use the Certificall API for creating and managing certified cases. Follow the instructions below to configure and operate your system efficiently.

Prerequisites​

Before getting started, make sure you meet the following conditions:

Account and API Access​

  • API Access: An API user access is required. Contact your Certificall administrator to activate this access if not already done.

Frame Configuration​

  • Company Frame: You must have a frame associated with your company. Configure it via your admin space provided by Certificall.

Authentication​

  • Obtaining the JWT Token: The token is essential for interacting with the API. Retrieve it via the /certificall/api/auth/token endpoint. For more details, see the Swagger documentation here or our complete guide.

API Usage Procedure​

1. Retrieving the Frame​

Objective: Identify the case structure to create by retrieving the frame information.

  1. Endpoint: /certificall/api/frames
    • See our Swagger interface for complete information.
  2. Expected Response: 
    class StepDto {
      id: number;
      title: string;
      description: string;
    }

    export class PublicFramesDto {
      id: number;
      name: string;
      steps: StepDto[];
    }
    • Important: Keep track of the step id values to use them in the following case creation steps.

2. Opening a Case​

Objective: Initialize a case that will structure the information collection according to the retrieved frame.

  1. Endpoint: POST /certificall/api/cases/create
    • Include the frame identifier to link the case to a sequence of steps and expected content.
  2. Important Parameters: 
    export class CreateCaseDto {
      frameId: number;
      options?: DeeplinkParams;
    }

Deeplink parameters are optional and allow performing various actions within Certificall, see: https://doc.certificall.app/docs/admin/deeplink

3. Creating Items​

Objective: Fill in the case steps with the required content, including certified photos.

  1. Endpoint: POST /api/items
    • Each content sent must be associated with a stepId and a caseId.
  2. For Photos: Geolocation details are mandatory.

The expected DTO for an item must be in the following format:

class CreateItemBaseDto {
  stepId: number;
  data: string; // for a photo this is the file name, for other content it is the content itself
  userDeviceManufacturer: string;
  userDeviceModel: string;
  userDeviceName: string;
  userDevicePlatform: string;
  userDeviceOs: string;
  userDeviceOsVersion: string;
  userDeviceCarrierIpAddress?: string;
  userDeviceWifiIpAddress?: string;
  geolocLatitude: string;
  geolocLongitude: string;
  geolocAccuracy?: string;
}

4. Closing the Case​

Objective: Finalize the case so it becomes viewable and archivable.

  • Endpoint: GET /certificall/api/cases/close/{caseId}
    • This makes the case non-modifiable and initiates the generation of the summary PDF.

5. Retrieving the Case​

Objective: Access the finalized case for viewing or integration into your systems.

  • Endpoint: GET /certificall/api/cases
    • Use caseId to access the case and its metadata.