Skip to main content

How to issue a credential via API and filter by tags

To issue a credential through the POK Proof of Knowledge API, you create a template, generate an API key, and call the issuance endpoint with your template ID. If you add tags to the request, you can later filter your issued credentials with the tags query parameter. This guide walks you through the full flow.

Part 1: Initial setup​

Create a template​

You need a template before you can issue any credential.

  1. Log in to your POK dashboard through the region selector.
  2. Open the Designs section.
  3. Create a new template.

For detailed instructions, see how to design a certificate.

Create an API key​

  1. In POK, open the top right menu and go to Integrations.
  2. Click New integration.
  3. Enter a descriptive name (for example, "Internal System Integration").
  4. Select API Key Integration.
  5. Copy your API key and store it in a secure location. It is only shown once.
  6. Check the toggle "I've already copied the API Key…" and confirm to close the dialog.

Part 2: Issue a credential via the API​

Step 1: Get the template ID​

First, identify the ID of the template you created. Call the list templates endpoint to retrieve every template available in your organization. For the full request details, see the API reference.

The response includes each template with its name and ID. Find the template you configured earlier and copy its ID. You will use it in the next step.

Response example:

{
    "pagination": {
        "next": "string"
    },
    "data": [
        {
            "id": "Qmx1ZQ==",
            "name": "Certified Frontend OB v2"
        }
    ]
}

Optional data​

Step 2: Issue the credential​

Call the issue credential endpoint. For the full request body details, see the API reference.

Two fields matter most in the request body:

  • id inside the template object: enter the template ID you obtained in Step 1.
  • tags inside the credential object: tags are arbitrary values associated with the credential that let you filter your issuances later.

Tags example:

"tags": ["StudentId:65989", "#SALE", "Q1"]

Once you complete the request body, you can issue credentials linked to tags.

Body example:

{
    "credential": {
        "tags": ["StudentId:65989", "#SALE", "Q1"],
        "skipAcceptance": false,
        "emissionType": "pok",
        "dateFormat": "dd/MM/yyyy",
        "emissionDate": "2022-10-09T00:00:00.000Z",
        "title": "Frontend developer",
        "emitter": "The World University"
    },
    "receiver": {
        "languageTag": "es-AR",
        "identification": "12345678",
        "email": "john.doe@pok.tech",
        "lastName": "Doe",
        "firstName": "John"
    },
    "customization": {
        "learningPath": {
            "stepId": "",
            "id": ""
        },
        "page": "",
        "template": {
            "customParameters": {},
            "id": "Qmx1ZQ=="
        }
    }
}

Part 3: List and filter issued credentials​

List issued credentials​

After issuing, retrieve the full list of issued credentials with the list credentials endpoint. For the full request details, see the API reference.

Filter by tags​

To filter the results, use the tags query parameter. The value must exactly match the tag you used at issuance time.

Request example:

GET /credential?tags=Q1

The API returns only the credentials that contain that tag.

What you can do now​

With these steps you can:

  • Issue digital credentials via the API.
  • Associate them with custom identifiers (tags).
  • Filter your issuances easily.
  • Manage large volumes of credentials with advanced segmentation.