Skip to main content

Issuing Credentials via the Velocert API

This guide explains how to issue credentials programmatically using the Velocert API.

You’ll learn how to reference an existing credential template, retrieve the required input fields, validate your credential payload, and issue credentials to recipients via API calls.

1. API Token Creation

To use the Velocert API in this guide, you need an API token. This token allows your application to authenticate requests and ensures that all API calls are securely authorized.

If you don’t already have a token, create one in the Velocert platform under Settings → API Tokens. Once generated, copy and store it securely — it’s shown only once and cannot be retrieved later.

For more details on creating and managing API tokens, see the Create an API Token guide.

2. Credential Template Creation

Before you can issue credentials through the API, you need a credential template. If you already have a suitable template, you can skip this step.

To create a new template in the Velocert platform:

  • Navigate to Issue Credentials.
  • Under Default templates, choose a template that fits your needs.
  • Click Use template to open the customization flow.
  • Adjust the template as needed — for example, update the credential appearance or modify its fields.
  • Give your template a descriptive name.
You don’t need to enter recipient information at this stage. Once you click Continue, the template is saved automatically and can be found under Issue Credentials → My templates.

Once your template is saved, it’s ready to be referenced for API-based credential issuance.

3. Retrieve Your Credential Type

Next, you’ll need to identify the credential type associated with your template. This type is required for all subsequent API calls.

To do this, use the List your organization’s credential types API endpoint. Make sure to include your API token in the Authorization header so your request is authenticated.

GEThttps://app.velocert.com/api/v1/plugin/credential-types

CURL

1curl -X GET "https://app.velocert.com/api/v1/plugin/credential-types?pageSize=20&pageToken=0" \
2-H "Accept: application/json" \
3-H "Content-Type: application/json"
See the List Credential Types API for full details.

REQUEST

Authentication

Parameters

From the API response:

  • Locate the credential type that matches your template by checking the displayName.
  • Extract the numeric ID from the name field. For example, if the field reads credentialTypes/123, the credential type ID is 123.

This credentialType ID is required for the next step, where you’ll fetch the input fields needed to issue a credential.

If the credentialTypes array is empty, it means your organization doesn’t yet have any credential templates available.

4. Understand Credential Input Fields

To issue a credential successfully, you need a clear picture of which fields are required. This ensures your API requests are complete and your credentials are valid.

Use the Learn about credential input fields API, including the credentialType ID obtained in the previous step:

GEThttps://app.velocert.com/api/v1/plugin/credential-types/:credentialType/input-fields

CURL

1curl -X GET "https://app.velocert.com/api/v1/plugin/credential-types/:credentialType/input-fields" \
2-H "Accept: application/json" \
3-H "Content-Type: application/json"
See the Learn about the credential input fields API for full details.

REQUEST

Authentication

Path Parameters

The response provides an example payload showing all the fields for this credential. All fields returned here should be included when you make your credential issuance request.

Consider this response your blueprint — it ensures that no required information is overlooked when issuing a credential via the API.

5. Validate Your Credential Payload (Optional)

With your payload structure prepared and populated with actual credential values, it’s a good idea to validate your data before issuing credentials. While this step is optional, it’s highly recommended—especially when issuing credentials at scale—as it helps catch missing fields or formatting issues early. You can perform this check using the Validate your input API.

The credential payload must be wrapped inside the credential field of the request body.
POSThttps://app.velocert.com/api/v1/plugin/credential-types/:credentialType/actions/validate

CURL

1curl -X POST "https://app.velocert.com/api/v1/plugin/credential-types/:credentialType/actions/validate" \
2-H "Accept: application/json" \
3-H "Content-Type: application/json" \
4-d '{
5  "credential": {}
6}'
See the Validate your input API for full details.

REQUEST

Authentication

Path Parameters

Request Body

The API response will provide:

  • valid - true if the payload meets all requirements and is ready for issuance.
  • errors – Lists any validation errors; null if no issues are found.

Keep in mind: this call does not issue a credential. It exists to guide your payload construction. Once valid returns true, your payload is ready to use in the final credential issuance request.

6. Issue the Credential

With your payload ready it's time to issue the credential using the Create new credentials API endpoint.

You’ll use the credentialType ID from earlier along with the payload you’ve prepared. With this information, you can issue credentials to one or more recipients in a single request. For each recipient, Velocert takes care of creating, signing, storing, and delivering the credential via email, making the entire process seamless and automatic.

Important: Make sure the recipient’s email is correct in your request, as this is where the credential will be sent.
POSThttps://app.velocert.com/api/v1/plugin/credential-types/:credentialType/credentials

CURL

1curl -X POST "https://app.velocert.com/api/v1/plugin/credential-types/:credentialType/credentials" \
2-H "Accept: application/json" \
3-H "Content-Type: application/json" \
4-d '{
5  "recipients": [
6    {
7      "email": "user@example.com",
8      "credential": {}
9    }
10  ]
11}'
See the Create new credentials API for full details.

REQUEST

Authentication

Path Parameters

Request Body

Credential issuance is processed asynchronously. Once the request is successfully submitted, recipients will receive their credential via email shortly afterward. Each credential can then be viewed and verified directly by the recipient, completing the issuance process smoothly.