--- updatedAt: 2026-07-30T06:46:35.000Z --- Fetch the complete documentation index at: https://apidocs.hibob.com/llms.txt. Use this file to discover all available pages before exploring further. # Scopes mapping to endpoints Learn how to work with scopes when integrating with ob **Partner OAuth integrations only** This reference is for **approved HiBob Marketplace partners** choosing OAuth scopes in the Developer Portal. Bob customers using Service Users should use [Permissions](/reference/permissions) instead. Every time you build an integration app, you need to decide what data and actions your app needs access to. In HiBob, we use OAuth scopes for that. Scopes limit an app’s access to data and functionality, and help customers understand exactly what your app can and cannot do in their Bob account. Once a customer authorizes your app, each scope determines which API endpoints your app can access. > 🚧 > > **Important**: > > * **Least privilege**: In the consent screen, the customer can accept or deny all requested scopes. Your app should request only the scopes that are absolutely necessary for your use case. > * **Changes**: If you change the scopes of an existing app, it may impact existing installations (for example, customers may need to re‑install). > * **Sensitive employee data scopes**: These scopes apply only to employee data, and they protect access based on the employee data category a field belongs to (for example, EEO or Financial). See [sensitive employee data scopes](#sensitive-employee-data-scopes). # Scopes mapping to endpoints
Scope name in Portal & Description Endpoints
**Docs > Manage documents**
Manage folders, requests, and eSign workflows `documents:write` 		`POST /v1/docs/people/{id}/confidential/upload` `POST /v1/docs/people/{employeeId}/custom/{folderId}` `DELETE /v1/docs/people/{id}/shared/{docId}` `DELETE /v1/docs/people/{id}/folders/{folderId}/{docId}` `POST /v1/docs/people/{employeeId}/confidential` `POST /v1/docs/people/{employeeId}/shared` `POST /v1/docs/people/{id}/shared/upload` `DELETE /v1/docs/people/{id}/confidential/{docId}` `POST /v1/docs/people/{id}/folders/{folderId}/upload`
**Docs > View documents and eSign**
View requests and eSign status reports `documents:read` 		`GET /v1/docs/people/{id}` `GET /v1/docs/folders/metadata`
**Goals > Manage goals**
Create, edit, and check in employee, team, and company goals `goals:write` 		`PATCH /v1/goals/goals/{goalId}/key-results/progress` `POST /v1/goals/goals/key-results/search` `PATCH /v1/goals/goals/{goalId}/status` `PATCH /v1/goals/goals/{goalId}/key-results` `DELETE /v1/goals/goals/{goalId}/key-results/{keyResultId}` `POST /v1/goals/goals` `POST /v1/goals/goals/{goalId}/key-results` `PATCH /v1/goals/goals/{goalId}` `POST /v1/goals/goals/search` `DELETE /v1/goals/goals/{goalId}` `POST /v1/goals/goal-types/search`
**Goals > View goals**
View personal, team, and company goals `goals:read` 		`POST /v1/goals/goal-cycles/search`
**Hiring > Manage job openings**
Search and read hiring data (job ads, openings, candidates, applications, interviews, evaluations, offers, and related sub-resources) `hiring:write` 		`POST /v1/hiring/job-ads/search` `GET /v1/hiring/job-ads/{id}` `POST /v1/hiring/job-openings/search` `POST /v1/hiring/candidates/search` `POST /v1/hiring/applications/search` `POST /v1/hiring/candidate-educations/search` `POST /v1/hiring/candidate-experiences/search` `POST /v1/hiring/candidate-languages/search` `POST /v1/hiring/candidate-skills/search` `POST /v1/hiring/candidate-volunteer-experiences/search` `POST /v1/hiring/candidate-professional-associations-memberships/search` `POST /v1/hiring/candidate-qualifications-licenses/search` `POST /v1/hiring/application-form-answers/search` `POST /v1/hiring/interviews/search` `POST /v1/hiring/evaluations/search` `POST /v1/hiring/evaluation-scorecard-templates/search` `POST /v1/hiring/offers/search`
**Job catalog > View job catalog**
View jobs and associated competencies `job_catalog:read` 		`GET /v1/job-catalog/job-family-groups/metadata` `POST /v1/job-catalog/job-profiles/search` `GET /v1/job-catalog/job-family-groups` `GET /v1/job-catalog/job-roles` `GET /v1/job-catalog/job-families/metadata` `GET /v1/job-catalog/job-profiles/metadata` `GET /v1/job-catalog/job-families` `GET /v1/job-catalog/job-roles/metadata`
**Integrations > Manage learning integrations**
Allows the application to manage learning integrations, including creating, updating, and deleting integrations, learning content, and progress tracking. `learning.integrations:write` 		`POST /v1/learning/lms-integrations` `DELETE /v1/learning/lms-integrations/{provider-identifier}` `POST /v1/learning/lms-integrations/{provider-identifier}/training-content` `PATCH /v1/learning/lms-integrations/{provider-identifier}/training-content` `PATCH /v1/learning/lms-integrations/{provider-identifier}/training-content/archive` `POST /v1/learning/lms-integrations/{provider-identifier}/xapi/statements`
**People > Manage company metadata**
Manage company lists and employee fields `company.metadata:write` 		`PUT /v1/company/named-lists/{listName}/{itemId}` `POST /v1/company/people/fields` `DELETE /v1/company/people/fields/{fieldId}` `DELETE /v1/company/named-lists/{listName}/{itemId}` `POST /v1/company/named-lists/{listName}` `PUT /v1/company/people/fields/{fieldId}`
**People > View employee data**
View employee profiles and org data `employee_data:read` 		`GET /v1/profiles` `GET /v1/people/custom-tables/{employeeId}/{tableId}` `GET /v1/people/{id}/training` `GET /v1/avatars/{id}` `POST /v1/people/{identifier}` `GET /v1/people/{id}/employment` `GET /v1/people/{id}/work` `GET /v1/avatars` `GET /v1/people/{id}/lifecycle` `POST /v1/people/search`
**People > Manage employee data**
Manage employee profiles and org data `employee_data:write` 		`PUT /v1/people/custom-tables/{employeeId}/{tableId}/{rowId}` `PUT /v1/avatars/{id}` `PUT /v1/people/{id}/employment/{rowId}` `POST /v1/people` `POST /v1/people/{id}/training` `DELETE /v1/people/custom-tables/{employeeId}/{tableId}/{rowId}` `PUT /v1/people/{id}/work/{rowId}` `DELETE /v1/people/{id}/work/{entry_id}` `POST /v1/employees/{id}/terminate` `POST /v1/employees/{id}/start-date` `DELETE /v1/people/{id}/employment/{entry_id}` `POST /v1/people/custom-tables/{employeeId}/{tableId}` `PUT /v1/people/{id}` `POST /v1/employees/{id}/uninvite` `POST /v1/people/{id}/work` `PUT /v1/people/{id}/email` `POST /v1/people/{id}/employment` `DELETE /v1/people/{id}/training/{rowId}` `POST /v1/employees/{id}/invitations`
**People > View employee historical data**
View history of profiles and org chart `employee_data.history:read` 		`GET /v1/bulk/people/employment` `GET /v1/bulk/people/lifecycle` `GET /v1/bulk/people/work`
**People > View sensitive employee data** View personal and sensitive employee data `employee_data.sensitive:read` See [sensitive employee data scopes](#sensitive-employee-data-scopes) `GET /v1/people/{employeeId}/bank-accounts` `GET /v1/people/{id}/variable` `GET /v1/people/{id}/equities`
**People > Manage sensitive employee data**
Manage personal and sensitive employee data `employee_data.sensitive:write` See [sensitive employee data scopes](#sensitive-employee-data-scopes) 		`DELETE /v1/people/{id}/variable/{rowId}` `PUT /v1/people/{id}/equities/{rowId}` `POST /v1/people/{id}/equities` `POST /v1/people/{id}/salaries` `PUT /v1/people/{employeeId}/bank-accounts/{rowId}` `DELETE /v1/people/{id}/equities/{rowId}` `DELETE /v1/people/{employeeId}/bank-accounts/{rowId}` `POST /v1/people/{employeeId}/bank-accounts` `DELETE /v1/people/{id}/salaries/{entry_id}` `POST /v1/people/{id}/variable`
**People > View employee sensitive historical data**
View history of profiles and org chart with sensitive data `employee_data.sensitive.history:read` See [sensitive employee data scopes](#sensitive-employee-data-scopes) 		`GET /v1/bulk/people/salaries` `GET /v1/payroll/history` `GET /v1/people/{id}/salaries` `POST /v1/people/actual-payments/search`
**Projects > Manage projects**
Create and manage projects `projects:write` 		`GET /v1/attendance/project-clients/metadata` `GET /v1/attendance/project-tasks/metadata` `PATCH /v1/attendance/projects/{projectId}` `POST /v1/attendance/project-tasks/search` `PATCH /v1/attendance/projects/{projectId}/archive` `GET /v1/attendance/projects/metadata` `POST /v1/attendance/project-clients/search` `POST /v1/attendance/projects` `PATCH /v1/attendance/projects/{projectId}/restore` `POST /v1/attendance/projects/search`
**Settings > View company metadata**
View company fields and wizards `company.metadata:read` 		`GET /v1/company/named-lists` `GET /v1/onboarding/wizards` `GET /v1/goals/goal-cycles/metadata` `GET /v1/people/custom-tables/metadata` `GET /v1/company/named-lists/{listName}` `GET /v1/company/people/fields` `GET /v1/goals/goals/metadata` `GET /v1/goals/goal-types/metadata` `GET /v1/goals/goals/key-results/metadata` `GET /v1/people/custom-tables/metadata/{tableId}`
**Reports > View reports**
Access reports `reports:read` 		`GET /v1/company/reports/download/{reportName}` `GET /v1/company/reports/{reportId}/download-async` `GET /v1/company/reports` `GET /v1/company/reports/{reportIdStr}/download`
**Tasks and flows > Manage tasks**
View and update employee task `tasks:write` 		`GET /v1/tasks/people/{id}` `GET /v1/tasks` `POST /v1/tasks/{taskId}/complete`
**Time attendance > Manage attendance sheets**
Manage attendance sheets and balances `attendance:write` 		`POST /v1/attendance/import/{method}` `POST /v1/attendance/summaries/search` `POST /v1/attendance/daily-breakdown/search` `POST /v1/attendance/entries/search` `POST /v1/attendance/entries` `PATCH /v1/attendance/employees/{employeeId}/entries` `POST /v1/attendance/employees/{employeeId}/entries/clock-in` `PATCH /v1/attendance/employees/{employeeId}/entries/clock-out` `DELETE /v1/attendance/entries/{entryId}`
**Time off > View time off**
View employee time off, balances, settings, and company calendar events (holidays/closures). `timeoff:read` 		`GET /v1/timeoff/employees/{employeeId}/requests/{requestId}`
`GET /v1/timeoff/requests/changes`
`GET /v1/timeoff/whosout`
`GET /v1/timeoff/outtoday`
**Time off > View employees on private time off**
View employees who are out but are on private policies

`timeoff.sensitive:read` 		**Optional - only to fetch private data:**
`GET /v1/timeoff/requests/changes`
`GET /v1/timeoff/whosout`
`GET /v1/timeoff/outtoday`
`GET /v1/timeoff/employees/{employeeId}/requests/{requestId}`

**Required:**
`GET /v1/timeoff/policies`
`GET /v1/timeoff/policies/names`
`GET /v1/timeoff/employees/{employeeId}/balance`
`GET /v1/timeoff/policy-types/{policyType}/reason-codes`
`GET /v1/timeoff/policy-types/{policyType}`
`GET /v1/timeoff/policy-types`
**Time off > Manage time off**
Manage employee time off balances and requests `timeoff:write` 		`POST /v1/timeoff/employees/{employeeId}/adjustments`
`POST /v1/timeoff/employees/{employeeId}/requests`
`POST /v1/timeoff/policy-types/{policyType}/reason-codes`
`DELETE /v1/timeoff/employees/{id}/requests/{requestId}`
**Time off > Manage calendar events**
Fetch company calendar events (holidays/closures). `timeoff:write` 		`POST /v1/timeoff/calendars/events/search`
**Workforce planning > View workforce planning**
View positions, hierarchy, and budget data `workforce_planning:read` 		`GET /v1/metadata/objects/position`
**Workforce planning > Manage workforce planning**
Manage positions, budgets, events, and hiring plans `workforce_planning:write` 		`POST /v1/workforce-planning/positions/{positionId}/position-openings` `POST /v1/positions/position-openings/search` `GET /v1/positions/position-budget/metadata` `POST /v1/positions/schedule-cancellation` `PATCH /v1/workforce-planning/positions/{positionId}/position-budget/{positionBudgetId}` `POST /v1/positions/position-budget/search` `POST /v1/workforce-planning/positions/{positionId}/position-budget` `POST /v1/workforce-planning/positions/schedule-cancellation` `DELETE /v1/workforce-planning/positions/{positionId}/position-openings/{positionOpeningId}` `GET /v1/positions/position-openings/metadata` `PATCH /v1/workforce-planning/positions/{positionId}/cancel` `PATCH /v1/workforce-planning/positions/{positionId}` `PATCH /v1/workforce-planning/positions/{positionId}/position-openings/{positionOpeningId}` `POST /v1/workforce-planning/positions` `POST /v1/objects/position/search`
**Payroll Hub > Payroll Hub Sync Status - Write**
Allows the partner to fetch employee data and perform syncs. `payrollhub.employee_sync:write` 		`GET /v1/payroll/hub/sync-requests/{syncRequestId}/sync-records` `PUT /v1/payroll/hub/sync-requests/{syncRequestId}/sync-records`
**Payroll Hub > Payroll Hub Data - Read**
Allows the partner to fetch pay cycle metadata, paystub information, and payroll-related employee data. `payrollhub.payroll:read` 		N/A
**Payroll Hub > Payroll Hub 401(k) Deductions & Loans - Write**
Allows the partner to fetch and update employee-level 401(k) deductions. `payrollhub.deductions:write` 		N/A
# Sensitive employee data scopes Sensitive employee data scopes are OAuth scopes intended for apps that need access to **sensitive employee data** in Bob. These scopes apply **only** to employee data, and they protect access based on the **employee data category** a field belongs to (for example, EEO or Financial). **When to use them** * Request a sensitive scope if your app needs to read or manage fields that are in the sensitive categories listed below. * If your app doesn’t need sensitive categories, don’t request a sensitive scope (customers will see it in the consent screen). **What to pay attention to** * **Least privilege**: request only what you need (read vs. write), and avoid requesting sensitive scopes “just in case.” * **Category-driven behavior**: only fields in the listed categories are covered. If an admin moves a field **out** of a sensitive category, it stops being covered by the sensitive scope; if a field is moved **into** a sensitive category, it becomes covered. **Two variants**: * **Sensitive data**: access to the data field of sensitive categories in employee data. * **Historical sensitive data**: access to historical tables of sensitive categories in employee data. **Sensitive scopes categories mapping** | **Scope** | **Sensitive categories covered** | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `employee_data.sensitive:read` | EEO (`eeo`)
Financial (`financial`)
Bands (`band`)
Bands calculated fields (`bandsCalculatedFields`)
Payroll (`payroll`)
UK tax settings (`ukTaxSettings`)
Equity (`equity`)
Identification (`identification`)
Analytics (`peopleAnalytics`) | | `employee_data.sensitive:write` | EEO (`eeo`)
Financial (`financial`)
Payroll (`payroll`)
UK tax settings (`ukTaxSettings`)
Equity (`equity`)
Identification (`identification`) | | `employee_data.sensitive.history:read` | EEO (`eeo`)
Financial (`financial`)
Payroll (`payroll`)
UK tax settings (`ukTaxSettings`)
Equity (`equity`)
Identification (`identification`)
Analytics (`peopleAnalytics`) |