SmartRecruiters User Management API Guide

Auth method: API Key (X-SmartToken header) or OAuth 2.0

Setup steps

1. Log in to SmartRecruiters as an Admin.
2. Navigate to Settings > Admin > API & Integrations > API Keys.
3. Generate a new API key; copy the token value.
4. Include the token in all requests as the header: X-SmartToken: .
5. For OAuth 2.0: register an application under Settings > Admin > API & Integrations > OAuth Apps, obtain client_id and client_secret, and exchange credentials for a Bearer token via the token endpoint.

Required scopes

List Users

• Method: GET
• URL: https://api.smartrecruiters.com/users
• Watch out for: Inactive users are excluded by default; use ?active=false to include them.

Request example

GET /users?limit=20&offset=0
X-SmartToken: <token>

Response example

{
  "total": 150,
  "offset": 0,
  "limit": 20,
  "content": [
    {"id": "abc123", "firstName": "Jane", "lastName": "Doe", "email": "jane@example.com", "active": true}
  ]
}

Get User

• Method: GET
• URL: https://api.smartrecruiters.com/users/{userId}
• Watch out for: Returns 404 if the user ID does not exist or belongs to a different account.

Request example

GET /users/abc123
X-SmartToken: <token>

Response example

{
  "id": "abc123",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane@example.com",
  "role": "RECRUITER",
  "active": true
}

Create User

• Method: POST
• URL: https://api.smartrecruiters.com/users
• Watch out for: Duplicate email returns 409 Conflict. An invitation email is sent automatically upon creation.

Request example

POST /users
X-SmartToken: <token>
Content-Type: application/json

{"firstName":"John","lastName":"Smith","email":"john@example.com","role":"RECRUITER"}

Response example

{
  "id": "def456",
  "firstName": "John",
  "lastName": "Smith",
  "email": "john@example.com",
  "active": true
}

Update User

• Method: PATCH
• URL: https://api.smartrecruiters.com/users/{userId}
• Watch out for: Only fields included in the payload are updated; omitted fields are unchanged.

Request example

PATCH /users/def456
X-SmartToken: <token>
Content-Type: application/json

{"role":"HIRING_MANAGER","active":true}

Response example

{
  "id": "def456",
  "role": "HIRING_MANAGER",
  "active": true
}

Deactivate User

• Method: DELETE
• URL: https://api.smartrecruiters.com/users/{userId}
• Watch out for: This deactivates the user rather than permanently deleting the record. The user's historical data is retained.

Request example

DELETE /users/def456
X-SmartToken: <token>

Response example

HTTP 204 No Content

Get Current User (Me)

• Method: GET
• URL: https://api.smartrecruiters.com/users/me
• Watch out for: Returns the user associated with the API token in use; useful for validating token identity.

Request example

GET /users/me
X-SmartToken: <token>

Response example

{
  "id": "abc123",
  "firstName": "Jane",
  "email": "jane@example.com",
  "role": "ADMIN"
}

List Roles

• Method: GET
• URL: https://api.smartrecruiters.com/configuration/roles
• Watch out for: Role IDs returned here are the valid enum values for the role field on user create/update.

Request example

GET /configuration/roles
X-SmartToken: <token>

Response example

{
  "content": [
    {"id": "RECRUITER", "label": "Recruiter"},
    {"id": "HIRING_MANAGER", "label": "Hiring Manager"},
    {"id": "ADMIN", "label": "Admin"}
  ]
}

Search Users

• Method: GET
• URL: https://api.smartrecruiters.com/users
• Watch out for: The q parameter performs a partial match on name and email. Results are not guaranteed to be sorted consistently across pages.

Request example

GET /users?q=jane&limit=10
X-SmartToken: <token>

Response example

{
  "total": 2,
  "content": [
    {"id": "abc123", "email": "jane@example.com"}
  ]
}

• Rate limits: SmartRecruiters enforces per-API-key rate limits. Limits vary by plan. HTTP 429 is returned when exceeded.
• Rate-limit headers: Yes
• Retry-After header: No
• Rate-limit notes: X-RateLimit-Limit and X-RateLimit-Remaining headers are returned. No Retry-After header documented. Burst limits may apply; back off exponentially on 429 responses.
• Pagination method: offset
• Default page size: 10
• Max page size: 100
• Pagination pointer: offset / limit

• Webhooks available: Yes
• Webhook notes: SmartRecruiters supports outbound webhooks (called 'Subscriptions') for job and candidate lifecycle events. User provisioning/deprovisioning events are not explicitly documented as webhook triggers; use SCIM or polling for user sync.
• Alternative event strategy: For user lifecycle events, use SCIM 2.0 provisioning or poll GET /users on a schedule.
• Webhook events: job.created, job.updated, job.published, job.unpublished, application.created, application.updated, application.hired, application.rejected

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Corporate/Enterprise

• Endpoint: https://api.smartrecruiters.com/scim/v2

• Supported operations: GET /Users (list users), GET /Users/{id} (get user), POST /Users (create user), PUT /Users/{id} (replace user), PATCH /Users/{id} (update user), DELETE /Users/{id} (deactivate user), GET /Groups (list groups), POST /Groups (create group), PATCH /Groups/{id} (update group membership), DELETE /Groups/{id} (delete group)

Limitations:

• SCIM is only available on Corporate and Enterprise plans; not available on Essential or Professional.
• SCIM token is separate from the standard API key and must be generated in the SCIM settings section.
• Group provisioning maps to SmartRecruiters departments/teams, not arbitrary groups.
• Password sync is not supported via SCIM.
• SSO is not a prerequisite for SCIM but is commonly deployed alongside it.

Three scenarios cover the primary integration surface.

First, provisioning a new recruiter: call GET /configuration/roles to confirm the RECRUITER enum, then POST /users with role, department.id, and email

a 409 on duplicate email means the account exists and may need reactivation via PATCH with active: true rather than a new POST.

Second, deprovisioning via SCIM: resolve the user with a filter query on userName, then PATCH /scim/v2/Users/{id} with an RFC 7644-compliant active: false operation

deactivation is soft-delete only, and the user's audit trail is preserved.

Third, bulk audit: paginate GET /users with limit=100 and increment offset until offset exceeds total;

offset pagination can drift if accounts change during iteration, so schedule audits during low-activity windows.

Provision a new recruiter and assign to a department

1. GET /configuration/roles to confirm the RECRUITER role ID.
2. GET /configuration/departments (or equivalent) to retrieve the target department ID.
3. POST /users with firstName, lastName, email, role: 'RECRUITER', and department.id.
4. Capture the returned user id for future updates.
5. User receives an automatic invitation email to set their password.

Watch out for: If the email already exists in the system (even as inactive), the API returns 409. Reactivate via PATCH /users/{id} with active: true instead.

Deprovision a departing employee via SCIM

1. Obtain the SCIM bearer token from SmartRecruiters Admin > SCIM Settings.
2. GET /scim/v2/Users?filter=userName eq "user@example.com" to resolve the SCIM user ID.
3. PATCH /scim/v2/Users/{id} with {"Operations":[{"op":"replace","path":"active","value":false}]} to deactivate.
4. Verify deactivation with GET /scim/v2/Users/{id} and confirm active: false.

Watch out for: SCIM deactivation is soft-delete; the user's job history and audit trail are preserved. Ensure your IdP SCIM connector sends the correct PATCH body format (RFC 7644).

Bulk-list all active users for an audit

1. GET /users?limit=100&offset=0 with X-SmartToken header.
2. Read total from response; calculate number of pages (ceil(total/100)).
3. Iterate pages by incrementing offset by 100 until offset >= total.
4. Aggregate content arrays across all responses.
5. Filter or export the resulting user list as needed.

Watch out for: Offset pagination can produce duplicate or missing records if users are created/deactivated during iteration. Run audits during low-activity windows or accept minor drift.

Several non-obvious behaviors will break integrations if not handled explicitly. The X-SmartToken header is required for API key flows - do not substitute Authorization: Bearer, which is reserved for OAuth. Role values are case-sensitive enums;

lowercase submissions return 400. POST /users always triggers an invitation email with no documented suppression flag, which matters for bulk-provisioning flows. The DELETE /users/{id} endpoint is a soft-delete;

no hard-delete endpoint is publicly documented, so identity graph reconciliation must treat active: false as the terminal state rather than record absence. Offset pagination has no cursor fallback, making large-set audits susceptible to record duplication or omission if the user list mutates mid-iteration.

Finally, webhook subscriptions cover job and candidate lifecycle events but do not fire on user provisioning or deprovisioning events - use SCIM or scheduled polling of GET /users for user-state sync.