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

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

200

Successful response

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

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

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

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

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

200

Successful response

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

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

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

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

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

200

Successful response

PreviousCertificate Issuance NextOrganization

Last updated 4 months ago

Good evening

hashtag1. Get All Templates

hashtagEndpoint

hashtagDescription

hashtagHeaders

hashtagExample Request

hashtagExample Response

hashtag2. Create Template

hashtagEndpoint

hashtagDescription

hashtagHeaders

hashtagRequest Body

hashtagExample Request

hashtagExample Response

hashtag3. Edit Template

hashtagEndpoint

hashtagDescription

hashtagHeaders

hashtagExample Request

hashtagExample Response

hashtag4. Get Template by ID

hashtagEndpoint

hashtagDescription

hashtagHeaders

hashtagExample Response

hashtag5. Delete Template

hashtagEndpoint

hashtagDescription

hashtagHeaders

hashtagExample Response

hashtagGet Templates

hashtagCreate Template

hashtagGet Template

hashtagEdit Template

hashtagDelete Template

1. Get All Templates

Endpoint

Description

Headers

Example Request

Example Response

2. Create Template

Endpoint

Description

Headers

Request Body

Example Request

Example Response

3. Edit Template

Endpoint

Description

Headers

Example Request

Example Response

4. Get Template by ID

Endpoint

Description

Headers

Example Response

5. Delete Template

Endpoint

Description

Headers

Example Response

Get Templates

Create Template

Get Template

Edit Template

Delete Template