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

Scope	Access Permissions Sought	Prompt Shown to User
candidates_read	Read access to the user’s candidate list, details, tags, onboarding status, properties, attachments, screening answers, and status history.	Access Candidates
candidates_create	Add 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_read	Read access to candidates’ offers and get offer terms.	Access Offer Terms
candidates_manage	Write access to the candidate’s status, onboarding status, tags, source, and properties	Manage Candidate Status and Properties
candidate_status_read	Read access to the candidate’s status history.	Access Candidate’s status
job_applications_read	Read access to job applications	Access job applications
job_applications_manage	Write / delete access to job applications	Manage job applications
configuration_read	Read 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_manage	Write/delete access to all company configuration settings for departments and job properties. (NOTE: Requires an Admin user role)	Manage Company Settings
jobs_read	Read access to the user’s jobs list and details.	Access Jobs
jobs_manage	Write access to user’s jobs, their hiring team, and notes.	Manage jobs
jobs_publications_manage	Write/delete access to the user’s jobs publications.	Publish Jobs
users_read	Read access to users in a company. (NOTE: Requires an Admin user role)	Access Users
user_me_read	Read access to current user.	Access information about my user
users_manage	Write/delete access to users in a company. (NOTE: Requires an Admin user role)	Manage Users
messages_write	Create messages to other users.	Message Users
messages_manage	Delete access to messages.	Manage Messages
messages_read	Access candidate messages.	Access messages
company_read	Get company information.	Access Company Information
audit_events_read	Read access to audit events.	Access Audit Events
reporting_read	Get analytics reports and download report files.	Get analytics reports and download report files
reporting_write	Manage/execute analytics reports.	Manage/execute analytics reports.
interview_types_read	Read the list of interview types.	Access Interview Types.
interview_types_write	Write or delete access to manage interview types.	Create and delete Interview Types.
interviews_write	Create, update, or delete interviews.	Create, update, and delete Interviews and Timeslots.
interviews_read	Read interviews.	Access Interviews and Timeslots.
webhooks_read	Read user’s webhook subscriptions and get details of a specific subscription.	View webhook subscriptions.
webhooks_write	Create new webhook subscriptions.	Create a new webhook subscription.
webhooks_delete	Delete webhook subscriptions.	Delete webhook subscription.
webhooks_manage	Create, read, and delete webhook subscriptions	View, create and delete webhook subscriptions.
reviews_read	Read access to reviews	Access Reviews
reviews_write	Write access to reviews	Create, update, and delete reviews
approvals_read	Read access to the job and offer approvals	Access job and offer approval requests
approvals_create	Write access to the job and offer approvals	Create a new job and offer approval requests
assessment_orders_read	Read access to assessment orders	Access Assessment Orders
event_management_read	Read access to the company scheduling events and session data	Read access to event management
event_management_write	Write 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
message_templates_read	Read access to the company message templates	Read access to message templates
message_templates_write	Write access to the company message templates (create/update/delete templates)	Write access to message templates