Talk to us
HomeFeaturesWho it's forMobileSecurityPlansTalk to us

API and webhooks

Your own systems read employees, attendance, leave and payroll results with API keys that have scopes. They are told at once when an employee joins, changes or leaves, a leave or payslip is approved, or a resignation is sent.
PLANSScale only
Compare plansHow it works

The problem it solves

  • Your ERP, access control or BI tool needs the employee list, and someone exports a spreadsheet every week.
  • When a person leaves, other systems keep their access because nobody told them.
  • A shared admin password is given to an integration, and it can see and change everything.
  • When a call to another system fails, nobody knows, and the data drifts apart.

How it works

  1. The HR administrator opens Integrations and makes a new API key. Give it a name (what will use it) and the user it acts as. Choose what it may read: employees, attendance, leave, payroll results.
  2. Make the Key shows the key once. Your IT team copies it into the other system.
  3. The other system calls https://<your workspace>/hrms/api/v1/ with the key in the Authorization: Bearer header and reads what its scopes allow.
  4. For events, add a webhook: a name, the event and the address to call. Right after the save, that address gets the record as JSON, signed with the webhook's secret.
  5. Failed calls are tried again every 15 minutes, up to five times. The Calls tab lists each call and the answer it got.

Everything it does

API keys

  • Acts As: the user whose access the key has; calls see only what that user may see
  • Scopes: Employees (on by default), Attendance, Leave, Payroll Results
  • The key is shown once; only its first characters are kept, as Key Starts With
  • API Keys lists each key with when it was last used and how many calls it made
  • Revoke stops a key at once; a lost key is revoked and a new one made
  • One entity per key

What the API reads

  • ping: checks the key and lists its scopes
  • employees and employees/<id>: employee records; updated_since gives only those changed since a time
  • attendance: the record per person and day (status, paid days, in and out, worked, late and overtime minutes), by date range and employee
  • leaves: leave requests in a period, by state and employee
  • payslips: approved and paid payslips (gross, deductions, net, employer cost), with the lines when asked
  • Pages of 100 records by default, at most 500 a call
  • Read only: there are no calls that add or change records yet

Webhooks

  • Six events: an employee is added, changes or leaves (relieved); a leave request is approved; a payslip is approved; a resignation or separation is sent
  • The record is sent as JSON right after the save
  • Headers: X-SmartMy-Event with the event, and X-SmartMy-Signature with the HMAC-SHA256 of the body using the webhook's secret
  • The secret is under Credentials, for the HR Manager only
  • States of each call: Waiting, Delivered, Failed; the answer code is kept
  • Failed calls are tried every 15 minutes, five times in all; each call waits up to 10 seconds

Security

  • A key sees what its user may see, narrowed by its scopes; make a user with just the access the other system needs
  • A wrong key gets 401; a call outside the key's scopes gets 403
  • The receiving system checks X-SmartMy-Signature to know a call is genuine
  • Every key and webhook change is kept in its history

Who uses it

HR administratorMakes and revokes keys, sets up webhooks and reads the call log.
Your IT team or partnerPuts the key into the other system, reads the API and checks the webhook signature.

Where you use it

  • Web: HRMS > Employees > Configuration > HRMS Setup > Integrations (API Keys, Webhooks)
  • The API: https://<your workspace>/hrms/api/v1/
  • Developer notes: the HRMS API document, section 6; ask us for it
  • Not in the phone app

What you control

Settings

  • Per key: Acts As (you, to start with), the entity, and scopes (Employees on, others off, to start with)
  • Per webhook: the event, the address to call, active or not

Notifications

  • No notices: the Calls tab and each key's last use show what happened

Questions

Can the API change records, such as add an employee?

Not yet. The API reads employees, attendance, leave and payslips. Tell us which changes you need before you plan on them.

Can a key read salaries?

Only if you tick Payroll Results and the user it acts as may see payslips. Give each system its own key with only the scopes it needs.

How does our system know a webhook call is really from you?

Each call carries X-SmartMy-Signature, the HMAC-SHA256 of the body with the webhook's secret. Your system works out the same value and compares.

What if our server is down when an employee leaves?

The call is tried again every 15 minutes, up to five times. Each attempt and the answer are listed on the webhook's Calls tab.

We lost a key. What now?

Revoke it in API Keys; it stops at once. Make a new key and put it into the other system. The full key is never kept, so it cannot be shown again.

Related features

ENGAGEMENT, GOALS AND HR TOOLSWorkflow rules without codeTell the HRMS what to do when a record is added, gets a value or a date comes, and it matches your filter. It can set a field, make a to-do, write a note, tell someone or ask for an approval, and every run is logged.ROLES AND ACCESSWho sees what: employees, managers and HR officersEach employee sees only their own records and each manager sees everyone below them. HR staff get roles per Entity, limited to some departments or locations if you wish. A role can also hide parts of the record, such as bank details.ENGAGEMENT, GOALS AND HR TOOLSSign-in with a code, passkeys and single sign-onEvery employee and manager has their own login and works on their own records. In the app they can sign in with a one-time code by WhatsApp or SMS, or with a passkey. On the web they use a password, a passkey or your Microsoft or Google account. Leavers' accounts are switched off.PAYROLLPayslips, bank files and accounting entriesOnce a payroll run is approved, each employee gets a password-protected PDF payslip by email. The bank gets a transfer file in its own format with a covering letter. The salary posts to each Entity's accounts.VIEWS AND REPORTSHR reports and the custom report builderHeadcount, attrition, salary cost, leave liability and more than 20 payroll and statutory reports, most of them on screen, in Excel and as PDF. In Scale, HR builds its own reports without code and shares them; each person sees only what their access allows.

See your own month run in it.

Tell us how many people you have, how you take attendance and how your salary is structured. We will show you SmartMy HRMS set up that way.
Talk to usCompare plans