LEARNTEC 2027Meet Virtualbadge.io in Karlsruhe in February 2027.Book a meeting at our stand
How-to guide

REST API and webhooks: trigger issuing from your own system

Your examination system or course management tool adds recipients itself and triggers the sending. You test in the sandbox and receive events by webhook. This guide shows every step in Virtualbadge.io.

45 minFor issuersUpdated November 2026
At a glanceGuide
in 6 steps
Time
about 45 minutes
For
Issuers
Where
Open the template Recipients Add recipients Add via API
Plan
Professional, otherwise as an add-on
What you need
  • A developer on your team
  • Access to “Settings” and “Integrations”
  • An active template

No account yet? Start a free trial. It runs for seven days.

The REST API is the direct route from your own system. One request adds up to 100 people to a template and, if you wish, sends the emails right away. The full documentation is at docs.virtualbadge.io.

Step 1: Generate an API token

Open “Settings” and “Integrations”. Under “API Access”, “Generate token” creates a token. Below are the URL for requests and the secret access token.

Treat the token like a password and do not store it in frontend code.

API Access in the integrations.

Step 2: Open the example for your template

In the template, open “Recipients”, click “Add recipients” and choose “Add via API”. The “API Integration” dialog shows a ready-made example for exactly this template in three steps, as cURL, JavaScript or Python.

“Add via API” in the menu of the list of recipients.

Step 3: Add recipients with a request

Send a POST request to /v2/public/recipient/. The token goes into the “Authorization” header as a bearer token. In the body you name the template in the certificate field and the people in the recipients field. email and full_name are required per person.

send_emails decides whether the emails are sent right away, add_duplicates whether duplicate email addresses are allowed. One request takes up to 100 people.

“API Integration” dialog with sample request and response.
Example
curl -X POST "https://api.virtualbadge.io/v2/public/recipient/" \  -H "Authorization: Bearer YOUR_API_TOKEN" \  -H "Content-Type: application/json" \  -d '{    "certificate": "cert_8Kq2mXv4TzR1pLw9",    "send_emails": true,    "add_duplicates": true,    "recipients": [      { "email": "lena.hoffmann@example.org", "full_name": "Lena Hoffmann" }    ]  }'
Fields in the request
FieldMeaning
certificateID of the template
recipientsList of people, up to 100 per request
emailThe person's email address, required
full_nameThe person's name, required
send_emailstrue sends the emails right away
add_duplicatestrue allows duplicate email addresses

Step 4: Handle the response

On success the API responds with status 201 and the created recipient objects. Each person receives a unique id and an access_page_url, the address of their recipient view. Store both values in your system.

Step 5: Receive events by webhook

Webhooks tell your system when something has happened, for example when a credential was generated or a recipient's access was revoked. The table lists the events. The API documentation describes setup and fields.

Webhook events
EventWhen it fires
Certificate/Badge GeneratedA credential was generated
Credential Email SentThe email with the credential was sent
Recipient Access RevokedA recipient's access was revoked
Training CompletedA training was completed, manually or automatically

Step 6: Test in the sandbox, then switch

Test in a sandbox organization first. Credentials from there are marked as tests. When everything is right, move the template with “Migrate to Productive Organisation” in the overview. This creates a copy there with basic details, design and recipient experience. Then check the token and the template ID in your system, because the copy is a template of its own.

“Manage Template” in the overview: “Migrate” creates a copy of the template in the productive organization.

Follow this guide with your own data.

Check the result

  • A test request returns status 201.
  • The person appears in the template's list of recipients.
  • Your system has stored id and access_page_url.

More on this: API documentationIntegrations

Frequently asked questions

How many people fit into one request?

Up to 100 people.

Where do I find the template's ID?

In the “API Integration” dialog it is already filled into the example. It is also shown at the bottom of the template's overview.

Where is the full documentation?

At docs.virtualbadge.io. “Go to docs” in the dialog takes you straight there.

Does this work without development of our own?

Yes, with Zapier. You do not need an API token there. For Moodle there is a plugin of its own.

Where to go next

Try it with your own certificate

Upload your current certificate design, issue a test credential and follow the guides with real data. The trial runs for seven days.

More than 1,000 organizations issue with Virtualbadge.io, including telc, Vodafone, Dell, IDP, EBS Universität and Mannheim Business School.