Access Scopes

Overview

Most 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, 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 an 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:

scope=candidates_read%20candidates_create

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 our Demo app to find out how to use the scopes and how to implement the OAuth 2.0 flow.

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

List of available Access Scopes

ScopeAccess Permissions SoughtPrompt Shown to User
candidates_readRead access to the user’s candidate 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 them 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 the candidate’s status, onboarding status, tags, source, and propertiesManage Candidate Status and Properties
candidate_status_readRead access to the candidate’s status history.Access Candidate’s status
job_applications_readRead access to job applicationsAccess job applications
job_applications_manageWrite / delete access to job applicationsManage 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 the user’s jobs list and details.Access Jobs
jobs_manageWrite access to user’s jobs, their hiring team, and notes.Manage jobs
jobs_publications_manageWrite/delete access to the 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
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 the 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 a specific subscription.View webhook subscriptions.
webhooks_writeCreate new webhook subscriptions.Create a 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 the job and offer approvalsAccess job and offer approval requests
approvals_createWrite access to the job and offer approvalsCreate a new job and offer approval requests
assessment_orders_readRead access to assessment ordersAccess Assessment Orders
event_management_readRead access to the company scheduling events and session dataRead access to event management
event_management_writeWrite access to the company scheduling events and session data (create events, add/remove interviewers from sessions, cancel event/session, ect.)Write access to events and sessions