Access Scopes


Most of the Customer API endpoints require prior authorization by your app’s user. To get that authorization, your application will first need to make a call to the SmartRecruiters dedicated endpoint (see OAuth 2.0 page for details), passing along a list of the scopes for which access permission is sought.

How many scopes should I request?

Scopes let you specify exactly what types of data your app wants to access, and the set of scopes you pass in your call determines what access permissions the user is asked to grant.

Note: If the list of scopes is missed in the authorization call, then the default scopes will be used. They are defined during your App registration process.

You should only request the scope you need at the time of authorization. If in the future you require additional scope, you may forward the user to the authorization URL with that additional scope to be granted. If you attempt to perform a request with an access token that is not authorized for that scope, you will receive an OAuthPermissionsException error return.

Separating multiple scopes

To request multiple scopes at once, simply separate the scopes by a space. In the url, this equates to an escaped space (“%20”). So if you are requesting candidate read and write permission, the parameter will look like this:


Note that an empty scope parameter (scope=) is invalid; you must either omit the scope, or specify a non-empty scope list.

Example confirmation page

Take a look at example Java and Node.js Apps to find out how to use the scopes and how to implement the OAuth 2.0 flow.

On execution of the authorization request call, user is redirected to a page explaining what information has been requested by an App:


List of available Access Scopes

ScopeAccess Permissions SoughtPrompt Shown to User
candidates_readRead access to user’s candidates list, details, tags, onboarding status, properties, attachments, screening answers and status history.Access Candidates
candidates_createAdd new candidate records on behalf of a user and assign to a General Application or to a Job by uploading a resume or by passing a JSON object. Add attachments.Create Candidates
candidates_offers_readRead access to candidates’ offers and get offer terms.Access Offer Terms
candidates_manageWrite access to candidate’s status, onboarding status, tags, source and propertiesManage Candidate Status and Properties
candidate_status_readRead access to candidate’s status history.Access Candidate’s status
job_applications_readRead access to job applicationsAccess job applications
configuration_readRead access to all company configuration settings for departments, hiring processes, job properties and offer properties. (NOTE: Requires an Admin user role)Access Company Settings
configuration_manageWrite / delete access to all company configuration settings for departments and job properties. (NOTE: Requires an Admin user role)Manage Company Settings
jobs_readRead access to user’s jobs list and details.Access Jobs
jobs_manageWrite access to user’s jobs, its hiring team and notes.Manage jobs
jobs_publications_manageWrite / delete access to user’s jobs publications.Publish Jobs
users_readRead access to users in a company. (NOTE: Requires an Admin user role)Access Users
user_me_readRead access to current user.Access information about my user
users_manageWrite / delete access to users in a company. (NOTE: Requires an Admin user role)Manage Users
messages_writeCreate messages to other users.Message Users
messages_manageDelete access to messages.Manage Messages
messages_readAccess candidate messages.Access messages
analytics_readRead access to analytics data.Access Analytics
company_readGet company information.Access Company Information
audit_events_readRead access to audit events.Access Audit Events
reporting_readGet analytics reports and download report files.Get analytics reports and download report files
reporting_writeManage/execute analytics reports.Manage/execute analytics reports.
interview_types_readRead list of interview types.Access Interview Types.
interview_types_writeWrite or delete access to manage interview types.Create and delete Interview Types.
interviews_writeCreate, update or delete interviews.Create, update and delete Interviews and Timeslots.
interviews_readRead interviews.Access Interviews and Timeslots.
webhooks_readRead user’s webhook subscriptions and get details of specific subscription.View webhook subscriptions.
webhooks_writeCreate new webhook subscriptions.Create new webhook subscription.
webhooks_deleteDelete webhook subscriptions.Delete webhook subscription.
webhooks_manageCreate, read and delete webhook subscriptionsView, create and delete webhook subscriptions.
reviews_readRead access to reviewsAccess Reviews
reviews_writeWrite access to reviewsCreate, update and delete reviews
approvals_readRead access to job and offer approvalsAccess job and offer approval requests
approvals_createWrite access to job and offer approvalsCreate new job and offer approval requests
assessment_orders_readRead access to assessment ordersAccess Assessment Orders