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.
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.
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.
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" } ] }'
| Field | Meaning |
|---|---|
| certificate | ID of the template |
| recipients | List of people, up to 100 per request |
| The person's email address, required | |
| full_name | The person's name, required |
| send_emails | true sends the emails right away |
| add_duplicates | true 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.
| Event | When it fires |
|---|---|
| Certificate/Badge Generated | A credential was generated |
| Credential Email Sent | The email with the credential was sent |
| Recipient Access Revoked | A recipient's access was revoked |
| Training Completed | A 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.
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.