In OAuth flows, your application needs to exchange either a client credential or an authorization code for an access token before calling a SmartRecruiters endpoint. Each access token is tied to a defined scope which describes the resource permission your application is seeking from the resource owner.

In many cases, the resource owner needs to review the scopes via a SmartRecruiter page or a dialog box to grant access to your application.

Below is the list of access scopes and description of each scope:

Scope	Description	Prompt Displayed to User
`approvals_create`	Write access to create job approval requests and offer approval requests	Create new job approval and offer approval requests
`approvals_read`	Read access to job approval requests and offer approval requests	Access job approval and offer approval requests
`audit_events_read`	Read access to audit events	Access audit events
`candidates_create`	Write access to add new candidate records by assigning the candidate to a job or general application. Write access to add attachment to a candidate	Create candidates
`candidates_read`	Read access to candidates list, candidate details, tags, onboarding status, properties, attachments, screening question answers and status history	Access candidates
`candidates_manage`	Write access to edit a candidate's status, onboarding status, tags, source and candidate properties	Manage candidate status and properties
`candidates_offers_read`	Read access to candidates' offers and offer terms	Access candidate offer terms
`candidates_status_read`	Read access to candidates' status history	Access candidate status
`company_read`	Read access to company information	Access company information
`configuration_read`	Read access to all company settings including departments, hiring processes, job properties and offer properties	Access company settings
`configuration_manage`	Write access to all company settings including departments, hiring process, job properties and offer properties	Manage company settings
`interviews_write`	Write access to create, update and delete interviews	Create, update and delete interviews and timeslots
`interviews_read`	Read access to interviews	Access interviews and timeslots
`interview_types_write`	Write access to create and delete interview types	Create and delete interview types
`interview_types_read`	Read access to interview types	Access interview types
`jobs_manage`	Write access to jobs, hiring team and notes	Create and manage jobs
`jobs_read`	Read access to jobs and detail	Access jobs
`job_publications_manage`	Write access to create and delete job publications	Publish and unpublish jobs
`messages_write`	Create messages to users in SmartRecruiters	Message users
`messages_manage`	Delete messages that were sent to users in SmartRecruiters	Manage messages
`messages_read`	Read access to messages	Access messages
`reporting_read`	Read access to ReportBuilder's reports and report files	Access analytics reports and download report files
`reporting_write`	Manage/execute analytics reports	Manage/execute analytics reports
`reviews_write`	Write access to create reviews on applications	Create, update and delete reviews
`reviews_read`	Read access to reviews on applications	Access reviews
`users_manage`	Write access to create, update and delete users of the company	Manage users
`users_read`	Read access to retrieve users of the company	Access users
`user_me_read`	Read access to user information of which the API credential is associated to	Access my user
`webhooks_write`	Create new webhook subscriptions	Create webhook subscriptions
`webhooks_delete`	Delete webhook subscriptions	Delete webhook subscriptions
`webhooks_read`	Read only access to retrieve webhook subscriptions	View webhook subscriptions
`webhook_manage`	Read and write access to create, delete and retrieve webhook subscriptions	Create, delete and view webhook subscriptions

Permission Reference

The following sections list and describe SmartAPI resources, their endpoints and the OAuth scopes needed to access them:

Approvals

The Approval API lets developers to create and to retrieve approval requests for publishing jobs and for sending out offers to candidates.

Endpoint	Scope Required
ListUserApprovals	`approvals_read`
CreateApproval	`approvals_create`
RetrieveApproval	`approvals_read`

Assessments

The Assessment API lets developers to retrieve assessment results and attachments of applications

Endpoint	Scope Required
RetrieveAssessmentResult	`assessment_orders_read`

Audits

The Audit API lets developers retrieve event logs that captured actions performed by both end users and system users.

Endpoint	Scope Required
ListAuditEvents	`audit_events_read`

Candidates

The Candidate API lets developers create, manage and retrieve information on candidates and candidate applications.

Endpoint	Scope Required
ListCandidates	`candidates_read`
CreateCandidate	`candidates_create`
CreateCandidateFromResume	`candidates_create`
RetrieveCandidate	`candidates_read`
UpdateCandidate	`candidate_manage`
DeleteCandidate	`candidates_manage`
ListCandidateConsents	`candidates_read`
ListCandidateSingleConsent	`candidates_read`
CreateCandidateConsents	`candidates_create`
CreateCandidateTags	`candidates_manage`
UpdateCandidateTags	`candidates_manage`
DeleteCandidateTags	`candidates_manage`
ListCandidateTags	`candidates_manage`
RetrieveCandidateAttachment	`candidates_read`
DeleteCandidateAttachment	`candidates_create`
CreateApplicationToJob	`candidates_create`
CreateApplicationFromJobPosting	`candidates_create`
CreateApplicationFromResume	`candidates_create`
RetrieveApplication	`candidates_read`
RetrieveApplicationStatus	`candidates_read` `candidates_manage`
UpdateApplicationStatus	`candidates_create`
ListApplicationAttachments	`candidates_read`
ListApplicationStatusLog	`candidates_read`
CreateApplicationAttachment	`candidates_create`
ListApplicationAttachment	`candidates_read`
RetrieveApplicationOnboardingStatus	`candidates_status_read` `candidates_read`
UpdateApplicationOnboardingStatus	`candidates_manage`
UpdateApplicationSource	`candidates_manage`
UpdateApplicationPropertyValue	`candidates_manage`
ListApplicationProperties	`candidates_read`
ListApplicationScreeningQuestionAnswers	`candidates_read`

Configuration

The Configuration API lets developers retrieve and manage the company's configuration such as custom job fields, candidate fields and hiring processes.

Endpoint	Scope Required
ListCompanyCandidateProperties	`configuration_read`
RetrieveCompanyCandidateProperty	`configuration_read`
ListCompanyCandidatePropertyValues	`configuration_read`
CreateCompanyCandidatePropertyValue	`configuration_manage`
RetrieveCompanyCandidatePropertyValue	`configuration_read`
UpdateCompanyCandidatePropertyValue	`configuration_manage`
RetrieveCompany	`company_read`
ListDepartments	`configuration_read`
CreateDepartment	`configuration_manage`
RetrieveDepartment	`configuration_read`
ListHiringProcesses	`configuration_read`
RetrieveHiringProcess	`configuration_read`
ListCompanyJobProperties	`configuration_read`
CreateCompanyJobProperty	`configuration_manage`
RetrieveCompanyJobProperty	`configuration_read`
UpdateCompanyJobProperty	`configuration_manage`
ActivateCompanyJobProperty	`configuration_manage`
DeleteCompanyJobProperty	`configuration_manage`
ArchiveCompanyJobProperty	`configuration_manage`
UnarchiveCompanyJobProperty	`configuration_manage`
ListCompanyJobPropertyValues	`configuration_read`
CreateCompanyJobPropertyValue	`configuration_manage`
UpdateCompanyJobPropertyValue	`configuration_manage`
ListCompanyJobPropertyValueDependentValues	`configuration_read`
CreateCompanyJobPropertyValueDependentValue	`configuration_manage`
DeleteCompanyJobPropertyValueDependentValue	`configuration_manage`
UpdateCompanyJobPropertyValueTranslation	`configuration_manage`
ListCompanyJobPropertyDependents	`configuration_read`
CreateCompanyJobPropertyDependent	`configuration_manage`
DeleteCompanyJobPropertyDependent	`configuration_manage`
ListCompanyJobPropertyDependentValues	`configuration_read`
ListCompanyOfferProperties	`configuration_read`
ListCompanyRejectionReasons	`configuration_read`
ListCompanyRejectionReasons	`configuration_read`
ListCompanyCandidateSourceType	`configuration_read`
ListCompanyCandidateSources	`configuration_read`
RetrieveCompanyCandidateSource	`configuration_read`

Interviews

The Interview API lets developers create and manage interviews and retrieve information of interviews (created by the Interview API) of candidates.

Endpoint	Scope Required
ListInterviewTypes	`interview_types_read`
CreateInterviewType	`interview_types_write`
DeleteInterviewType	`interview_types_write`
CreateInterview	`interviews_write`
RetrieveInterview	`interviews_read`
UpdateInterview	`interviews_write`
DeleteInterview	`interviews_write`
UpdateInterviewCandidateStatus	`interviews_write`
UpdateInterviewInterviewerTimeslotStatus	`interviews_write`
CreateInterviewTimeslot	`interviews_write`
RetrieveInterviewTimeslot	`interviews_read`
UpdateInterviewTimeslot	`interviews_write`
DeleteInterviewTimeslot	`interviews_write`

Jobs

The Job API lets developers create, manage and retrieve information on jobs.

Endpoint	Scope Required
ListJobs	`jobs_read`
CreateJob	`jobs_manage`
RetrieveJob	`jobs_read`
UpdateJob	`jobs_manage`
UpdateJobHeadcount	`jobs_manage`
RetrieveJobHiringteam	`jobs_read`
UpdateJobHiringteam	`jobs_manage`
DeleteJobHiringteamMember	`jobs_manage`
ListJobAds	`jobs_read`
CreateJobAds	`jobs_manage`
RetrieveJobAd	`jobs_read`
UpdateJobAd	`jobs_manage`
ListJobAdPostings	`job_publications_manage`
CreateJobAdPosting	`job_publications_manage`
DeleteJobAdPosting	`job_publications_manage`
RetrieveJobNote	`jobs_read`
UpdateJobNote	`jobs_manage`
ListJobPositions	`jobs_read`
CreateJobPosition	`jobs_manage`
RetrieveJobPosition	`jobs_read`
UpdateJobPosition	`jobs_manage`
DeleteJobPosition	`jobs_manage`
ListJobPublications	`jobs_read`
CreateJobPublication	`jobs_manage`
DeleteJobPublication	`jobs_manage`
UpdateJobStatus	`jobs_manage`
ListJobStatusHistory	`jobs_read`

Messages

The Message API lets developers retrieve and manages messages to users.

Endpoint	Scope Required
ListMessages	`messages_read`
CreateMessage	`messages_write`
DeleteMessage	`messages_manage`

Offers

The Offer API lets developer retrieve offers for candidates.

Endpoint	Scope Required
ListOffers	`candidates_offers_read`
ListCandidateOffers	`candidates_offers_read`
RetrieveCandidateOffer	`candidates_offers_read`

Postings

🚧
Postings Resource Access Scopes
Postings endpoints are one of the oldest endpoints SmartRecruiters have and these endpoints currently do not support the use of OAuth 2.0.
We are planning to provide a new version of these endpoints that supports OAuth 2.0. In the mean time, please use API Key instead if you are working with the Postings resources.

Reports

The Report API lets developers schedule single or periodic download of ReportBuilder's reports and report files.

Endpoint	Scope Required
ListReports	`reporting_read`
RetrieveReport	`reporting_read`
ListReportFiles	`reporting_read`
CreateReportFile	`reporting_read`
RetrieveReportFile	`reporting_read`
RetrieveReportFileData	`reporting_read`
ListRecentReportFiles	`reporting_read`
RetrieveRecentReportFilesData	`reporting_read`

Reviews

The Review API lets developers retrieve, create and update reviews of candidate applications.

Endpoint	Scope Required
ListReviews	`reviews_read`
CreateReview	`reviews_write`
RetrieveReview	`reviews_read`
UpdateReview	`reviews_write`
DeleteReview	`reviews_delete`

Users

The User API lets developers access and manage user information, status, roles and permissions.

Endpoint	Scope Required
ListUsers	`users_read`
CreateUser	`users_manage`
RetrieveUser	`users_read`
UpdateUser	`users_manage`
ActivateUser	`users_manage`
DeactivateUser	`users_manage`
CreateUserPassword	`users_manage`
UpdateUserPassword	`users_manage`
UpdateUserAvatar	`users_manage`
ListAccessGroups	`users_read`
UpdateAccessGroupUsers	`users_manage`
DeleteAccessGroupUser	`users_manage`
ListSystemRoles	`users_read`
RetrieveMyUser	`user_me_read`

Webhook Subscriptions

The Webhook Subscriptions API lets developers create and manage subscriptions for event notifications from the SmartRecruiters Public API service.

Endpoint	Required Scope
ListWehbookSubscriptions	`webhooks_read` `webhooks_manage`
CreateWebhookSubscription	`webhooks_write` `webhooks_manage`
RetrieveWebhookSubscription	`webhooks_read` `webhooks_manage`
DeleteWebhookSubscription	`webhooks_delete` `webhooks_manage`
ActivateWebhookSubscription	`webhooks_write` `webhooks_manage`
ListCallbacksLog	`webhooks_read` `webhooks_manage`
CreateWebhookSubscriptionSecretKey	`webhooks_write` `webhooks_manage`
RetrieveWebhookSubscriptionSecretKey	`webhooks_read` `webhooks_manage`

Permission Reference

Approvals

Assessments

Audits

Candidates

Configuration

Interviews

Jobs

Messages

Offers

Postings

🚧Postings Resource Access Scopes

Reports

Reviews

Users

Webhook Subscriptions

🚧
Postings Resource Access Scopes