Developer platform
Offerrole Partner API
One REST API to connect your ATS or HRIS to Offerrole. Push candidates in the export format your system already produces, read open jobs for syndication, and query anonymized talent cohorts. Keys, payload testing, and live logs live in the Integration Studio.
Overview
Base URL: https://offerrole.com/api/partner. All endpoints speak JSON over HTTPS. Requests are authenticated with a bearer API key. Candidate records you push are canonicalized by the same mapper pipeline our CSV importer uses, so field handling is identical whether data arrives by file or by API. Every ingest creates an auditable import batch with the key owner recorded as the importer.
Authentication
Create a key in the Integration Studio (employer account required). Keys look like sh_live_… and are shown once — only a SHA-256 hash is stored on our side. Send it on every request:
Authorization: Bearer sh_live_your_key_hereRevoking a key in the Studio takes effect immediately. Max 10 active keys per account.
Quickstart
Push one candidate from a Greenhouse-style export in under a minute:
curl -X POST https://offerrole.com/api/partner/v1/candidates \
-H "Authorization: Bearer sh_live_..." \
-H "Content-Type: application/json" \
-d '{
"source": "greenhouse",
"records": [{
"First Name": "Dana",
"Last Name": "Alvarez",
"Email": "dana.alvarez@example.com",
"Job": "Senior Salesforce Administrator",
"Location": "Austin, TX"
}]
}'{
"source": "greenhouse",
"batchId": "1f6f…",
"received": 1,
"imported": 1,
"skipped": 0,
"errors": []
}Push candidates
source(optional) — one of the mapper ids below. Omit it and the format is auto-detected from your record keys.records— 1 to 500 objects of string key/value pairs, exactly as your ATS exports them.- Records without a mappable email are skipped and reported in
errors; the rest still import (partial success). - Re-pushing an existing email never overwrites candidate-provided data — the record is attached to the new batch and enriched only where fields were empty.
Read jobs
Returns up to 500 open postings with public fields plus canonical url and direct apply_url links — ideal for syndicating Offerrole jobs into an external board or internal mobility tool.
Supported ATS formats
Current registry (auto-detected in this precedence order):
| source id | System |
|---|---|
| greenhouse | Greenhouse Recruiting |
| lever | Lever |
| workable | Workable |
| smartrecruiters | SmartRecruiters |
| bamboohr | BambooHR ATS |
| jazzhr | JazzHR |
| taleo | Oracle Taleo |
| generic | Generic / unknown ATS |
The generic mapper accepts common column aliases (name/email/phone/title/company/location and more), so most unfamiliar exports work without any configuration.
Cohort analytics
Aggregate, anonymized talent-pool distributions for approved data partners. Provisioned separately — contact us before use.
Rate limits & errors
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_input / unknown_source | Body failed validation, or unknown source id. |
| 401 | unauthorized | Missing, malformed, or revoked API key. |
| 429 | rate_limited | Over 60 requests/minute on this key. Back off and retry. |
| 5xx | internal | Our fault — safe to retry with exponential backoff. |
Ingest is idempotency-friendly: batches are append-only and re-pushed emails never clobber existing candidate data, so retries are safe.
Integration Studio
The Studio is the operational side of this reference: create and revoke keys, paste a real payload from your ATS and see exactly how it maps before you ship, and watch live ingest logs with per-call status and durations.
Open the Integration Studio →Requires an employer account. OAuth-based connectors (Workday, SAP, Oracle, Merge, Finch, calendars, Slack) are managed separately under Integrations.