Access Scopes

Define access permissions for OAuth

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

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

RetrieveCandidate

candidates_read

UpdateCandidate

candidate_manage

DeleteCandidate

candidates_manage

ListCandidateConsents

candidates_read

RetrieveCandidateApplication

candidates_read

ListCandidateApplicationAttachments

candidates_read

CreateCandidateApplicationAttachment

candidates_create

RetrieveCandidateApplicationOnboardingStatus

candidates_status_read
candidates_read

UpdateCandidateApplicationOnboardingStatus

candidates_manage

ListCandidateApplicationProperties

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

ListJobPoisitions

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


Did this page help you?