Templates

The Templates API allows you to create, manage, and delete certificate templates. Templates define the visual layout of a certificate, including background images and dynamic fields such as recipient name, issue date, and QR codes.

This section covers all template-related endpoints:

---

1. Get All Templates

Endpoint

GET /api/templates

Description

Fetches all templates available to your account (or sub-account if provided).

Headers

• x-api-key (required) – Your API key from the Akowe dashboard.

• x-subaccount-email (optional) – Filters results to templates created by the specified sub-account.

Example Request

curl --location '{{baseurl}}/api/templates' \
--header &#x27;x-api-key: <your_api_key>&#x27;

Example Response

{
  "success": true,
  "message": "",
  "data": [
    {
      "id": "290e4c3b-1da4-4f7e-811d-30dde4f8858d",
      "name": "Demo Template",
      "imageUrl": "https://academicrecords.s3.eu-west-2.amazonaws.com/issuance/template.jpeg",
      "fields": [
        {
          "id": "997a7a31-a5eb-4b6a-bb01-f2b60c848171",
          "type": "name",
          "text": "Display Name",
          "fontSize": 16,
          "fontFamily": "Arial",
          "color": "#000000",
          "isBold": false,
          "isItalic": false,
          "alignment": "center",
          "x": 50,
          "y": 40
        }
      ],
      "dimensions": {
        "width": 2560,
        "height": 1920
      },
      "subAccountEmail": "[email protected]",
      "createdAt": "2025-09-24T18:23:43.621Z"
    }
  ]
}

---

2. Create Template

Endpoint

POST /api/templates

Description

Creates a new certificate template with a background image, dimensions, and defined fields.

Headers

• x-api-key (required)

• x-subaccount-email (optional but recommended) – Links the template to a specific sub-account.

• Content-Type: application/json

Request Body

Field	Type	Required	Description
name	string	✅ Yes	The template name.
imageUrl	string	✅ Yes	Base64 string or image URL for the background.
dimensions	object	✅ Yes	Width and height of the template.
fields	array	✅ Yes	List of field definitions (e.g., name, date, QR).

Example Request

curl --location '{{baseurl}}/api/templates' \
--header &#x27;x-api-key: <your_api_key>&#x27; \
--header 'x-subaccount-email: [email protected]' \
--header 'Content-Type: application/json' \
--data '{
  "name": "Demo",
  "imageUrl": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQU//Z",
  "dimensions": {
    "width": 2560,
    "height": 1920
  },
  "fields": [
    {
      "type": "name",
      "text": "Display Name",
      "x": 50,
      "y": 40,
      "fontSize": 16,
      "fontFamily": "Arial",
      "color": "#000000",
      "isBold": false,
      "isItalic": false,
      "alignment": "center"
    }
  ]
}'

Example Response

{
  "success": true,
  "message": "Template created successfully",
  "data": {
    "id": "290e4c3b-1da4-4f7e-811d-30dde4f8858d",
    "name": "Demo",
    "imageUrl": "https://academicrecords.s3.eu-west-2.amazonaws.com/issuance/template.jpeg",
    "dimensions": {
      "width": 2560,
      "height": 1920
    },
    "fields": [
      {
        "id": "8fa5eacf-34e3-4115-82c8-356edc9ccd6f",
        "type": "name",
        "text": "Display Name",
        "x": 50,
        "y": 40
      }
    ]
  }
}

---

3. Edit Template

Endpoint

PUT /api/templates/{templateId}

Description

Updates an existing template’s details and fields.

Headers

• x-api-key (required)

• Content-Type: application/json

Example Request

curl --location --request PUT '{{baseurl}}/api/templates/{templateId}' \
--header &#x27;x-api-key: <your_api_key>&#x27; \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "Demo Edited",
  "imageUrl": "https://academicrecords.s3.eu-west-2.amazonaws.com/issuance/template.jpeg",
  "fields": [...]
}'

Example Response

{
  "success": true,
  "message": "Template updated successfully"
}

---

4. Get Template by ID

Endpoint

GET /api/templates/{templateId}

Description

Fetches the details of a specific template.

Headers

• x-api-key (required)

Example Response

{
  "success": true,
  "data": {
    "id": "290e4c3b-1da4-4f7e-811d-30dde4f8858d",
    "name": "Demo Edited",
    "imageUrl": "https://academicrecords.s3.eu-west-2.amazonaws.com/issuance/template.jpeg",
    "fields": [...],
    "dimensions": {
      "width": 2560,
      "height": 1920
    }
  }
}

---

5. Delete Template

Endpoint

DELETE /api/templates/{templateId}

Description

Deletes a specific template permanently.

Headers

• x-api-key (required)

Example Response

{
  "success": true,
  "message": "Template deleted successfully"
}

Get Templates

get

Header parameters

x-api-keystringOptionalExample: live-4ddc3c34-c47d-423a-a49b-0dbc3dac75a1-0-2d45cc19-2241-42ed-8e97-0eb8486c93c7

x-subaccount-emailstringOptionalExample: [email protected]

Responses

200

Successful response

application/json

get

/templates

HTTPcURLJavaScriptPython

GET /templates HTTP/1.1
Host: {{baseurl}}
Accept: */*

200

Successful response

No content

Create Template

post

Header parameters

x-api-keystringOptionalExample: live-4ddc3c34-c47d-423a-a49b-0dbc3dac75a1-0-2d45cc19-2241-42ed-8e97-0eb8486c93c7

x-subaccount-emailstringOptionalExample: [email protected]

Body

application/json

objectOptionalExample: {"name":"Demo","imageUrl":"data:image/jpeg;base64","dimensions":{"width":2560,"height":1920},"fields":[{"type":"name","text":"Display Name","x":50,"y":40,"fontSize":16,"fontFamily":"Arial","color":"#000000","isBold":false,"isItalic":false,"alignment":"center"},{"type":"date","text":"Issue Date","x":50,"y":50,"fontSize":16,"fontFamily":"Arial","color":"#000000","isBold":false,"isItalic":false,"alignment":"center"},{"type":"qr","text":"QR","x":50,"y":70,"color":"#000000","alignment":"center","fontSize":50}]}

Responses

200

Successful response

application/json

post

/templates

HTTPcURLJavaScriptPython

POST /templates HTTP/1.1
Host: {{baseurl}}
Content-Type: application/json
Accept: */*
Content-Length: 511

{
  "name": "Demo",
  "imageUrl": "data:image/jpeg;base64",
  "dimensions": {
    "width": 2560,
    "height": 1920
  },
  "fields": [
    {
      "type": "name",
      "text": "Display Name",
      "x": 50,
      "y": 40,
      "fontSize": 16,
      "fontFamily": "Arial",
      "color": "#000000",
      "isBold": false,
      "isItalic": false,
      "alignment": "center"
    },
    {
      "type": "date",
      "text": "Issue Date",
      "x": 50,
      "y": 50,
      "fontSize": 16,
      "fontFamily": "Arial",
      "color": "#000000",
      "isBold": false,
      "isItalic": false,
      "alignment": "center"
    },
    {
      "type": "qr",
      "text": "QR",
      "x": 50,
      "y": 70,
      "color": "#000000",
      "alignment": "center",
      "fontSize": 50
    }
  ]
}

200

Successful response

No content

Get Template

get

Header parameters

x-api-keystringOptionalExample: live-4ddc3c34-c47d-423a-a49b-0dbc3dac75a1-0-2d45cc19-2241-42ed-8e97-0eb8486c93c7

x-subaccount-emailstringOptionalExample: [email protected]

Responses

200

Successful response

application/json

get

/templates/290e4c3b-1da4-4f7e-811d-30dde4f8858d

HTTPcURLJavaScriptPython

GET /templates/290e4c3b-1da4-4f7e-811d-30dde4f8858d HTTP/1.1
Host: {{baseurl}}
Accept: */*

200

Successful response

No content

Edit Template

put

Header parameters

x-api-keystringOptionalExample: live-4ddc3c34-c47d-423a-a49b-0dbc3dac75a1-0-2d45cc19-2241-42ed-8e97-0eb8486c93c7

x-subaccount-emailstringOptionalExample: [email protected]

Body

application/json

objectOptionalExample: {"id":"290e4c3b-1da4-4f7e-811d-30dde4f8858d","name":"Demo Edited","imageUrl":"https://academicrecords.s3.eu-west-2.amazonaws.com/issuance/7d25bf2d-ad17-4f30-abfe-e96117803e84.jpeg","fields":[{"id":"8fa5eacf-34e3-4115-82c8-356edc9ccd6f","type":"name","text":"Display Name","fontSize":16,"fontFamily":"Arial","color":"#000000","isBold":false,"isItalic":false,"alignment":"center","x":50,"y":40,"templateId":"290e4c3b-1da4-4f7e-811d-30dde4f8858d"},{"id":"1566bf7b-756f-4493-943b-69c077dc6f6a","type":"date","text":"Issue Date","fontSize":16,"fontFamily":"Arial","color":"#000000","isBold":false,"isItalic":false,"alignment":"center","x":50,"y":50,"templateId":"290e4c3b-1da4-4f7e-811d-30dde4f8858d"},{"id":"91475635-8561-4989-8de3-dd9bf5b81ffd","type":"qr","text":"QR","fontSize":50,"fontFamily":"Arial","color":"#000000","isBold":false,"isItalic":false,"alignment":"center","x":50,"y":70,"templateId":"290e4c3b-1da4-4f7e-811d-30dde4f8858d"}],"subAccountEmail":"[email protected]","dimensions":{"width":2560,"height":1920},"createdAt":"2025-09-24T18:23:43.621Z"}

Responses

200

Successful response

application/json

put

/templates/290e4c3b-1da4-4f7e-811d-30dde4f8858d

HTTPcURLJavaScriptPython

PUT /templates/290e4c3b-1da4-4f7e-811d-30dde4f8858d HTTP/1.1
Host: {{baseurl}}
Content-Type: application/json
Accept: */*
Content-Length: 1059

{
  "id": "290e4c3b-1da4-4f7e-811d-30dde4f8858d",
  "name": "Demo Edited",
  "imageUrl": "https://academicrecords.s3.eu-west-2.amazonaws.com/issuance/7d25bf2d-ad17-4f30-abfe-e96117803e84.jpeg",
  "fields": [
    {
      "id": "8fa5eacf-34e3-4115-82c8-356edc9ccd6f",
      "type": "name",
      "text": "Display Name",
      "fontSize": 16,
      "fontFamily": "Arial",
      "color": "#000000",
      "isBold": false,
      "isItalic": false,
      "alignment": "center",
      "x": 50,
      "y": 40,
      "templateId": "290e4c3b-1da4-4f7e-811d-30dde4f8858d"
    },
    {
      "id": "1566bf7b-756f-4493-943b-69c077dc6f6a",
      "type": "date",
      "text": "Issue Date",
      "fontSize": 16,
      "fontFamily": "Arial",
      "color": "#000000",
      "isBold": false,
      "isItalic": false,
      "alignment": "center",
      "x": 50,
      "y": 50,
      "templateId": "290e4c3b-1da4-4f7e-811d-30dde4f8858d"
    },
    {
      "id": "91475635-8561-4989-8de3-dd9bf5b81ffd",
      "type": "qr",
      "text": "QR",
      "fontSize": 50,
      "fontFamily": "Arial",
      "color": "#000000",
      "isBold": false,
      "isItalic": false,
      "alignment": "center",
      "x": 50,
      "y": 70,
      "templateId": "290e4c3b-1da4-4f7e-811d-30dde4f8858d"
    }
  ],
  "subAccountEmail": "[email protected]",
  "dimensions": {
    "width": 2560,
    "height": 1920
  },
  "createdAt": "2025-09-24T18:23:43.621Z"
}

200

Successful response

No content

Delete Template

delete

Header parameters

x-api-keystringOptionalExample: live-4ddc3c34-c47d-423a-a49b-0dbc3dac75a1-0-2d45cc19-2241-42ed-8e97-0eb8486c93c7

x-subaccount-emailstringOptionalExample: [email protected]

Responses

200

Successful response

application/json

delete

/templates/290e4c3b-1da4-4f7e-811d-30dde4f8858d

HTTPcURLJavaScriptPython

DELETE /templates/290e4c3b-1da4-4f7e-811d-30dde4f8858d HTTP/1.1
Host: {{baseurl}}
Accept: */*

200

Successful response

No content