Access Scopes

Overview

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: Not passing a list of scopes with the authorization call with use default scopes you have defined when registering your App.

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:

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 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:

20352035

List of available Access Scopes

Scope

Access Permissions Sought

Prompt Shown to User

candidates_read

Read access to user’s candidates 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 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 candidate’s status, onboarding status, tags, source and properties

Manage Candidate Status and Properties

candidate_status_read

Read access to candidate’s status history.

Access Candidate’s status

job_applications_read

Read access to job applications

Access 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 user’s jobs list and details.

Access Jobs

jobs_manage

Write access to user’s jobs, its hiring team and notes.

Manage jobs

jobs_publications_manage

Write / delete access to 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

analytics_read

Read access to analytics data.

Access Analytics

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 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 specific subscription.

View webhook subscriptions.

webhooks_write

Create new webhook subscriptions.

Create 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 job and offer approvals

Access job and offer approval requests

approvals_create

Write access to job and offer approvals

Create new job and offer approval requests

assessment_orders_read

Read access to assessment orders

Access Assessment Orders


Did this page help you?