SmartRecruiters

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

SmartRecruiters developer portal

Customer API reference

Guides: getting started, authentication, webhooks

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 (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.

Job

Open the approved position

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

Intent ID correlation

Carry the Intent ID

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.

Job Property

Fallback carrier when refNumber is already in use

Mapping	Detail
Canonical to destination	intent_id -> properties[{id: <Intent ID property>, 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

Hire back-sync

Close the loop

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

How composerID connects

The five ways composerID reaches a destination, and the minimum a destination must offer.

Publishing

Plan, preflight and publish: how a decision becomes a valid record in a destination.

All destinations

Every destination composerID documents, with its category and coverage status.

⌘I

Get started

Concepts

Guides

Destinations

Upstream connectors

API reference

Endpoints

Manuscript API (Triage)

Manuscript endpoints

Resources

Integration path

Vendor documentation

SmartRecruiters developer portal

Customer API reference

Guides: getting started, authentication, webhooks

API posture

Publish target and field mapping

Next steps

How composerID connects

Publishing

All destinations

​Integration path

​Vendor documentation

SmartRecruiters developer portal

Customer API reference

Guides: getting started, authentication, webhooks

​API posture

​Publish target and field mapping

​Next steps

How composerID connects

Publishing

All destinations

Integration path

Vendor documentation

API posture

Publish target and field mapping

Next steps