Connect a system with the API

What it is for

The API lets another system work with one company's training records without anyone exporting a spreadsheet. The usual starts:

• your HR system adds new joiners, with their role, so the training plan assigns their courses;
• your intranet or dashboard shows who is trained and whose certificates are due;
• your payroll or employee file keeps the certificate numbers.

It is included for companies with a paid course purchase or an active plan.

Create a key

1. Open the company, then Integrations and API.
2. Choose Create key, name it after the system that will use it, and pick when it expires.
3. Tick only the permissions that system needs. Reading never changes anything; Create and update employees is the only one that writes.
4. Copy the key when it is shown. It is shown once: store it in that system's secret settings.

Make the first request

Every request goes to https://training.shogconsulting.com/api/v1 with the key as a Bearer token. The Quickstart tab shows the exact request for your company, ready to copy.

• Lists return up to 100 records a page; follow nextCursor for the next one.
• A request that adds or changes an employee carries an Idempotency-Key, so a retry never creates the same person twice.
• Each key may make 60 requests a minute, and the company 120 in all. A 429 answer says how long to wait.

Keep keys safe

• Keep keys on a server. Never put one in a web page, a spreadsheet or a screenshot.
• Rotate secret issues a new secret and keeps the old one working for 24 hours while you switch.
• Revoke stops a key at once.
• Usage shows the last 30 days of requests, so you can see what each key has been doing.