SmartRecruiters ATS API Directory

SmartRecruiters ATS is a robust, cloud-based applicant tracking system designed to modernize how organizations hire. Using AI-driven capabilities, it covers the full hiring lifecycle, from job posting and sourcing to application tracking and interview scheduling. Built for the Human Resources domain, SmartRecruiters ATS helps HR teams, recruiters, and hiring managers move faster, stay aligned, and run a cleaner hiring process without drowning in manual work.

Where it gets even more useful is integration. SmartRecruiters ATS is built to plug into the rest of your HR and recruiting stack, so your systems don’t operate in silos. That integration story is powered by the SmartRecruiters ATS API, which lets you extend and customize workflows based on how your organization actually hires.

Key highlights of SmartRecruiters ATS APIs

1. End-to-end hiring flow coverage
   You can manage core objects across hiring, jobs, candidates, applications, interviews, offers, approvals, and audit events, without stitching together hacks.
2. Automate approvals and offer governance
   The approvals endpoints let you trigger, fetch, and act on approval requests (approve/reject, comments), which is essential for offer and hiring compliance.
3. Assessment partner integrations are first-class
   The Assessment API supports company-level integration setup, partner configuration, results updates, and attachments, useful if you’re plugging in testing/assessment vendors.
4. Candidate lifecycle control (not just read-only sync)
   You can create candidates, parse CVs, manage attachments, update statuses, track status history, and even delete candidates where allowed, real operational control.
5. Configuration data is accessible for “system of record” alignment
   Pull candidate properties, job properties, sources, departments, hiring processes, rejection reasons, etc., so your CRM/HRIS/reporting stays consistent with SmartRecruiters.
6. Interview scheduling + status tracking is API-driven
   Work with interview types, interview objects, timeslots, and participant statuses, critical for syncing calendar workflows and interviewer coordination.
7. Audit-ready visibility
   The Audit API supports filtering and pagination and retains data for at least 26 months, useful for investigations, compliance, and internal audits.
8. Supports scale and safe platform operations
   Pagination, rate limiting, versioning, and structured error handling make it practical to run integrations in production without constant firefighting.

SmartRecruiters ATSAPI Endpoints

Approvals API

• POST https://api.smartrecruiters.com/approvals-api/v201910/approvals : This API endpoint allows the creation of a new approval request based on an existing approval request identified by the provided baseId. If the base approval request is pending, it will be abandoned. The new request will have a new id, type, decision mode, and steps, all with PENDING statuses and decisions. The request requires headers specifying 'accept' and 'content-type' as 'application/json'. The body must include 'baseId', 'type', 'decisionMode', and 'steps'. The response will return a 201 status with the new approval request details if successful, or error codes 400 or 401 if there are issues such as missing baseId, invalid approver ids, or unauthorized access.
• GET https://api.smartrecruiters.com/approvals-api/v201910/approvals/{approvalRequestId} : This API retrieves the details of an approval request using the specified approvalRequestId. The request requires the 'accept' header to be set to 'application/json'. The path parameter 'approvalRequestId' is mandatory and identifies the specific approval request. The response includes details such as the approval request id, subject, type, decision mode, status, and steps involved in the approval process. If the approval request is found, a 200 status code is returned with the approval details. If not found, a 404 status code is returned with an error code and message.
• POST https://api.smartrecruiters.com/approvals-api/v201910/approvals/{approvalRequestId}/approve-decisions : This API endpoint is used to approve a decision for a specific approval request in the SmartRecruiters system. The request requires the approvalRequestId as a path parameter and the approverId in the request body. The headers must include 'accept' and 'content-type' set to 'application/json'. A successful request will approve the decision, while errors may occur if the approval request is not found, already completed, or if the approver is not allowed to take the decision. The response will include error codes and messages in case of failure.
• GET https://api.smartrecruiters.com/approvals-api/v201910/approvals/{approvalRequestId}/comments : This API endpoint retrieves comments for a specific approval request identified by the 'approvalRequestId' path parameter. The request requires an 'accept' header with the value 'application/json'. The response includes a 200 status code with a list of comments, each containing 'content', 'authorId', and 'createdOn' fields. If the approval request is not found, a 404 status code is returned with an error code 'APPROVAL_REQUEST_NOT_FOUND'.
• POST https://api.smartrecruiters.com/approvals-api/v201910/approvals/{approvalRequestId}/reject-decisions : This API endpoint is used to reject an approval request decision. It requires the approval request identifier as a path parameter and a JSON body containing the approver's ID and a comment. The request headers must include 'accept' and 'content-type' set to 'application/json'. A successful rejection returns a 204 status code. Errors may include 400 or 404 status codes with detailed error messages.

Assessment API

• POST https://api.smartrecruiters.com/assessment-api/v202010/integration/company/{companyId} : This API endpoint is used to set up an integration for a company. It validates if the token has the client_credentials_write scope and if the company has given consent for integration with the partner. It saves the credentials sent by the partner and creates credentials for the current company, which are then sent back to the partner. The request requires a path parameter 'companyId' and a request body containing 'clientId' and 'clientSecret'. The response can be a successful creation of credentials or various error messages indicating issues such as invalid request body, unauthorized request, missing required scopes, or existing integration.
• PATCH https://api.smartrecruiters.com/assessment-api/v202010/orders/{orderId}/results : The Update Assessment Package Results API allows users to update the results for a package ordered using the PATCH method. It follows RFC 7396 rules to describe a set of modifications. The API requires the 'orderId' as a path parameter, which is a UUID representing the order ID. The request body can include details such as assessment package date, submission date, name, status, score, score label, summary, attachments, and assessment results. The response returns the updated details of the assessment package, including the same fields as the request body. The API handles various response codes, including 200 for successful updates, 400 for invalid updates, 401 for unauthorized requests, 403 for missing required scopes, 404 for non-existent orders, and 415 for unsupported payload formats.
• POST https://api.smartrecruiters.com/assessment-api/v202010/orders/{orderId}/results/attachment : This API endpoint allows users to add an attachment to a specific order identified by the orderId path parameter. The request must include the orderId as a path parameter and the attachment content in multipart/form-data format in the request body. The response will return a 201 status code with the URL of the created attachment if successful. If the request is unauthorized, missing required scopes, or if the order does not exist, appropriate error messages will be returned with status codes 401, 403, and 404 respectively.
• PUT https://api.smartrecruiters.com/assessment-api/v202010/partner/configuration : This API endpoint is used to save the partner's configuration in the SmartRecruiters system. The request requires a JSON body with several required fields, including URLs for various partner API endpoints, consent display mode, and supported assessment types. The consent display mode can be either REDIRECT or POPUP, determining how end users interact with the consent URL. The response will confirm the configuration with the same fields provided in the request. If the configuration is invalid, unauthorized, or missing required scopes, appropriate error messages will be returned.
• GET https://api.smartrecruiters.com/assessment-api/v202107/assessment-orders : The Retrieve Assessment Orders API endpoint allows clients to fetch assessment orders associated with a specific application ID. The request requires a query parameter 'applicationId' which is a GUID representing the application. The response includes an array of assessment orders, each containing details such as applicationId, orderId, assessmentPackageDate, submissionDate, assessmentPackageName, description, status, score, scoreLabel, summary, attachments, and assessments. The API returns a 200 status code with the assessment orders if successful, a 401 status code if the caller is not authorized, a 404 status code if the application is not found, and a 500 status code for unexpected errors.

Audit API

• GET https://api.smartrecruiters.com/audit-api/v201910/audit-events : The Retrieve Audit Events API allows users to fetch a list of audit events from the SmartRecruiters system. The API supports filtering by event date, event name, author type, author ID, entity type, and entity ID. It returns a paginated list of events, each with details such as event name, date, author type, and context information. The API retains data for at least 26 months and defaults to the last 7 days if no date range is specified. The response includes a nextPageId for pagination and a limit on the number of events returned.

Candidates API

• GET https://api.smartrecruiters.com/candidates : This API endpoint retrieves candidates matching specified criteria from the SmartRecruiters platform. It supports various query parameters for filtering candidates, such as keyword search, job ID, location, status, consent status, and more. The response includes candidate details like ID, name, email, location, and job assignments. Pagination is supported through the 'limit' and 'pageId' query parameters, with links to the next page provided in the response headers. The API returns a JSON object containing the list of candidates and metadata about the search results.
• DELETE https://api.smartrecruiters.com/candidates/attachments/{attachmentId} : This API endpoint is used to delete a candidate's attachment by its identifier. The DELETE method is used, and the endpoint requires the 'attachmentId' as a path parameter. The request should include an 'accept' header with 'application/json' as the value. If the deletion is successful, a 204 status code is returned with no content. If the user does not have permission to delete the attachment, a 403 status code is returned with a message and error details. If the attachment does not exist, a 404 status code is returned with a message and error details.
• POST https://api.smartrecruiters.com/candidates/consent-requests : This API endpoint is used to create consent requests for candidates. It is a POST request to the URL https://api.smartrecruiters.com/candidates/consent-requests. The request headers must include 'accept' and 'content-type' both set to 'application/json'. The request body must contain a 'content' array with at least one and at most 1000 objects, each having a 'candidate id'. The response will return a list of results for each consent request, with a status of 202 if successfully scheduled or 403 if consent cannot be requested due to missing privacy policy configuration.
• POST https://api.smartrecruiters.com/candidates/cv : This API endpoint allows you to parse a resume, create a candidate, and assign them to a Talent Pool. The request is made via a POST method to the URL https://api.smartrecruiters.com/candidates/cv. The request headers must include 'accept: application/json' and 'content-type: multipart/form-data'. The body of the request should contain the resume file to be parsed, along with optional parameters such as sourceTypeId, sourceSubTypeId, sourceId, and internal to specify the candidate's source and whether they are a company employee. Upon successful creation, the API returns a 201 status code with detailed candidate information including personal details, location, web presence, education, experience, and assignments. In case of errors, the API returns appropriate error messages with status codes 400, 403, or 404, indicating issues such as unparsable resumes, permission denial, or non-existent source types.
• DELETE https://api.smartrecruiters.com/candidates/{id} : The Delete Candidate API allows you to delete a candidate from the system using their unique identifier. The API requires the candidate's ID as a path parameter. The request should include an 'accept' header specifying 'application/json'. A successful deletion returns a 204 status code with no content. If the candidate access is denied, a 403 status code is returned with a JSON body containing error details. If the candidate is not found, a 404 status code is returned with a JSON body containing error details.
• GET https://api.smartrecruiters.com/candidates/{id}/consent : This API endpoint retrieves the consent status of a candidate using their unique identifier. The request is made using the GET method to the URL 'https://api.smartrecruiters.com/candidates/{id}/consent'. The path parameter 'id' is required and represents the candidate's identifier. The request header must include 'accept: application/json'. The response will return a 200 status code with the candidate's latest consent status, which can be 'REQUIRED', 'PENDING', or 'ACQUIRED'. If the status is 'ACQUIRED', a date will also be provided. A 403 status code indicates that access to the candidate is denied, and an error message will be included in the response.
• GET https://api.smartrecruiters.com/candidates/{id}/consents : This API endpoint retrieves the consent decisions of a candidate based on the consent approach chosen by the customer. The response can either be a single consent decision or multiple decisions broken out by data scopes such as SmartRecruit and SmartCRM. If there is at least one pending consent request for a candidate, the response includes the date and time of the most recent request. The API requires the candidate's ID as a path parameter and returns a JSON object with the consent decisions. A 403 response indicates access denial with an error message.
• GET https://api.smartrecruiters.com/candidates/{id}/jobs/{jobId} : This API endpoint retrieves the details of a candidate's application to a specific job. It requires the candidate's ID and the job ID as path parameters. The response includes the application ID, status, sub-status, start date, source, reasons for rejection or withdrawal, actions, and the URL of the application details. The API returns a 200 status code with the application details if successful, a 403 status code if permission is denied, and a 404 status code if the application is not found.
• POST https://api.smartrecruiters.com/candidates/{id}/jobs/{jobId}/attachments : This API endpoint allows you to attach a file to a candidate in the context of a given job. The request requires the candidate identifier and job identifier as path parameters. The request body must include the attachment type, which can be 'GENERIC_FILE', 'RESUME', or 'COVER_LETTER', and the file to be uploaded in binary format. The response will return a 201 status code with details of the attachment if successful. Possible error responses include 400 for file issues, 403 for permission issues, 404 if the job is not found, and 422 if the attachment limit is exceeded.
• GET https://api.smartrecruiters.com/candidates/{id}/jobs/{jobId}/offers : This API endpoint retrieves the job offers for a specific candidate identified by the 'id' path parameter and a specific job identified by the 'jobId' path parameter. The request requires an 'accept' header with the value 'application/json'. The response includes a list of offers with details such as offer ID, status, creation and update timestamps, and associated actions. Possible response statuses include 200 (success), 401 (access denied), 403 (no access to offers), and 404 (offers not found).
• GET https://api.smartrecruiters.com/candidates/{id}/jobs/{jobId}/offers/{offerId} : This API endpoint retrieves the details of a candidate's offer using the specified offer ID. The request requires the 'accept' header to be set to 'application/json'. The path parameter 'offerId' is mandatory and identifies the specific offer to be retrieved. The response includes the offer's ID, status, creation and update timestamps, additional properties, and actions related to the candidate, job, and details. Possible response statuses include 200 for a successful retrieval, 401 for access denial, 403 for no access to offers, and 404 if the offer is not found.
• GET https://api.smartrecruiters.com/candidates/{id}/jobs/{jobId}/offers/{offerId}/approvals/latest : This API endpoint retrieves the latest approval request for a given offer. It requires the 'offerId' as a path parameter to identify the specific offer. The request must include an 'accept' header with the value 'application/json'. The response can be a successful retrieval of the approval request ID (HTTP 200) or various error responses such as unauthorized access (HTTP 401), forbidden access (HTTP 403), or not found errors (HTTP 404) with appropriate error messages and codes.
• PUT https://api.smartrecruiters.com/candidates/{id}/jobs/{jobId}/onboardingStatus : This API sets the onboarding status for a candidate associated with a given job. It requires the candidate ID and job ID as path parameters. The request body must include the onboarding status, which can be 'READY_TO_ONBOARD', 'ONBOARDING_SUCCESSFUL', or 'ONBOARDING_FAILED'. The API returns a 204 status code if successful. If there are errors, such as no access to the candidate or the candidate/job not found, it returns a 403 or 404 status code with detailed error messages.
• GET https://api.smartrecruiters.com/candidates/{id}/jobs/{jobId}/properties : This API endpoint retrieves the properties of a candidate for a specific job. It requires the candidate ID and job ID as path parameters. An optional query parameter 'context' can be provided to specify the context for candidate properties to display, which can be one of PROFILE, OFFER_FORM, HIRE_FORM, or OFFER_APPROVAL_FORM. The response includes a list of candidate properties with details such as id, label, type, value, and actions. If the candidate properties cannot be accessed, a 403 error is returned. If the candidate is not assigned to the given job, a 404 error with code JOB_NOT_FOUND is returned.
• GET https://api.smartrecruiters.com/candidates/{id}/jobs/{jobId}/screening-answers : This API endpoint retrieves the screening question answers for a specific candidate's job. It requires the candidate identifier and job identifier as path parameters. The response includes the total number of answers found and an array of answer details, each containing the question ID, type, category, name, label, and records. The records include fields with IDs, labels, and values. The API returns an empty array if no screening answers are found. The response also includes predefined and custom questions, with labels used for human-readable formats.
• PUT https://api.smartrecruiters.com/candidates/{id}/jobs/{jobId}/source : This API endpoint is used to update a candidate's source for a specific job. It requires the candidate identifier and job identifier as path parameters. The request body must include the sourceTypeId and sourceId, with an optional sourceSubTypeId. The API returns a 204 status code on success. On failure, it returns error messages with codes such as INVALID_SOURCE_TYPE, SUBTYPE_REQUIRED, and INVALID_SOURCE for a 400 response, Candidate access denied for a 401 response, and Candidate is not assigned to given job for a 404 response.
• PUT https://api.smartrecruiters.com/candidates/{id}/jobs/{jobId}/status : This API endpoint allows updating a candidate's status for a specific job. The request requires the candidate's ID and job ID as path parameters. The request body must include the 'status' field, which can be one of several predefined values such as 'LEAD', 'NEW', 'IN_REVIEW', etc. Optional fields include 'subStatus', 'startsOn', and 'reason'. The response will be a 204 status code for a successful update, or an error message with a 400, 401, 403, or 404 status code if there are issues such as missing reasons, permission denial, or candidate-job mismatch.
• GET https://api.smartrecruiters.com/candidates/{id}/jobs/{jobId}/status/history : This API endpoint retrieves the status history of a candidate for a specific job. It requires the candidate's ID and the job ID as path parameters. The response includes the total number of status history records found and an array of status changes, each with a timestamp, status, sub-status, and possible actions. If the user does not have access to the candidate or job, a 403 error is returned with appropriate error codes. If the candidate or job is not found, a 404 error is returned.
• PUT https://api.smartrecruiters.com/candidates/{id}/tags : The Update Candidate Tags API allows you to update the tags for a specific candidate by replacing all existing tags with a new array of tags provided in the request body. The request requires the candidate's identifier as a path parameter and a JSON body containing an array of tags. The response will return a 201 status code with the updated tags if successful, or a 403 status code if there is no permission to access the candidate.

Job Applications API

• GET https://api.smartrecruiters.com/job-applications-api/v202112/job-applications/{jobApplicationId} : This API endpoint retrieves the details of a job application using the specified job application ID. The request requires the 'jobApplicationId' as a path parameter, which must be a valid UUID. The response includes the status of the job application, sub-status, source identifier, creation date, profile ID, and job ID. The API returns a 200 status code with the job application details if successful. If the 'jobApplicationId' is invalid, a 400 status code is returned with an error message. If the job application is not found, a 404 status code is returned with an error message.

Jobs API

• POST https://api.smartrecruiters.com/jobs : This API endpoint allows the creation of a new job in the SmartRecruiters system. The request is made via a POST method to the URL https://api.smartrecruiters.com/jobs. The request headers must include 'accept' and 'content-type' set to 'application/json'. The request body must include a JSON object with required fields such as 'title', 'function', 'industry', 'experienceLevel', and 'location'. Optional fields include 'refNumber', 'targetHiringDate', 'department', 'typeOfEmployment', 'eeoCategory', 'template', 'compensation', 'jobAd', and 'properties'. The response will return a 201 status code with details of the created job, including 'id', 'title', 'refNumber', 'createdOn', 'updatedOn', 'department', 'location', 'status', 'postingStatus', 'targetHiringDate', 'industry', 'function', 'typeOfEmployment', 'experienceLevel', 'eeoCategory', 'template', 'creator', 'compensation', 'jobAd', 'properties', and 'actions'. Error responses include 400 for invalid input, 403 for forbidden actions, and 409 for conflicts such as duplicate reference numbers.
• PUT https://api.smartrecruiters.com/jobs/{jobId} : This API endpoint allows you to update a job and its associated jobAd by providing a job ID in the path and the new state of the job in the request body. The request must include the job's title, function, industry, experience level, and location. The jobAd and all its properties must be provided, as any missing properties will be removed. The API returns the updated job with its jobAd. The response includes details such as the job's ID, title, reference number, creation and update timestamps, department, location, status, posting status, target hiring date, industry, function, type of employment, experience level, EEO category, template status, creator information, compensation details, jobAd sections, and available actions. The API handles various error responses, including department, industry, function, type of employment, job ad language, and EEO category not found errors, as well as input validation failures.
• GET https://api.smartrecruiters.com/jobs/{jobId}/approvals/latest : This API endpoint retrieves the latest approval details for a specific job identified by the jobId path parameter. The request can include an optional 'Accept-Language' header to specify the language of the returned content. The response includes details such as the approval request ID, positions associated with the job, and salary range. Possible response codes include 200 for successful retrieval, 401 for forbidden access, 403 for no access to approvals, and 404 if no approvals are found for the job.
• POST https://api.smartrecruiters.com/jobs/{jobId}/candidates : This API endpoint allows you to create a new candidate and assign them to a specific job using the job ID. It is crucial to track the candidate's source accurately by including the sourceDetails object in the request body. The request requires the candidate's first name, last name, and email, and optionally includes additional details such as phone number, location, web profiles, tags, education, experience, and source details. The response returns the created candidate's details, including their ID, name, contact information, location, web profiles, education, experience, and job assignments. The API also handles various error responses for invalid source details, permission issues, and non-existent source types.
• PATCH https://api.smartrecruiters.com/jobs/{jobId}/headcount : The Update Job Headcount API allows users to update the headcount for a specific job identified by the jobId path parameter. The request must include a JSON body with the salaryRange object, specifying the minimum and maximum salary and the currency. The API responds with a 202 status indicating the request is pending, or with error messages and codes for invalid requests, such as invalid salary range, permission denied, or approval process not enabled.
• GET https://api.smartrecruiters.com/jobs/{jobId}/hiring-team : This API endpoint retrieves the hiring team for a specific job identified by the jobId. The request is made using the GET method to the URL https://api.smartrecruiters.com/jobs/{jobId}/hiring-team. The request can include an optional 'Accept-Language' header to specify the language of the returned content. The response includes a list of team members with their roles and actions. If the job access is denied, a 401 error is returned with a message and error details.
• DELETE https://api.smartrecruiters.com/jobs/{jobId}/hiring-team/{userId} : This API endpoint is used to remove a member from the hiring team of a specified job. The request requires the job ID and user ID as path parameters. The request header must include 'accept: application/json'. If successful, the response will be a 204 No Content status. If there are errors, such as attempting to remove the last member of a hiring team, lacking job access, or the user not being a member of the hiring team, the response will include error messages with appropriate status codes (400, 401, 404).
• POST https://api.smartrecruiters.com/jobs/{jobId}/jobads : This API endpoint allows the creation of a job advertisement for a specific job identified by the jobId path parameter. The request must include a JSON body with the job ad details, including the title, language, location, and job ad content such as company description, job description, qualifications, additional information, and optional videos. The response returns the created job ad details, including its ID, title, language, location, job ad content, creation and update timestamps, apply URL, posting status, default status, actions, creator, and visibility. The API supports multiple languages and locales, and the location can be specified as remote.
• PUT https://api.smartrecruiters.com/jobs/{jobId}/jobads/{jobAdId} : This API endpoint allows you to update an existing job ad by sending a PUT request to the specified URL with the jobId and jobAdId as path parameters. The request must include headers for 'accept' and 'content-type' set to 'application/json'. The request body should contain the job ad details including the title, language, location, and job ad descriptions. The response will return the updated job ad details including the id, title, language, location, job ad descriptions, creation and update timestamps, posting status, and visibility. Note that changes will only be reflected on internal sources and job aggregators after publishing the job ad.
• DELETE https://api.smartrecruiters.com/jobs/{jobId}/jobads/{jobAdId}/postings : This API endpoint is used to unpublish a job ad from all sources. It requires the job identifier (jobId) and the job ad identifier (jobAdId) as path parameters. The request does not require a body or query parameters. The response can be a 202 status indicating the unposting is pending, a 401 status if the user is not authorized, or a 404 status if the job ad is not found. The response body for a 202 status includes the unposting status, while 401 and 404 responses include error messages and codes.
• GET https://api.smartrecruiters.com/jobs/{jobId}/note : The Get Job Note API retrieves a note associated with a specific job identified by the jobId path parameter. The request can include an optional Accept-Language header to specify the language of the returned content. The response will include the note content if successful (HTTP 200), or an error message if the job access is forbidden (HTTP 401) or the job note is not found (HTTP 404).
• POST https://api.smartrecruiters.com/jobs/{jobId}/positions : This API endpoint allows the creation of a new job position for a specified job ID. The request requires a path parameter 'jobId' which is the identifier for the job. The request body must include 'type', 'positionOpenDate', and 'targetStartDate' as required fields. The 'type' field can be either 'NEW' or 'REPLACEMENT'. Upon successful creation, the API returns a 201 status code with details of the created position including 'id', 'positionId', 'type', 'incumbentName', 'positionOpenDate', 'targetStartDate', 'createdOn', and 'status'. If the request is forbidden, a 403 status code is returned with error details.
• GET https://api.smartrecruiters.com/jobs/{jobId}/positions/{positionId} : This API endpoint retrieves the details of a specific job position using the job ID and position ID. It requires the 'Accept-Language' header to specify the language of the returned content, which defaults to 'en'. The response includes details such as the position ID, type, incumbent name, position open date, target start date, creation date, and status. If the job access is forbidden, a 403 error is returned with a message and error details. If the position is not found, a 404 error is returned with a message and error details.
• DELETE https://api.smartrecruiters.com/jobs/{jobId}/publication : This API endpoint unpublishes a job from all sources. It requires the job identifier as a path parameter. The request must include an 'accept' header with the value 'application/json'. The API does not require a request body. On success, it returns a 204 status code with no content. If the user is not authorized to access the job, it returns a 401 status code with an error message and error code 'UNAUTHORIZED_TO_ACCESS_JOB'.
• PUT https://api.smartrecruiters.com/jobs/{jobId}/status : The Update Job Status API allows users to update the status of a job identified by the jobId path parameter. The request requires a JSON body with a 'status' field, which can be one of the following values: CREATED, SOURCING, FILLED, INTERVIEW, OFFER, CANCELLED, or ON_HOLD. The API returns a 201 status code with the updated status if successful. If the job access is forbidden, a 403 status code is returned with an error message. If the job is not found, a 404 status code is returned with an error message.
• GET https://api.smartrecruiters.com/jobs/{jobId}/status/history : The Get Job Status History API retrieves the history of status changes for a specific job identified by the jobId path parameter. The API supports an optional Accept-Language header to specify the language of the returned content. The response includes a totalFound field indicating the number of status changes and a content array with details of each status change, including the changedOn date, status, and any user actions. If access is forbidden, a 401 response is returned with an error message and code.

Interviews API

• PATCH https://api.smartrecruiters.com/interviews-api/v201904/interview-types : The Update Interview Types API allows users to update the list of interview types by sending a PATCH request to the specified endpoint. The request must include headers specifying 'accept' and 'content-type' as 'application/json'. The body of the request should be an array of strings representing the interview types to be added, with a minimum of 1 and a maximum of 2000 items. Each string can have a maximum length of 400 characters. The API responds with a 204 status code if successful, or error codes such as 403 if forbidden, 409 if the maximum size is exceeded, 422 for input validation failures, and 500 for unexpected errors. The response body for errors includes an array of error objects with 'code' and 'message' fields.
• DELETE https://api.smartrecruiters.com/interviews-api/v201904/interview-types/{interviewType} : The Delete Interview Type API allows users to delete a specific interview type by providing the interview type name as a path parameter. The request requires the 'interviewType' path parameter, which is a string with a maximum length of 400 characters. The API responds with a 204 status code if the interview type is successfully deleted. If the user is forbidden to delete the interview type, a 403 status code is returned with an error message. If the interview type is not found, a 404 status code is returned with an error message. In case of an unexpected error, a 500 status code is returned.
• GET https://api.smartrecruiters.com/interviews-api/v201904/interviews : This API endpoint retrieves a list of interviews associated with a specific application ID. The request requires the 'applicationId' as a query parameter, which is a GUID representing the application. The response includes details about each interview, such as the candidate's ID, job ID, location, organizer ID, timezone, and timeslots. Each timeslot contains information about the interview type, title, place, start and end times, interviewers, candidate status, and no-show status. The response also includes metadata like creation time, reference URL, and source. The API returns a 403 error if access is forbidden, a 404 error if the application is not found, and a 500 error for unexpected issues.
• DELETE https://api.smartrecruiters.com/interviews-api/v201904/interviews/{interviewId} : The Delete Interview API allows users to delete an interview by providing the interview ID in the path parameters. The request requires the 'interviewId' as a path parameter, which is a GUID string representing the ID of the interview to be deleted. The API responds with a 204 status code if the interview is successfully deleted. If the user is forbidden from deleting the interview, a 403 status code is returned with an error message. If the interview is not found, a 404 status code is returned with an error message indicating 'INTERVIEW_NOT_FOUND'. A 500 status code indicates an unexpected error.
• POST https://api.smartrecruiters.com/interviews-api/v201904/interviews/{interviewId}/timeslots : This API endpoint allows the creation of a new timeslot for a specified interview. The request requires the interview ID as a path parameter and a JSON body containing details about the timeslot, including start and end times, interviewers, and optional fields like interview type, title, and place. The response returns the created timeslot details, including its ID and status. Possible error responses include forbidden access, interview not found, maximum timeslots reached, and validation errors.
• GET https://api.smartrecruiters.com/interviews-api/v201904/interviews/{interviewId}/timeslots/{timeslotId} : This API endpoint retrieves the details of a specific interview timeslot. It requires the interview ID and timeslot ID as path parameters. The response includes details such as the interview type, title, place, start and end times, interviewers, candidate status, and no-show status. If access is forbidden, a 403 error with error details is returned. If the interview or timeslot is not found, a 404 error is returned. A 500 error indicates an unexpected error.
• PUT https://api.smartrecruiters.com/interviews-api/v201904/interviews/{interviewId}/timeslots/{timeslotId}/candidateStatus : This API updates the candidate's status for a specific interview timeslot. It requires the interview ID and timeslot ID as path parameters. The request body must include the new status of the candidate, which can be 'accepted', 'declined', 'pending', or 'tentative'. The API returns a 204 status code if the update is successful. If the user is forbidden to change the status, a 403 error with a detailed message is returned. Other possible error responses include 404 for not found errors and 422 for input validation failures.
• PUT https://api.smartrecruiters.com/interviews-api/v201904/interviews/{interviewId}/timeslots/{timeslotId}/interviewers/{userId}/status : This API endpoint updates the status of an interviewer for a specific timeslot in an interview. It requires the interview ID, timeslot ID, and user ID as path parameters. The request body must include the new status of the interviewer, which can be 'accepted', 'declined', 'pending', or 'tentative'. The API returns a 204 status code if the status is successfully changed. If the user is forbidden to change the status, a 403 error is returned with details. Other possible errors include 404 for not found resources and 422 for input validation failures.
• PATCH https://api.smartrecruiters.com/interviews-api/v201904/interviews/{interviewId}/timeslots/{timeslotId}/noshow : This API endpoint allows updating the no-show status for a specific interview timeslot. It requires the interview ID and timeslot ID as path parameters, and a boolean value as a query parameter to set the new no-show status. The request must include an 'accept' header with 'application/json'. A successful update returns a 204 status code. If the user is forbidden to change the no-show value, a 403 status code is returned with error details. A 404 status code indicates that the interview or timeslot was not found, and a 500 status code indicates an unexpected error.

Messages API

• GET https://api.smartrecruiters.com/messages : This API endpoint allows users with ADMINISTRATOR role to search for messages related to a specific candidate. The messages can be filtered by job application using the jobId parameter. The API requires the candidateId as a mandatory query parameter, while jobId, pageId, and limit are optional. The response includes an array of messages with details such as content, creation date, visibility, author ID, and context. The response headers may include a Link header for pagination. Possible error responses include 403 for permission issues and 400 for not found errors.
• POST https://api.smartrecruiters.com/messages/shares : This API endpoint allows users to share messages with specific users, hiring teams, or everyone in a company. The request body requires a 'content' field for the message text, and optional fields such as 'correlationId' for additional ID reference, and 'shareWith' for specifying visibility options. The 'shareWith' object can include 'users' (an array of user IDs), 'hiringTeamOf' (an array of job IDs), 'everyone' (a boolean to share with all company members), and 'openNote' (a boolean to share with those having access to tagged candidates). The response returns a 201 status with an 'id' and 'shareRequired' flag if successful, or a 400 status with error codes for various issues such as invalid visibility options or non-existent users.
• DELETE https://api.smartrecruiters.com/messages/shares/{id} : This API endpoint allows the deletion of a message by its ID. The DELETE method is used to remove a message from the system, making it no longer visible on Hireloop. The request requires the 'id' path parameter, which is the identifier of the message to be deleted. The response can be a 204 status code indicating successful deletion, a 403 status code indicating no permission to delete the message, or a 404 status code indicating that the message was not found. The 403 and 404 responses include a JSON body with a message and an array of errors, each containing a code and a message.

Offers API

• GET https://api.smartrecruiters.com/offers : The Get Offers from SmartRecruiters API retrieves a list of job offers based on specified query parameters. The API supports filtering by the number of results to return (limit), the number of results to skip (offset), creation time boundaries (createdAfter and createdBefore), offer age (age), and offer status (status). The response includes the total number of offers found and a list of offer details, including ID, status, creation and update timestamps, and associated actions. If access is denied, a 403 error with a message and error code is returned.

FAQs

1. What do most teams integrate SmartRecruiters with?
   Usually HRIS (Workday, SAP SuccessFactors), background verification, assessments, calendars, and internal data warehouses/BI.
2. Is the API enough to run full recruitment operations externally?
   It depends on scope and permissions, but the endpoints cover a lot: jobs, candidates, interviews, offers, approvals, and configuration. For complex org processes, you’ll still align on governance and access controls.
3. How do you keep candidate status and stage consistent across systems?
   Use the candidate job status endpoints (update + history) as your single source of truth for pipeline movement, then sync downstream to CRM/analytics.
4. What’s the cleanest way to onboard an assessment partner integration?
   Start with company integration setup and partner configuration, then wire in order retrieval and results update/attachments for an end-to-end loop.
5. How do you handle approvals for offers or job changes?
   Use the Approvals API to create and track approval requests, plus approve/reject decision endpoints to close the loop programmatically.
6. Can you pull audit logs for compliance reviews?
   Yes—Audit API supports filtering and pagination and retains events for at least 26 months, which is typically what audit teams care about.
7. What’s the biggest integration pitfall teams hit?
   Treating the integration like a one-time project. Real success means ongoing monitoring for permissions, payload changes, rate limits, and process drift (especially around statuses, sources, and custom properties).

Get started with Knit

If you want quick and seamless access to SmartRecruiters ATS API, Knit API offers a straightforward path. Integrate once, and Knit handles authentication, authorization, and the ongoing integration maintenance, so your team stays focused on building workflows.

‍