Connect your student records system

How your records map to Certrust

1. Prepare Certrust

1. Create an achievement for each award you will issue, and choose its certificate design.
2. Find each achievement's numeric ID: open it on the Issue page, and the number after ?achievement= in the address is the ID.
3. Create an API key under Manage → API keys with the Read and Issue permissions. Add Revoke only if your system will withdraw awards.
4. Store the key in your server's secret settings, never in code or in the export files.

The API guide explains keys and permissions in full.

2. Choose how to send awards

Most institutions start with a nightly catch-up, because it needs only an export your records system can already produce. It is covered in the next step.

3. A working example: issue from an export

This example script reads a CSV export, issues through an issuance job, waits for it to finish and writes a results file. It needs Python 3.8 or later and nothing else.

Download certrust-sync-example.py

The export

One row per student who has earned the award. name and email are required. student_id is never sent to Certrust; it is copied into the results so you can match them to your records. A column named after one of your Certrust custom attributes (here training_date) is printed on the certificate. Any other column is ignored and stays on your server.

student_id,name,email,expiry_date,training_date
S1042,Ada Lovelace,ada@example.edu,,2026-10-01
S1043,Alan Turing,alan@example.edu,,2026-10-01

Run it

export CERTRUST_API_KEY=crt_...
python3 certrust-sync-example.py --achievement 12 --input graduates.csv --output results.csv

Example University: 2 students to process
  0/2 processed
Done: 2 issued, 0 already issued, 0 failed. Results in results.csv

The results

One row per student, in the same order, with the outcome (issued, already_issued or failed), the credential ID and the certificate link. Load these back into your records system. The command exits with an error status if any student failed, so a scheduler can alert you.

student_id,name,email,outcome,credential_id,certificate_url,error
S1042,Ada Lovelace,ada@example.edu,issued,urn:uuid:351dc622-…,https://certrust.app/credentials/urn%3Auuid%3A351dc622-…,
S1043,Alan Turing,alan@example.edu,already_issued,urn:uuid:4d7b1747-…,https://certrust.app/credentials/urn%3Auuid%3A4d7b1747-…,

4. Issue as results are confirmed

If your system can call an API when a result is confirmed, issue one credential at a time instead. Use your own record ID for the award as the Idempotency-Key, so a retry after a timeout never issues twice:

curl -X POST https://api.certrust.app/api/credentials/issue \
  -H "Authorization: Bearer $CERTRUST_API_KEY" \
  -H "Idempotency-Key: award-2026-S1042-BSC-CS" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "achievementId": 12,
      "recipient": { "name": "Ada Lovelace", "email": "ada@example.edu" }
    }
  }'

The response contains credential.id (use it to revoke) and credential.credentialId (the public ID in the certificate link).

5. Run it on a schedule

On a Linux server, a cron entry is enough. On Windows, use Task Scheduler with the same command.

# Every night at 01:30: export, then issue
30 1 * * *  /opt/sis/export-awards.sh > /var/certrust/awards.csv && \
            python3 /opt/certrust/certrust-sync-example.py --achievement 12 \
              --input /var/certrust/awards.csv --output /var/certrust/results.csv

• Keep the API key in the environment of the scheduled job, readable only by the account that runs it.
• Have the scheduler alert someone when the command fails, and review the failed rows in the results.
• Delete export and results files once they have been loaded back, as you would any file with student data.

Before you go live

• Test with a small group first. Issue one award to a few staff email addresses and check the certificate, the email and the verification page.
• Check student emails. The certificate goes to the address you send. Prefer an address the student keeps after they leave.
• Agree who owns the key. A key works with the permissions of the staff member who created it and stops if they leave your Certrust organisation. Create it from a shared or role account.
• Plan for withdrawals. Decide who may revoke an award and give only that system the Revoke permission.
• Know the limits. 120 requests a minute per key, 2,000 students per job and 3 jobs at once. A job counts as one request.

Full reference for every request, error and limit: the API guide.