Certilink (Magic Link) API User Guide

This guide will walk you through using the Certilink API to create, retrieve, and delete Magic Links. These links allow your users to access specific features without requiring prior authentication.

Prerequisites

Before getting started, make sure that:

• You have API access credentials. If not, contact your Certificall administrator.
• You have obtained a JWT authentication token required to interact with the API.

---

Authentication

Obtain an Access Token

To use the Certilink API, you must first obtain a JWT authentication token.

• Endpoint: POST /certificall/api/auth/token
• Description: Retrieves the Certificall identification token to add to your requests.

Request body:

{
  "username": "your_username",
  "password": "your_password"
}

Response example:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response codes:

• 200 OK: Access token returned successfully
• 401 Unauthorized: Incorrect credentials

Important: Store this token securely. It must be included in the Authorization header of all your API requests:

Authorization: Bearer <your_token>

---

Steps for Using the Certilink API

1. Retrieving Frames

To create a Certilink, you need to retrieve a frame that determines the case structure.

• Endpoint: GET /certificall/api/frames
• Description: Retrieves the list of frames available for your company.

Required headers:

Authorization: Bearer <your_token>

Response example:

[
  {
    "id": 1,
    "name": "Visual Inspection",
    "steps": [
      {
        "id": 10,
        "title": "Equipment photo",
        "description": "Take a photo of the equipment to inspect"
      },
      {
        "id": 11,
        "title": "General condition",
        "description": "Evaluate the general condition of the equipment"
      }
    ]
  },
  {
    "id": 2,
    "name": "Technical Inspection",
    "steps": [
      {
        "id": 20,
        "title": "Electrical verification",
        "description": "Check electrical installations"
      }
    ]
  }
]

For more details, see the Certificall documentation.

---

2. Creating a Certilink

Once you have the frame, you can create a Certilink. This allows your users to directly access a form or case without needing to authenticate.

• Endpoint: POST /certilink/create

Required headers:

Authorization: Bearer <your_token>

Required parameters:

• reportToken (String): A unique identifier for the case (provided by you).
• frameId (Number): The identifier of the frame you want to associate with the Magic Link.

Optional parameters:

• expirationDate (String): Magic Link expiration date (format: yyyy-mm-ddThh:mm:ss.sss+hhmm).
• maxUses (Number): Maximum number of authorized uses for this Magic Link.
• companyId (Number): Company ID (usually automatically inferred).
• context (Object): Magic Link context with visibleData and metadata.
  • visibleData (Object):
    • beneficiary (Object): Beneficiary information (lastName, firstName, address, city, postCode, email)
    • issuer (String): Issuer name
    • photoRef (String): Photo reference
    • reportRef (String): Report reference
    • instructions (String): Instructions for the user when completing the case
    • user (String): User name to display in the PDF (replaces the Kizeo user)
  • metadata (Object): Custom metadata (string key-value pairs)

Simple request example:

{
  "reportToken": "my-case-identifier",
  "frameId": 1
}

Complete request example:

{
  "reportToken": "my-case-identifier",
  "frameId": 1,
  "expirationDate": "2025-12-31T23:59:59.000+0100",
  "maxUses": 5,
  "context": {
    "visibleData": {
      "beneficiary": {
        "lastName": "Dupont",
        "firstName": "Jean",
        "address": "123 Rue de la Paix",
        "city": "Paris",
        "postCode": "75001",
        "email": "jean.dupont@example.com"
      },
      "issuer": "ACME Company",
      "photoRef": "photo-123-ref",
      "reportRef": "report-456-ref",
      "instructions": "Please note the apartment number",
      "user": "Jean Dupont"
    },
    "metadata": {
      "source": "web-portal",
      "version": "1.0",
      "department": "claims"
    }
  }
}

Response example:

The API will return the generated Magic Link URL:

{
  "url": "https://app.certificall.app?mt=09ca0baf-ce70-47a0-b84e-0b4acb0ecec3"
}

---

3. Bulk Certilink Creation

If you need to create multiple Certilinks in a single operation, you can use the bulk creation endpoint.

• Endpoint: POST /certilink/bulk-create
• Description: Create multiple magic links in a single request.

Required headers:

Authorization: Bearer <your_token>

Request body: Array of certilinks to create

[
  {
    "reportToken": "case-001",
    "frameId": 1,
    "maxUses": 3,
    "expirationDate": "2025-12-31T23:59:59.000+0100"
  },
  {
    "reportToken": "case-002",
    "frameId": 1,
    "maxUses": 5,
    "expirationDate": "2025-12-31T23:59:59.000+0100"
  },
  {
    "reportToken": "case-003",
    "frameId": 2
  }
]

Response example:

{
  "state": "Certilink bulk creation ended",
  "date": "2025-01-14T10:30:00.000+0100",
  "company": 123,
  "success": [
    {
      "reportToken": "case-001",
      "url": "https://app.certificall.app?mt=09ca0baf-ce70-47a0-b84e-0b4acb0ecec3"
    },
    {
      "reportToken": "case-002",
      "url": "https://app.certificall.app?mt=1a2b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6"
    },
    {
      "reportToken": "case-003",
      "url": "https://app.certificall.app?mt=a1b2c3d4-e5f6-7g8h-9i0j-1k2l3m4n5o6p"
    }
  ],
  "error": []
}

---

4. Retrieving Certilinks

You can retrieve the list of Certilinks created for your company using the API. This allows for an overview of active Magic Links and their tracking.

• Endpoint: POST /certilink/findCompanyMagicLinks

Required headers:

Authorization: Bearer <your_token>

Parameters:

• start (Number): Starting point of the list (useful for pagination).
• limit (Number): Number of Magic Links to return (maximum 100 per request).

Request example:

{
  "start": 0,
  "limit": 50
}

Response example:

[
  {
    "reportToken": "abc123",
    "url": "https://app.certificall.app?mt=09ca0baf-ce70-47a0-b84e-0b4acb0ecec3",
    "magicLinkToken": "09ca0baf-ce70-47a0-b84e-0b4acb0ecec3",
    "createdAt": "2024-01-01T12:00:00Z",
    "expirationDate": "2024-01-31T12:00:00Z",
    "enabled": true,
    "frame": {
      "id": 1,
      "name": "Visual Inspection"
    }
  }
]

---

5. Updating a Certilink

If you want to modify the expiration date or context of an existing Magic Link, you can do so by calling the following endpoint:

• Endpoint: PATCH /certilink/:magicLinkToken
• Parameter: The token of the Magic Link to update (in the URL).

Required headers:

Authorization: Bearer <your_token>

Request body:

• expirationDate (String, optional): New expiration date (format: yyyy-mm-ddThh:mm:ss.sss+hhmm).
• context (Object, optional): New context with visibleData and metadata.

Request example:

{
  "expirationDate": "2025-12-31T23:59:59.000+0100",
  "context": {
    "visibleData": {
      "beneficiary": {
        "lastName": "Martin",
        "firstName": "Sophie",
        "email": "sophie.martin@example.com"
      },
      "instructions": "Updated instructions"
    },
    "metadata": {
      "updated": "true",
      "version": "2.0"
    }
  }
}

Response example:

{
  "status": "Success",
  "message": "Magic link updated successfully"
}

---

6. Deleting a Certilink

If you want to disable or delete a Magic Link, you can do so by calling the following endpoint:

• Endpoint: DELETE /certilink/:magicLinkToken
• Parameter: The token of the Magic Link to delete (in the URL).

Required headers:

Authorization: Bearer <your_token>

Response example:

{
  "status": "Success",
  "message": "Magic link deleted successfully"
}

---

Security and Permissions

To ensure the security of your operations, each request to the Certilink API is subject to authentication and permission checks:

• You must be authenticated via a valid JWT token.
• Only users with the necessary rights can create or manage Certilinks.
• Magic Links must be associated with a valid frame and an authorized company.
• Store and manage the authentication token securely.
• All interactions with the Certificall API must be performed via HTTPS.

---

Endpoint Summary

Method	Endpoint	Description
POST	/certificall/api/auth/token	Obtain an authentication token
GET	/certificall/api/frames	Retrieve available frames
POST	/certilink/create	Create a certilink
POST	/certilink/bulk-create	Bulk create certilinks
POST	/certilink/findCompanyMagicLinks	Retrieve company certilinks
PATCH	/certilink/:magicLinkToken	Update a certilink
DELETE	/certilink/:magicLinkToken	Delete a certilink