Skip to content
Ratify

API quickstart

Keep Ratify current from your HR system with a short script, and pull people, matters, and upcoming dates into your own reports.

Read the API reference

The API is for servers and scripts, not browsers. It's included in the Standard and Enterprise plans. Every request goes to https://api.ratify.win/v1 with an API key, and is recorded in your organization's audit log.

1. Create a key

  1. In Ratify, an Owner or Admin opens Settings, then Integrations, and chooses “Create an API key”.
  2. Name it for what will use it, such as “Workday sync”. Choose “Read people and matters” for reports, or “Read, and create or update people” for a sync that changes job details. Choose when it stops working, if it should.
  3. Copy the key. It's shown once. Keep it where your scripts read secrets, never in code or a shared document. If it's lost or shared by mistake, revoke it on the same page and create another.

The examples below read the key from an environment variable:

export API_KEY="ik_test_…"   # the key you copied

2. List people

Send the key in the Authorization header. Lists come 50 at a time; pass next_cursor back as cursor for the next page.

curl -s "https://api.ratify.win/v1/people?employment_status=ACTIVE" \
  -H "Authorization: Bearer $API_KEY"
{
  "data": [
    {
      "id": "0192f0c4-7b1e-7c3a-9d2e-000000000001",
      "display_name": "Ana Example",
      "employee_number": "E-1001",
      "work_email": "[email protected]",
      "job_title": "Data Engineer",
      "department": "Platform",
      "employment_status": "ACTIVE",
      "archived": false,
      "current_statuses": [ … ],
      "updated_at": "2026-10-02T14:05:00Z"
    }
  ],
  "next_cursor": "…"
}

Dates and statuses are as recorded by HR or counsel. The API doesn't decide anyone's legal status or which date governs a status; your immigration counsel decides legal questions.

3. Update one person

Find the person by the identifier your HR system uses (an employee number or a work email), then send only the fields that changed. Send null to clear one. This needs a key that can create or update people.

curl -s "https://api.ratify.win/v1/people/lookup?employee_number=E-1001" \
  -H "Authorization: Bearer $API_KEY"
curl -s -X PATCH "https://api.ratify.win/v1/people/<id from the lookup>" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_title": "Senior Data Engineer", "department": "Platform"}'

The change shows on the person's timeline as made by “API key: Workday sync”, under the key's name.

4. Sync from an HRIS export

Export a CSV from your HR system with these columns:

employee_number,job_title,department,manager_name,manager_email,work_location,employment_status
E-1001,Senior Data Engineer,Platform,Sam Rivera,[email protected],Austin,ACTIVE
E-1002,Product Designer,Design,Lee Park,[email protected],Remote,ON_LEAVE

Then run this script with the export. For each row it looks the person up by employee number and sends only the fields that differ. It waits and retries when it reaches the rate limit.

#!/usr/bin/env python3
"""Update employment fields in Ratify from an HRIS export (CSV).

Usage: API_KEY=ik_test_… python3 sync.py hris-export.csv
Needs only Python 3. Rows whose employee number isn't found are listed.
"""
import csv, json, os, sys, time, urllib.error, urllib.parse, urllib.request

API = "https://api.ratify.win/v1"
FIELDS = ["job_title", "department", "manager_name", "manager_email",
          "work_location", "employment_status"]


def call(method, path, body=None):
    data = json.dumps(body).encode() if body is not None else None
    while True:
        req = urllib.request.Request(API + path, data=data, method=method, headers={
            "Authorization": "Bearer " + os.environ["API_KEY"],
            "Content-Type": "application/json",
        })
        try:
            with urllib.request.urlopen(req) as res:
                return res.status, json.load(res)
        except urllib.error.HTTPError as err:
            if err.code == 429:  # over the limit: wait as told, then retry
                time.sleep(int(err.headers.get("Retry-After", "1")))
                continue
            return err.code, json.load(err)


with open(sys.argv[1], newline="") as f:
    for row in csv.DictReader(f):
        number = row["employee_number"]
        status, person = call("GET", "/people/lookup?" +
                              urllib.parse.urlencode({"employee_number": number}))
        if status == 404:
            print(f"{number}: not found")
            continue
        if status != 200:
            sys.exit(f"{number}: {person['message']} ({person['requestId']})")
        # Send only what changed; an empty cell clears the field
        # (employment_status can't be cleared, so an empty one is skipped).
        changes = {k: row[k] or None for k in FIELDS
                   if k in row and (row[k] or None) != person.get(k)}
        if changes.get("employment_status", "") is None:
            del changes["employment_status"]
        if not changes:
            continue
        status, saved = call("PATCH", f"/people/{person['id']}", changes)
        if status != 200:
            sys.exit(f"{number}: {saved['message']} ({saved['requestId']})")
        print(f"{number}: updated {', '.join(changes)}")

To add new hires, send POST /v1/people with anIdempotency-Key header, so a retried request never adds the same person twice. See the reference.

Limits and errors

  • Each key may make 60 requests a minute, in bursts of up to 20. Past that, requests get 429 with Retry-After.
  • A key reads people, their current statuses and tracked dates, matters, upcoming dates, and what needs attention. It never reaches documents, notes, dependents, members, billing, or settings.
  • Changes follow the same rules as the app, including the plan's limits and a read-only organization.
  • A revoked or expired key gets 401. Within v1, changes to the API only add things.
  • Errors share one shape: a stable code, a message you can show, and a reference for support.
{
  "code": "validation_failed",
  "message": "Some of the information sent isn't valid. Check the highlighted fields and try again.",
  "fieldErrors": { "manager_email": "Enter an email address, like [email protected]." },
  "requestId": "…"
}

Every operation, field, and error in the API reference.