> ## Documentation Index
> Fetch the complete documentation index at: https://www.composer.id/llms.txt
> Use this file to discover all available pages before exploring further.
# SmartRecruiters
> SmartRecruiters (ATS): the API posture, publish target and field mapping composerID publishes a decision reference through.
This page records how composerID publishes into SmartRecruiters: the vendor's API posture, the publish target and field mapping, and the documentation each claim rests on. It is for anyone evaluating the connection or building against it.
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.
Category: ATS. Coverage status: Specification mapped. Vendor documentation: public developer portal.
## Integration path
How composerID connects to this destination, at a glance.
| Step | Detail |
| -------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Authentication | Two documented credential types, both tenant-scoped. |
| composerID publishes | Job: POST /jobs |
| Intent ID lands on | `Job` `refNumber`, written into the destination record |
| Back-sync | Webhooks: the destination pushes events; composerID verifies each delivery and lands it on the intent's timeline. |
## Vendor documentation
## API posture
| Aspect | Detail |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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. |
| 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](https://api.smartrecruiters.com) (companies hosted in the EU data centre use a separate regional API host; confirm the host at onboarding) |
| 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. |
| Events posture | Webhooks |
| 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. |
| 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 |
## Publish target and field mapping
Each object below pairs the canonical intent fields with the destination's own fields and operations. The mapping is indicative until it is confirmed against a tenant at onboarding.
| Mapping | Detail |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Canonical to destination | title, refNumber = intent\_id, department, location, typeOfEmployment, experienceLevel, properties\[] |
| Target | POST /jobs |
| Requirement | Required |
| Notes | 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 |
| Mapping | Detail |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Canonical to destination | intent\_id -> job.refNumber |
| Target | Job.refNumber (client-supplied reference, read back on GET /jobs/\{id} and exposed on the public Posting API once published) |
| Requirement | Required |
| Notes | 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. |
| Mapping | Detail |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Canonical to destination | intent\_id -> properties\[\{id: \, value}] |
| Target | Configuration API job properties + Job.properties\[] |
| Requirement | Tenant optional |
| Notes | 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 |
| Mapping | Detail |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Canonical to destination | job.status, application.status, offer approved, hire |
| Target | Webhooks API subscriptions (job.*, application.*, offer.\*) |
| Requirement | Recommended |
| Notes | 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 |
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.
## Next steps
The five ways composerID reaches a destination, and the minimum a destination must offer.
Plan, preflight and publish: how a decision becomes a valid record in a destination.
Every destination composerID documents, with its category and coverage status.