API Reference
Become a partner

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

Scopes mapping to endpoints

Scope name in Portal & DescriptionEndpoints

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

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

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

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

ScopeSensitive categories covered
employee_data.sensitive:readEEO (eeo)
Financial (financial)
Bands (band)
Bands calculated fields (bandsCalculatedFields)
Payroll (payroll)
UK tax settings (ukTaxSettings)
Equity (equity)
Identification (identification)
Analytics (peopleAnalytics)
employee_data.sensitive:writeEEO (eeo)
Financial (financial)
Payroll (payroll)
UK tax settings (ukTaxSettings)
Equity (equity)
Identification (identification)
employee_data.sensitive.history:readEEO (eeo)
Financial (financial)
Payroll (payroll)
UK tax settings (ukTaxSettings)
Equity (equity)
Identification (identification)
Analytics (peopleAnalytics)

Updated 10 days ago

Did this page help you?

Updated 10 days ago

Did this page help you?