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
| 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. (NOTE: Requires an Admin user role or the "Manage Webhook" feature enabled in the Permissions settings for a custom role.) | View webhook subscriptions. |
| webhooks_write | Create new webhook subscriptions. (NOTE: Requires an Admin user role or the "Manage Webhook" feature enabled in the Permissions settings for a custom role.) | Create a new webhook subscription. |
| webhooks_delete | Delete webhook subscriptions. (NOTE: Requires an Admin user role or the "Manage Webhook" feature enabled in the Permissions settings for a custom role.) | Delete webhook subscription. |
| webhooks_manage | Create, read, and delete webhook subscriptions. (NOTE: Requires an Admin user role or the "Manage Webhook" feature enabled in the Permissions settings for a custom role.) | 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 |
| self_schedules_read | Read access to interview self schedules | Read access to self schedules |
| self_schedules_manage | Write access to interview self schedules (create/update/cancel self schedules) | Write access to self schedules |
| candidate_applications_manage | Create candidates and read applications' status on behalf of candidates | Create application and read application status on behalf of a candidates |
Updated 4 days ago