Skip to main content

How to enable and use dynamic fields in the Additional Information of your POK credential

Dynamic fields let you personalize the Additional Information of a POK Proof of Knowledge credential for each recipient, instead of using the same value for everyone. You enable them in the design editor, then fill them in at emission time (manual, bulk, or via API). This guide covers both parts: configuring dynamic fields in a design and issuing credentials with them through the API.

Part 1: Configure dynamic fields in a design​

1. Open the design editor​

  1. Log in to your POK dashboard through the region selector, using your username and password.
  2. In the left menu, select Designs.
  3. Click New design to start building a template from scratch.

From here you can edit both the visual design and the structural information that make up your credential.

2. Open the Additional Information section​

  1. Inside the template editor, select Additional Information in the left menu. This section holds the extra content that accompanies each credential.
  2. In the General Information section, click Add to configure the fields that describe the credential you will issue.

3. Enable advanced options (optional)​

Inside the General Information dialog you will find an extra option:

  • Turn on the "Improve the quality of my OpenBadge credential" toggle to unlock more optional fields. These fields add detail, transparency, and context for the recipient, and raise the quality of your credential within the OpenBadge standard.

This configuration is not mandatory, but it is highly recommended if you want to deliver more complete credentials aligned with international best practices.

4. Activate the dynamic fields​

  1. Inside the Details accordion, check the Enable dynamic fields checkbox.

  2. Once enabled, each general information field displays a new checkbox: Enable dynamic field.

This lets you decide which information stays fixed for all recipients and which is personalized case by case.

What does enabling a dynamic field mean?​

  • If you check the option, the field becomes dynamic: its value is filled in with personalized information for each recipient at emission time (manual, bulk, or via API).
  • If you leave it unchecked, the value is the same for all recipients and is taken directly from the design.

Dynamic field identifier​

When you activate a dynamic field, a name appears in brackets, for example: [final grade].

Keep this identifier at hand. You will use it during emission to assign a different value to each recipient.

5. Save the design​

Once you have configured the Additional Information and defined the dynamic fields you need:

  • Click Save Design to keep your changes and make the template available for emissions.

Part 2: Issue credentials with dynamic fields via API​

API emission lets you issue credentials automatically by integrating your external systems with POK.

1. Get your API Key​

  1. In POK, open the top-right menu and go to Integrations.

  2. Click New integration.

  3. Give it a descriptive name (for example, "Internal System Integration").

  4. Select API Key Integration.

  5. Copy your API Key and store it in a secure place. It is shown only once.

  6. Turn on the "I have already copied the API Key..." toggle and confirm to close the dialog.

2. Get the ID of the template with dynamic fields​

Before issuing credentials with dynamic fields, identify the ID of the template that contains them. Call the list templates endpoint to get the full list of templates available in your organization. For request details, check the List templates endpoint documentation.

The response lists every template with its name and ID. Find the template you configured with dynamic additional information and copy its ID; you will use it in the next steps.

Example response

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

3. Retrieve the template details​

With the template ID in hand, query the template details to extract the dynamic fields defined in it. Replace the id parameter with the template ID you copied in the previous step. For request details, check the Get template endpoint documentation.

The response includes the full structure of the template, where you can identify:

  • The customParameters object, which contains the dynamic fields you created.
  • The ID and label of each of those fields.

You will need these IDs to build the request body in the next step, since each dynamic field must be sent inside the customParameters object.

Example response

{
    "id": "Qmx1ZQ==",
    "name": "Certified Frontend OB v2",
    "version": "2",
    "customParameters": [
        {
            "id": "achievement_description",
            "label": "achievement_description"
        },
        {
            "id": "37c53975-c57c-4f3b-a894-238ed118f7b7",
            "label": "final grade"
        }
    ]
}

4. Issue a credential using dynamic fields​

To issue the credential with your dynamic fields, use the emit credential endpoint. For request details, check the Emit credential endpoint documentation.

Inside the request body:

  • In the customization template object, include the customParameters object. Inside it, add each of the IDs identified in step 3 together with the value you want to assign to each dynamic field.
  • In the id field of the template object, enter the template ID obtained in step 2.

With these steps, your credential is issued with all the dynamic values you defined.

Example body

{
    "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": "01J4MM0KYVR71D7VSCAN09TYW4",
            "id": "01J4MM0KYTAW0MJDJVGCG7XDBE"
        },
        "page": "48a975cd-be42-48b4-967a-84c1c09b730e",
        "template": {
            "customParameters": {
                "achievement_description": "This certificate attests that John Doe has successfully completed the program of study and has met all academic requirements established by The World University to obtain the Frontend Developer degree.",
                "37c53975-c57c-4f3b-a894-238ed118f7b7": "+A"
            },
            "id": "Qmx1ZQ=="
        }
    }
}

Additional customizations (optional)​

Besides dynamic fields, you can add other elements to the emission:

These options further enrich the context the student receives.

Successful response​

When the credential is issued correctly, the response includes:

  • The credential ID.
  • The state of the emission.
  • The viewUrl, where the credential can be viewed once the recipient accepts it.

Example response

{
    "id": "cf0a0360-85f7-494f-86bd-dba8c1b86893",
    "state": "waitingForApproval"
}

With these steps, dynamic fields are fully configured, letting you create more personalized and flexible experiences for each recipient within the POK ecosystem.