SmartRecruiters (platform)
SmartRecruiters is a cloud ATS whose authenticated Customer API exposes Jobs, Candidates and their applications, Offers, Interviews, Users and a company-configured set of Job Properties, behind an open developer portal with a separately versioned Webhooks API. The Job is the system of record for an approved permanent hire and carries a client-supplied reference number (refNumber) alongside tenant-defined properties. composerID creates the Job for the decided role and stamps the Intent ID into refNumber, reads it back on the Job (and on the public posting once the job is published), and correlates job, application and offer webhook events to it.
The public API facts composerID's adapter relies on. Tenant-specific details (custom fields, picklists, approval chains) are confirmed during connection and folded into the MappingProfile.
| Authentication | Two documented credential types, both tenant-scoped: a company API key issued in the SmartRecruiters admin and sent in the X-SmartToken header, or OAuth 2.0 client credentials (client id and secret exchanged for a bearer token; marketplace partner apps use OAuth with per-customer consent). Which type the tenant issues, and the scopes it grants, are confirmed at onboarding. |
|---|---|
| API style | REST, JSON. The main Customer API list endpoints (jobs, candidates) page with limit and offset and return a totalFound count; some newer surfaces page with an opaque page-id cursor (indicative until confirmed). A separate unauthenticated Posting API serves published job ads by company identifier. |
| Base URL | https://api.smartrecruiters.com (companies hosted in the EU data centre use a separate regional API host; confirm the host at onboarding) |
| Objects | jobs (refNumber, title, status, department, location, typeOfEmployment, experienceLevel, properties[]), job properties (Configuration API, company-defined pick lists), candidates and their applications to jobs, offers, interviews, users, departments (Configuration API), webhook subscriptions |
| Events / webhooks | A separately versioned Webhooks API: subscriptions are created over the API with a callback URL and events list, verified by a callback handshake (a secret header the receiver echoes back) and then activated, and deliver events for jobs (created, status updated), applications (created, status updated) and offers, with retries on failure. Header names, signature scheme, retry schedule and exact event names are indicative until confirmed at onboarding. |
| Rate limits | Per-credential throttling returning 429 with rate-limit response headers. The published ceiling is modest (of the order of ten requests per second per credential); treat the exact figure and header names as indicative until confirmed at onboarding and back off on 429. |
“Docs confidence” describes how deterministic our mapping templates can be before we connect to a tenant. Even with public docs, implementations vary, especially around custom fields, approval flows and object extensions.
Deterministic mapping
Common Workforce Model fields map to known API fields. Best for standard objects (requisitions, assignments, timesheets, POs).
Tenant discovery
composerID can scan tenant configuration (custom fields, picklists, required fields) where the platform permits it, then generate a tenant‑specific MappingProfile.
Enrichment loop
If the target platform requires a field the Intent record doesn't yet have, composerID emits an enrichment_request back to the intake layer.
An opinionated baseline. The platform adapter enforces additional requirements via preflight. “Tenant required” fields are discovered during connection and added to the MappingProfile.
| Object | Canonical fields | Platform target | Required status | Notes |
|---|---|---|---|---|
| Job Open the approved position |
title, refNumber = intent_id, department, location, typeOfEmployment, experienceLevel, properties[] | POST /jobs | Required | Property values are pick-list ids from the Configuration API, resolved by name at preflight. Tenant approval workflows can hold an API-created job in a pending status before it is publishable |
| Intent ID correlation Carry the Intent ID |
intent_id -> job.refNumber | Job.refNumber (client-supplied reference, read back on GET /jobs/{id} and exposed on the public Posting API once published) | Required | refNumber is free text and SmartRecruiters does not enforce its uniqueness: composerID guarantees one Intent ID per Job and stores the SmartRecruiters job id against the Intent ID, so lookup is by id, not by search. Server-side filtering of the job list by refNumber is not asserted. Deep link to the job detail page is illustrative and uses the job id. |
| Job Property Fallback carrier when refNumber is already in use |
intent_id -> properties[{id: <Intent ID property>, value}] | Configuration API job properties + Job.properties[] | Tenant optional | Weaker fallback: job properties are company-configured and typically pick lists, so whether the tenant can define a free-text property to hold an opaque id is confirmed at onboarding. Used only where the tenant reserves refNumber for an HRIS position number |
| Hire back-sync Close the loop |
job.status, application.status, offer approved, hire | Webhooks API subscriptions (job.*, application.*, offer.*) | Recommended | Events reference the job id; composerID resolves the id to the Intent ID it stamped on refNumber. Read scope on jobs, applications and offers only; event names indicative until confirmed |
Idempotency & drift: publish + reconcileExpand
Publish operations are idempotent using a deterministic key {intent_id}-{intent_version}-{target_system}. Because humans can change records inside the platform, composerID supports reconciliation: it compares the platform record snapshot to the canonical intent and flags drift.
Real deployments rely on program-specific custom fields (for compliance, approvals, GL coding, rate rules or supplier constraints). composerID is designed to generate tenant‑specific mappings rather than forcing you to redesign your intake.
How scanning works
High-level flow
What gets produced
Portable artefacts
Important: where this platform is tenant-definedExpand
Credentials are issued per company and scoped by the admin, and only the tenant can say whether it issues an X-SmartToken API key or an OAuth client and which scopes it grants: request only the job, application, offer and webhook scopes publishing and read-back need. refNumber is the natural Intent ID carrier but is free text with no uniqueness constraint, so agree at onboarding whether it is free for composerID or already holds an HRIS position number (then a dedicated Job Property is configured, and the tenant confirms a property type that accepts free text exists). Job approval workflows, the pick-list values behind department, location and properties, EU regional hosting and the exact rate-limit ceiling are tenant facts to confirm; nothing here claims a live tenant.
Use this page alongside the API + Schemas docs to implement: destination connection, preflight validation, publish, webhook back-sync and reconciliation.