Purple HRIS API Documentation

POST /api/purple-suite/hris/employees/search

Search HRIS employees by name, email or attributes

Parameters

Request body

application/json — required

• query string — Free-text search query (tokenized, scored by term overlap). Mutually exclusive with framed fields.
• name string — Full or partial person name — firstName + lastName substring match (framed search)
• email string — Email address partial match (framed search)
• department string — Exact department name match (framed search)
• role string — Role/title substring match (framed search)
• manager_name string — Manager full name substring — applied as post-filter after framed scoring (framed search)
• manager_email string — Manager email substring — applied as post-filter after framed scoring (framed search)
• employment_status string — Employment status exact match (framed search)

Responses

200

Search results in RecordResult format (top 5 matches by score)

application/json

• results array

  array of:

  • record object — Nested RecordResult envelope
    Nested RecordResult envelope
    • meta_info object
      • structured_entity object
        • person_entity object
          • person_info object

            …

          • contact_info object

            …

          • occupation_info object

            …

          • workplace_info object

            …

  • score number — Match score between 0 and 1
  • confidence string — EXACT_MATCH ≥ 0.9, VALID ≥ 0.5, INVALID < 0.5
• total_retrieved integer

500

Internal server error

POST /api/purple-suite/hris/users/search

Search HRIS employees, projected as flat User records

Parameters

Request body

application/json — required

• query string — Free-text search query (tokenized, scored by term overlap). Mutually exclusive with framed fields.
• name string — Full or partial person name — firstName + lastName substring match (framed search)
• email string — Email address partial match (framed search)
• department string — Exact department name match (framed search)
• role string — Role/title substring match (framed search)
• manager_name string — Manager full name substring — applied as post-filter after framed scoring (framed search)
• manager_email string — Manager email substring — applied as post-filter after framed scoring (framed search)
• employment_status string — Employment status exact match (framed search)

Responses

200

Search results as flat User records (top 5 matches by score)

application/json

• results array

  array of:

  • record_id string — Employee id
  • email_addr string
  • full_name string
  • first_name string
  • last_name string
  • department string
  • role string
  • manager_email string
  • timezone string
  • location string
• total_retrieved integer

500

Internal server error

GET /api/purple-suite/hris/employees

List HRIS employee records

Parameters

Responses

200

Paginated list

application/json

• data array

  array of:

  Employee

  • id string
  • firstName string required — Employee first name. Alias accepted on create/update: first_name
  • lastName string required — Employee last name. Alias accepted on create/update: last_name
  • email string required
  • department string — Department name. Must match an existing department. Alias accepted on create: department_id
  • title string
  • status string — Employment status. On PATCH also accepts 'suspended'. Use the /transition endpoint for lifecycle transitions.
  • startDate string — Employment start date. Alias accepted on create: hire_date
  • salary number
  • managerId string — ID of the manager employee. Alias accepted on create: manager_id
  • phone string
  • location string — City (leaf of the location hierarchy city ∈ country ∈ region).
  • country string — Country (derived from city). Middle level of the location hierarchy; drives HRBP country-level scope.
  • timezone string
  • costCenter string
  • region string — Geographic region (derived from location/city). Top level of the location hierarchy; used by HRBP analytics group-by + region scope.
  • job_level string — Job level code (IC1–IC6 / M1–M7). Alias accepted on create: level.
  • management_level string — Individual Contributor or Managerial.
  • employment_type string — Worker classification. Drives contingent-headcount analytics.
  • probation_end_date string — End of probation period; null once past probation. Drives probation-headcount analytics.
  • termination_type string — Set when status→terminated via /transition.
  • termination_reason string — Categorized exit reason (e.g. compensation, career_growth, relocation, performance, retirement).
  • termination_date string — Effective termination date (mirrors the latest 'terminated' status_history entry).
  • pto_balance object — Current PTO balance. Use PATCH /employees/{id}/pto-balance to update directly.
    Current PTO balance. Use PATCH /employees/{id}/pto-balance to update directly.
    • vacation_days number
    • sick_days number
  • status_history array — Immutable audit log of status transitions (appended by /transition endpoint).
    Immutable audit log of status transitions (appended by /transition endpoint).

    array of:

    • status string
    • reason string
    • effective_date string
    • recorded_at string
  • skills array — Employee skills with proficiency. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/skills.
    Employee skills with proficiency. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/skills.

    array of:

    • skill string
    • proficiency string
    • last_updated string
  • reviews array — Recent performance reviews. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/reviews.
    Recent performance reviews. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/reviews.

    array of:

    • id string
    • period string
    • rating string
    • strengths array

      array of:

      string

    • gaps array

      array of:

      string

    • reviewer_id string
    • reviewed_at string
  • goals array — Current development goals. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/goals.
    Current development goals. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/goals.

    array of:

    • id string
    • description string
    • target_role string
    • target_timeline string
    • status string
    • progress_pct integer
  • generate_related_records boolean — CREATE only. When true (or camelCase generateRelatedRecords), seeds 3 timesheets and 2 benefits for the new employee. Not stored.
  • createdAt string
  • updatedAt string
• nextCursor string — Cursor for the next page, or null on the last page
• total integer — Total documents in the collection

POST /api/purple-suite/hris/employees

Create an HRIS employee record

Parameters

Request body

application/json — required

Employee

• id string
• firstName string required — Employee first name. Alias accepted on create/update: first_name
• lastName string required — Employee last name. Alias accepted on create/update: last_name
• email string required
• department string — Department name. Must match an existing department. Alias accepted on create: department_id
• title string
• status string — Employment status. On PATCH also accepts 'suspended'. Use the /transition endpoint for lifecycle transitions.
• startDate string — Employment start date. Alias accepted on create: hire_date
• salary number
• managerId string — ID of the manager employee. Alias accepted on create: manager_id
• phone string
• location string — City (leaf of the location hierarchy city ∈ country ∈ region).
• country string — Country (derived from city). Middle level of the location hierarchy; drives HRBP country-level scope.
• timezone string
• costCenter string
• region string — Geographic region (derived from location/city). Top level of the location hierarchy; used by HRBP analytics group-by + region scope.
• job_level string — Job level code (IC1–IC6 / M1–M7). Alias accepted on create: level.
• management_level string — Individual Contributor or Managerial.
• employment_type string — Worker classification. Drives contingent-headcount analytics.
• probation_end_date string — End of probation period; null once past probation. Drives probation-headcount analytics.
• termination_type string — Set when status→terminated via /transition.
• termination_reason string — Categorized exit reason (e.g. compensation, career_growth, relocation, performance, retirement).
• termination_date string — Effective termination date (mirrors the latest 'terminated' status_history entry).
• pto_balance object — Current PTO balance. Use PATCH /employees/{id}/pto-balance to update directly.
  Current PTO balance. Use PATCH /employees/{id}/pto-balance to update directly.
  • vacation_days number
  • sick_days number
• status_history array — Immutable audit log of status transitions (appended by /transition endpoint).
  Immutable audit log of status transitions (appended by /transition endpoint).

  array of:

  • status string
  • reason string
  • effective_date string
  • recorded_at string
• skills array — Employee skills with proficiency. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/skills.
  Employee skills with proficiency. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/skills.

  array of:

  • skill string
  • proficiency string
  • last_updated string
• reviews array — Recent performance reviews. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/reviews.
  Recent performance reviews. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/reviews.

  array of:

  • id string
  • period string
  • rating string
  • strengths array

    array of:

    string

  • gaps array

    array of:

    string

  • reviewer_id string
  • reviewed_at string
• goals array — Current development goals. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/goals.
  Current development goals. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/goals.

  array of:

  • id string
  • description string
  • target_role string
  • target_timeline string
  • status string
  • progress_pct integer
• generate_related_records boolean — CREATE only. When true (or camelCase generateRelatedRecords), seeds 3 timesheets and 2 benefits for the new employee. Not stored.
• createdAt string
• updatedAt string

Responses

201

Created

application/json

Employee

• id string
• firstName string required — Employee first name. Alias accepted on create/update: first_name
• lastName string required — Employee last name. Alias accepted on create/update: last_name
• email string required
• department string — Department name. Must match an existing department. Alias accepted on create: department_id
• title string
• status string — Employment status. On PATCH also accepts 'suspended'. Use the /transition endpoint for lifecycle transitions.
• startDate string — Employment start date. Alias accepted on create: hire_date
• salary number
• managerId string — ID of the manager employee. Alias accepted on create: manager_id
• phone string
• location string — City (leaf of the location hierarchy city ∈ country ∈ region).
• country string — Country (derived from city). Middle level of the location hierarchy; drives HRBP country-level scope.
• timezone string
• costCenter string
• region string — Geographic region (derived from location/city). Top level of the location hierarchy; used by HRBP analytics group-by + region scope.
• job_level string — Job level code (IC1–IC6 / M1–M7). Alias accepted on create: level.
• management_level string — Individual Contributor or Managerial.
• employment_type string — Worker classification. Drives contingent-headcount analytics.
• probation_end_date string — End of probation period; null once past probation. Drives probation-headcount analytics.
• termination_type string — Set when status→terminated via /transition.
• termination_reason string — Categorized exit reason (e.g. compensation, career_growth, relocation, performance, retirement).
• termination_date string — Effective termination date (mirrors the latest 'terminated' status_history entry).
• pto_balance object — Current PTO balance. Use PATCH /employees/{id}/pto-balance to update directly.
  Current PTO balance. Use PATCH /employees/{id}/pto-balance to update directly.
  • vacation_days number
  • sick_days number
• status_history array — Immutable audit log of status transitions (appended by /transition endpoint).
  Immutable audit log of status transitions (appended by /transition endpoint).

  array of:

  • status string
  • reason string
  • effective_date string
  • recorded_at string
• skills array — Employee skills with proficiency. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/skills.
  Employee skills with proficiency. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/skills.

  array of:

  • skill string
  • proficiency string
  • last_updated string
• reviews array — Recent performance reviews. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/reviews.
  Recent performance reviews. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/reviews.

  array of:

  • id string
  • period string
  • rating string
  • strengths array

    array of:

    string

  • gaps array

    array of:

    string

  • reviewer_id string
  • reviewed_at string
• goals array — Current development goals. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/goals.
  Current development goals. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/goals.

  array of:

  • id string
  • description string
  • target_role string
  • target_timeline string
  • status string
  • progress_pct integer
• generate_related_records boolean — CREATE only. When true (or camelCase generateRelatedRecords), seeds 3 timesheets and 2 benefits for the new employee. Not stored.
• createdAt string
• updatedAt string

400

Missing required field or invalid status

409

Employee with this email already exists

GET /api/purple-suite/hris/employees/{id}

Get an HRIS employee record by id

Parameters

Responses

200

Found

application/json

Employee

• id string
• firstName string required — Employee first name. Alias accepted on create/update: first_name
• lastName string required — Employee last name. Alias accepted on create/update: last_name
• email string required
• department string — Department name. Must match an existing department. Alias accepted on create: department_id
• title string
• status string — Employment status. On PATCH also accepts 'suspended'. Use the /transition endpoint for lifecycle transitions.
• startDate string — Employment start date. Alias accepted on create: hire_date
• salary number
• managerId string — ID of the manager employee. Alias accepted on create: manager_id
• phone string
• location string — City (leaf of the location hierarchy city ∈ country ∈ region).
• country string — Country (derived from city). Middle level of the location hierarchy; drives HRBP country-level scope.
• timezone string
• costCenter string
• region string — Geographic region (derived from location/city). Top level of the location hierarchy; used by HRBP analytics group-by + region scope.
• job_level string — Job level code (IC1–IC6 / M1–M7). Alias accepted on create: level.
• management_level string — Individual Contributor or Managerial.
• employment_type string — Worker classification. Drives contingent-headcount analytics.
• probation_end_date string — End of probation period; null once past probation. Drives probation-headcount analytics.
• termination_type string — Set when status→terminated via /transition.
• termination_reason string — Categorized exit reason (e.g. compensation, career_growth, relocation, performance, retirement).
• termination_date string — Effective termination date (mirrors the latest 'terminated' status_history entry).
• pto_balance object — Current PTO balance. Use PATCH /employees/{id}/pto-balance to update directly.
  Current PTO balance. Use PATCH /employees/{id}/pto-balance to update directly.
  • vacation_days number
  • sick_days number
• status_history array — Immutable audit log of status transitions (appended by /transition endpoint).
  Immutable audit log of status transitions (appended by /transition endpoint).

  array of:

  • status string
  • reason string
  • effective_date string
  • recorded_at string
• skills array — Employee skills with proficiency. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/skills.
  Employee skills with proficiency. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/skills.

  array of:

  • skill string
  • proficiency string
  • last_updated string
• reviews array — Recent performance reviews. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/reviews.
  Recent performance reviews. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/reviews.

  array of:

  • id string
  • period string
  • rating string
  • strengths array

    array of:

    string

  • gaps array

    array of:

    string

  • reviewer_id string
  • reviewed_at string
• goals array — Current development goals. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/goals.
  Current development goals. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/goals.

  array of:

  • id string
  • description string
  • target_role string
  • target_timeline string
  • status string
  • progress_pct integer
• generate_related_records boolean — CREATE only. When true (or camelCase generateRelatedRecords), seeds 3 timesheets and 2 benefits for the new employee. Not stored.
• createdAt string
• updatedAt string

404

Not found

DELETE /api/purple-suite/hris/employees/{id}

Delete an HRIS employee record

Parameters

Responses

200

Deleted

application/json

• success boolean
• id string

404

Not found

PATCH /api/purple-suite/hris/employees/{id}

Update an HRIS employee record

Parameters

Request body

application/json

Employee

• id string
• firstName string required — Employee first name. Alias accepted on create/update: first_name
• lastName string required — Employee last name. Alias accepted on create/update: last_name
• email string required
• department string — Department name. Must match an existing department. Alias accepted on create: department_id
• title string
• status string — Employment status. On PATCH also accepts 'suspended'. Use the /transition endpoint for lifecycle transitions.
• startDate string — Employment start date. Alias accepted on create: hire_date
• salary number
• managerId string — ID of the manager employee. Alias accepted on create: manager_id
• phone string
• location string — City (leaf of the location hierarchy city ∈ country ∈ region).
• country string — Country (derived from city). Middle level of the location hierarchy; drives HRBP country-level scope.
• timezone string
• costCenter string
• region string — Geographic region (derived from location/city). Top level of the location hierarchy; used by HRBP analytics group-by + region scope.
• job_level string — Job level code (IC1–IC6 / M1–M7). Alias accepted on create: level.
• management_level string — Individual Contributor or Managerial.
• employment_type string — Worker classification. Drives contingent-headcount analytics.
• probation_end_date string — End of probation period; null once past probation. Drives probation-headcount analytics.
• termination_type string — Set when status→terminated via /transition.
• termination_reason string — Categorized exit reason (e.g. compensation, career_growth, relocation, performance, retirement).
• termination_date string — Effective termination date (mirrors the latest 'terminated' status_history entry).
• pto_balance object — Current PTO balance. Use PATCH /employees/{id}/pto-balance to update directly.
  Current PTO balance. Use PATCH /employees/{id}/pto-balance to update directly.
  • vacation_days number
  • sick_days number
• status_history array — Immutable audit log of status transitions (appended by /transition endpoint).
  Immutable audit log of status transitions (appended by /transition endpoint).

  array of:

  • status string
  • reason string
  • effective_date string
  • recorded_at string
• skills array — Employee skills with proficiency. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/skills.
  Employee skills with proficiency. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/skills.

  array of:

  • skill string
  • proficiency string
  • last_updated string
• reviews array — Recent performance reviews. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/reviews.
  Recent performance reviews. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/reviews.

  array of:

  • id string
  • period string
  • rating string
  • strengths array

    array of:

    string

  • gaps array

    array of:

    string

  • reviewer_id string
  • reviewed_at string
• goals array — Current development goals. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/goals.
  Current development goals. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/goals.

  array of:

  • id string
  • description string
  • target_role string
  • target_timeline string
  • status string
  • progress_pct integer
• generate_related_records boolean — CREATE only. When true (or camelCase generateRelatedRecords), seeds 3 timesheets and 2 benefits for the new employee. Not stored.
• createdAt string
• updatedAt string

Responses

200

Updated

application/json

Employee

• id string
• firstName string required — Employee first name. Alias accepted on create/update: first_name
• lastName string required — Employee last name. Alias accepted on create/update: last_name
• email string required
• department string — Department name. Must match an existing department. Alias accepted on create: department_id
• title string
• status string — Employment status. On PATCH also accepts 'suspended'. Use the /transition endpoint for lifecycle transitions.
• startDate string — Employment start date. Alias accepted on create: hire_date
• salary number
• managerId string — ID of the manager employee. Alias accepted on create: manager_id
• phone string
• location string — City (leaf of the location hierarchy city ∈ country ∈ region).
• country string — Country (derived from city). Middle level of the location hierarchy; drives HRBP country-level scope.
• timezone string
• costCenter string
• region string — Geographic region (derived from location/city). Top level of the location hierarchy; used by HRBP analytics group-by + region scope.
• job_level string — Job level code (IC1–IC6 / M1–M7). Alias accepted on create: level.
• management_level string — Individual Contributor or Managerial.
• employment_type string — Worker classification. Drives contingent-headcount analytics.
• probation_end_date string — End of probation period; null once past probation. Drives probation-headcount analytics.
• termination_type string — Set when status→terminated via /transition.
• termination_reason string — Categorized exit reason (e.g. compensation, career_growth, relocation, performance, retirement).
• termination_date string — Effective termination date (mirrors the latest 'terminated' status_history entry).
• pto_balance object — Current PTO balance. Use PATCH /employees/{id}/pto-balance to update directly.
  Current PTO balance. Use PATCH /employees/{id}/pto-balance to update directly.
  • vacation_days number
  • sick_days number
• status_history array — Immutable audit log of status transitions (appended by /transition endpoint).
  Immutable audit log of status transitions (appended by /transition endpoint).

  array of:

  • status string
  • reason string
  • effective_date string
  • recorded_at string
• skills array — Employee skills with proficiency. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/skills.
  Employee skills with proficiency. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/skills.

  array of:

  • skill string
  • proficiency string
  • last_updated string
• reviews array — Recent performance reviews. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/reviews.
  Recent performance reviews. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/reviews.

  array of:

  • id string
  • period string
  • rating string
  • strengths array

    array of:

    string

  • gaps array

    array of:

    string

  • reviewer_id string
  • reviewed_at string
• goals array — Current development goals. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/goals.
  Current development goals. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/goals.

  array of:

  • id string
  • description string
  • target_role string
  • target_timeline string
  • status string
  • progress_pct integer
• generate_related_records boolean — CREATE only. When true (or camelCase generateRelatedRecords), seeds 3 timesheets and 2 benefits for the new employee. Not stored.
• createdAt string
• updatedAt string

404

Not found

422

State machine violation (e.g. reactivating a terminated employee)

POST /api/purple-suite/hris/employees/{id}/transition

Move an employee through their lifecycle (leave / return / terminate)

Parameters

Request body

application/json — required

• status string required — Target status for the transition
• reason string — Human-readable reason for the transition (appended to status_history)
• effective_date string — When the transition takes effect (defaults to now)
• days number — PTO vacation days to deduct from pto_balance.vacation_days. Only applied when transitioning to on_leave.

Responses

200

Updated employee record

application/json

Employee

• id string
• firstName string required — Employee first name. Alias accepted on create/update: first_name
• lastName string required — Employee last name. Alias accepted on create/update: last_name
• email string required
• department string — Department name. Must match an existing department. Alias accepted on create: department_id
• title string
• status string — Employment status. On PATCH also accepts 'suspended'. Use the /transition endpoint for lifecycle transitions.
• startDate string — Employment start date. Alias accepted on create: hire_date
• salary number
• managerId string — ID of the manager employee. Alias accepted on create: manager_id
• phone string
• location string — City (leaf of the location hierarchy city ∈ country ∈ region).
• country string — Country (derived from city). Middle level of the location hierarchy; drives HRBP country-level scope.
• timezone string
• costCenter string
• region string — Geographic region (derived from location/city). Top level of the location hierarchy; used by HRBP analytics group-by + region scope.
• job_level string — Job level code (IC1–IC6 / M1–M7). Alias accepted on create: level.
• management_level string — Individual Contributor or Managerial.
• employment_type string — Worker classification. Drives contingent-headcount analytics.
• probation_end_date string — End of probation period; null once past probation. Drives probation-headcount analytics.
• termination_type string — Set when status→terminated via /transition.
• termination_reason string — Categorized exit reason (e.g. compensation, career_growth, relocation, performance, retirement).
• termination_date string — Effective termination date (mirrors the latest 'terminated' status_history entry).
• pto_balance object — Current PTO balance. Use PATCH /employees/{id}/pto-balance to update directly.
  Current PTO balance. Use PATCH /employees/{id}/pto-balance to update directly.
  • vacation_days number
  • sick_days number
• status_history array — Immutable audit log of status transitions (appended by /transition endpoint).
  Immutable audit log of status transitions (appended by /transition endpoint).

  array of:

  • status string
  • reason string
  • effective_date string
  • recorded_at string
• skills array — Employee skills with proficiency. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/skills.
  Employee skills with proficiency. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/skills.

  array of:

  • skill string
  • proficiency string
  • last_updated string
• reviews array — Recent performance reviews. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/reviews.
  Recent performance reviews. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/reviews.

  array of:

  • id string
  • period string
  • rating string
  • strengths array

    array of:

    string

  • gaps array

    array of:

    string

  • reviewer_id string
  • reviewed_at string
• goals array — Current development goals. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/goals.
  Current development goals. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/goals.

  array of:

  • id string
  • description string
  • target_role string
  • target_timeline string
  • status string
  • progress_pct integer
• generate_related_records boolean — CREATE only. When true (or camelCase generateRelatedRecords), seeds 3 timesheets and 2 benefits for the new employee. Not stored.
• createdAt string
• updatedAt string

400

Invalid status value

404

Employee not found

422

Transition not allowed by state machine rules

PATCH /api/purple-suite/hris/employees/{id}/pto-balance

Set an employee's PTO day balances

Parameters

Request body

application/json — required

• vacation_days number — New vacation day balance. Omit to keep current value.
• sick_days number — New sick day balance. Omit to keep current value.

Responses

200

Updated employee record with new pto_balance

application/json

Employee

• id string
• firstName string required — Employee first name. Alias accepted on create/update: first_name
• lastName string required — Employee last name. Alias accepted on create/update: last_name
• email string required
• department string — Department name. Must match an existing department. Alias accepted on create: department_id
• title string
• status string — Employment status. On PATCH also accepts 'suspended'. Use the /transition endpoint for lifecycle transitions.
• startDate string — Employment start date. Alias accepted on create: hire_date
• salary number
• managerId string — ID of the manager employee. Alias accepted on create: manager_id
• phone string
• location string — City (leaf of the location hierarchy city ∈ country ∈ region).
• country string — Country (derived from city). Middle level of the location hierarchy; drives HRBP country-level scope.
• timezone string
• costCenter string
• region string — Geographic region (derived from location/city). Top level of the location hierarchy; used by HRBP analytics group-by + region scope.
• job_level string — Job level code (IC1–IC6 / M1–M7). Alias accepted on create: level.
• management_level string — Individual Contributor or Managerial.
• employment_type string — Worker classification. Drives contingent-headcount analytics.
• probation_end_date string — End of probation period; null once past probation. Drives probation-headcount analytics.
• termination_type string — Set when status→terminated via /transition.
• termination_reason string — Categorized exit reason (e.g. compensation, career_growth, relocation, performance, retirement).
• termination_date string — Effective termination date (mirrors the latest 'terminated' status_history entry).
• pto_balance object — Current PTO balance. Use PATCH /employees/{id}/pto-balance to update directly.
  Current PTO balance. Use PATCH /employees/{id}/pto-balance to update directly.
  • vacation_days number
  • sick_days number
• status_history array — Immutable audit log of status transitions (appended by /transition endpoint).
  Immutable audit log of status transitions (appended by /transition endpoint).

  array of:

  • status string
  • reason string
  • effective_date string
  • recorded_at string
• skills array — Employee skills with proficiency. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/skills.
  Employee skills with proficiency. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/skills.

  array of:

  • skill string
  • proficiency string
  • last_updated string
• reviews array — Recent performance reviews. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/reviews.
  Recent performance reviews. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/reviews.

  array of:

  • id string
  • period string
  • rating string
  • strengths array

    array of:

    string

  • gaps array

    array of:

    string

  • reviewer_id string
  • reviewed_at string
• goals array — Current development goals. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/goals.
  Current development goals. Settable via PATCH /employees/{id}. Also available at GET /employees/{id}/goals.

  array of:

  • id string
  • description string
  • target_role string
  • target_timeline string
  • status string
  • progress_pct integer
• generate_related_records boolean — CREATE only. When true (or camelCase generateRelatedRecords), seeds 3 timesheets and 2 benefits for the new employee. Not stored.
• createdAt string
• updatedAt string

404

Employee not found

GET /api/purple-suite/hris/employees/{id}/skills

Get an employee's skills profile

Parameters

Responses

200

Employee skills

application/json

• employee_id string
• skills array

  array of:

  #/components/schemas/Employee/properties/skills/items

404

Employee not found

GET /api/purple-suite/hris/employees/{id}/reviews

Get an employee's performance review history

Parameters

Responses

200

Employee reviews

application/json

• employee_id string
• reviews array

  array of:

  #/components/schemas/Employee/properties/reviews/items

404

Employee not found

GET /api/purple-suite/hris/employees/{id}/goals

Get an employee's development goals

Parameters

Responses

200

Employee goals

application/json

• employee_id string
• goals array

  array of:

  #/components/schemas/Employee/properties/goals/items

404

Employee not found

GET /api/purple-suite/hris/departments

List HRIS departments

Parameters

Responses

200

Paginated list

application/json

• data array

  array of:

  Department

  • id string
  • name string required
  • manager string — Email of the department manager. Aliases accepted on create: managerId, head_employee_id
  • budget number
  • headCount integer — Number of employees in the department. Alias accepted on create: headcount (lowercase)
  • createdAt string
  • updatedAt string
• nextCursor string — Cursor for the next page, or null on the last page
• total integer — Total documents in the collection

POST /api/purple-suite/hris/departments

Create an HRIS department

Parameters

Request body

application/json — required

Department

• id string
• name string required
• manager string — Email of the department manager. Aliases accepted on create: managerId, head_employee_id
• budget number
• headCount integer — Number of employees in the department. Alias accepted on create: headcount (lowercase)
• createdAt string
• updatedAt string

Responses

201

Created

application/json

Department

• id string
• name string required
• manager string — Email of the department manager. Aliases accepted on create: managerId, head_employee_id
• budget number
• headCount integer — Number of employees in the department. Alias accepted on create: headcount (lowercase)
• createdAt string
• updatedAt string

GET /api/purple-suite/hris/departments/{id}

Get an HRIS department by id

Parameters

Responses

200

Found

application/json

Department

• id string
• name string required
• manager string — Email of the department manager. Aliases accepted on create: managerId, head_employee_id
• budget number
• headCount integer — Number of employees in the department. Alias accepted on create: headcount (lowercase)
• createdAt string
• updatedAt string

404

Not found

DELETE /api/purple-suite/hris/departments/{id}

Delete an HRIS department

Parameters

Responses

200

Deleted

application/json

• success boolean
• id string

404

Not found

PATCH /api/purple-suite/hris/departments/{id}

Edit an HRIS department

Parameters

Request body

application/json

Department

• id string
• name string required
• manager string — Email of the department manager. Aliases accepted on create: managerId, head_employee_id
• budget number
• headCount integer — Number of employees in the department. Alias accepted on create: headcount (lowercase)
• createdAt string
• updatedAt string

Responses

200

Updated

application/json

Department

• id string
• name string required
• manager string — Email of the department manager. Aliases accepted on create: managerId, head_employee_id
• budget number
• headCount integer — Number of employees in the department. Alias accepted on create: headcount (lowercase)
• createdAt string
• updatedAt string

404

Not found

GET /api/purple-suite/hris/pay-runs

List payroll runs

Parameters

Responses

200

Paginated list

application/json

• data array

  array of:

  PayRun

  • id string
  • periodStart string — Pay period start date. Alias accepted on create: period_start
  • periodEnd string — Pay period end date. Alias accepted on create: period_end
  • status string — Pay run status. State machine: draft → processing → completed. Completed runs are locked. Cancelled runs cannot be reactivated.
  • totalAmount number — Total gross payroll amount. Alias accepted on create: total_amount
  • employeeCount integer — Number of employees included in this run. Alias accepted on create: employee_count
  • runDate string
  • entries array — Per-employee pay breakdown. Set on create or PATCH.
    Per-employee pay breakdown. Set on create or PATCH.

    array of:

    • employeeId string
    • grossPay number
    • netPay number
  • createdAt string
  • updatedAt string
• nextCursor string — Cursor for the next page, or null on the last page
• total integer — Total documents in the collection

POST /api/purple-suite/hris/pay-runs

Open a payroll run

Parameters

Request body

application/json — required

PayRun

• id string
• periodStart string — Pay period start date. Alias accepted on create: period_start
• periodEnd string — Pay period end date. Alias accepted on create: period_end
• status string — Pay run status. State machine: draft → processing → completed. Completed runs are locked. Cancelled runs cannot be reactivated.
• totalAmount number — Total gross payroll amount. Alias accepted on create: total_amount
• employeeCount integer — Number of employees included in this run. Alias accepted on create: employee_count
• runDate string
• entries array — Per-employee pay breakdown. Set on create or PATCH.
  Per-employee pay breakdown. Set on create or PATCH.

  array of:

  • employeeId string
  • grossPay number
  • netPay number
• createdAt string
• updatedAt string

Responses

201

Created

application/json

PayRun

• id string
• periodStart string — Pay period start date. Alias accepted on create: period_start
• periodEnd string — Pay period end date. Alias accepted on create: period_end
• status string — Pay run status. State machine: draft → processing → completed. Completed runs are locked. Cancelled runs cannot be reactivated.
• totalAmount number — Total gross payroll amount. Alias accepted on create: total_amount
• employeeCount integer — Number of employees included in this run. Alias accepted on create: employee_count
• runDate string
• entries array — Per-employee pay breakdown. Set on create or PATCH.
  Per-employee pay breakdown. Set on create or PATCH.

  array of:

  • employeeId string
  • grossPay number
  • netPay number
• createdAt string
• updatedAt string

GET /api/purple-suite/hris/pay-runs/{id}

Get a payroll run by id

Parameters

Responses

200

Found

application/json

PayRun

• id string
• periodStart string — Pay period start date. Alias accepted on create: period_start
• periodEnd string — Pay period end date. Alias accepted on create: period_end
• status string — Pay run status. State machine: draft → processing → completed. Completed runs are locked. Cancelled runs cannot be reactivated.
• totalAmount number — Total gross payroll amount. Alias accepted on create: total_amount
• employeeCount integer — Number of employees included in this run. Alias accepted on create: employee_count
• runDate string
• entries array — Per-employee pay breakdown. Set on create or PATCH.
  Per-employee pay breakdown. Set on create or PATCH.

  array of:

  • employeeId string
  • grossPay number
  • netPay number
• createdAt string
• updatedAt string

404

Not found

DELETE /api/purple-suite/hris/pay-runs/{id}

Delete a payroll run

Parameters

Responses

200

Deleted

application/json

• success boolean
• id string

404

Not found

PATCH /api/purple-suite/hris/pay-runs/{id}

Advance or edit a payroll run

Parameters

Request body

application/json

PayRun

• id string
• periodStart string — Pay period start date. Alias accepted on create: period_start
• periodEnd string — Pay period end date. Alias accepted on create: period_end
• status string — Pay run status. State machine: draft → processing → completed. Completed runs are locked. Cancelled runs cannot be reactivated.
• totalAmount number — Total gross payroll amount. Alias accepted on create: total_amount
• employeeCount integer — Number of employees included in this run. Alias accepted on create: employee_count
• runDate string
• entries array — Per-employee pay breakdown. Set on create or PATCH.
  Per-employee pay breakdown. Set on create or PATCH.

  array of:

  • employeeId string
  • grossPay number
  • netPay number
• createdAt string
• updatedAt string

Responses

200

Updated

application/json

PayRun

• id string
• periodStart string — Pay period start date. Alias accepted on create: period_start
• periodEnd string — Pay period end date. Alias accepted on create: period_end
• status string — Pay run status. State machine: draft → processing → completed. Completed runs are locked. Cancelled runs cannot be reactivated.
• totalAmount number — Total gross payroll amount. Alias accepted on create: total_amount
• employeeCount integer — Number of employees included in this run. Alias accepted on create: employee_count
• runDate string
• entries array — Per-employee pay breakdown. Set on create or PATCH.
  Per-employee pay breakdown. Set on create or PATCH.

  array of:

  • employeeId string
  • grossPay number
  • netPay number
• createdAt string
• updatedAt string

404

Not found

422

State machine violation (e.g. modifying a completed run, or skipping processing status)

GET /api/purple-suite/hris/timesheets

List employee timesheets

Parameters

Responses

200

Paginated list

application/json

• data array

  array of:

  Timesheet

  • id string
  • employee_id string
  • week_start string
  • hours_worked number
  • overtime_hours number
  • status string
  • created_at string
  • updated_at string
• nextCursor string — Cursor for the next page, or null on the last page
• total integer — Total documents in the collection

POST /api/purple-suite/hris/timesheets

Submit a weekly timesheet

Parameters

Request body

application/json — required

Timesheet

• id string
• employee_id string
• week_start string
• hours_worked number
• overtime_hours number
• status string
• created_at string
• updated_at string

Responses

201

Created

application/json

Timesheet

• id string
• employee_id string
• week_start string
• hours_worked number
• overtime_hours number
• status string
• created_at string
• updated_at string

400

Missing required field or out-of-range hours

404

Employee not found

409

Timesheet already exists for this employee and week

422

Cannot submit timesheet for a terminated employee

GET /api/purple-suite/hris/timesheets/{id}

Get a timesheet by id

Parameters

Responses

200

Found

application/json

Timesheet

• id string
• employee_id string
• week_start string
• hours_worked number
• overtime_hours number
• status string
• created_at string
• updated_at string

404

Not found

DELETE /api/purple-suite/hris/timesheets/{id}

Delete a timesheet

Parameters

Responses

200

Deleted

application/json

• success boolean
• id string

404

Not found

PATCH /api/purple-suite/hris/timesheets/{id}

Approve, reject or correct a timesheet

Parameters

Request body

application/json

Timesheet

• id string
• employee_id string
• week_start string
• hours_worked number
• overtime_hours number
• status string
• created_at string
• updated_at string

Responses

200

Updated

application/json

Timesheet

• id string
• employee_id string
• week_start string
• hours_worked number
• overtime_hours number
• status string
• created_at string
• updated_at string

404

Not found

GET /api/purple-suite/hris/benefits

List employee benefit enrollments

Parameters

Responses

200

Paginated list

application/json

• data array

  array of:

  Benefit

  • id string
  • employee_id string
  • type string
  • plan_name string
  • status string
  • enrollment_date string
  • created_at string
  • updated_at string
• nextCursor string — Cursor for the next page, or null on the last page
• total integer — Total documents in the collection

POST /api/purple-suite/hris/benefits

Enroll an employee in a benefit plan

Parameters

Request body

application/json — required

Benefit

• id string
• employee_id string
• type string
• plan_name string
• status string
• enrollment_date string
• created_at string
• updated_at string

Responses

201

Created

application/json

Benefit

• id string
• employee_id string
• type string
• plan_name string
• status string
• enrollment_date string
• created_at string
• updated_at string

400

Missing required field or invalid type

404

Employee not found

422

Employee already has an active benefit of this type

GET /api/purple-suite/hris/benefits/{id}

Get a benefit enrollment by id

Parameters

Responses

200

Found

application/json

Benefit

• id string
• employee_id string
• type string
• plan_name string
• status string
• enrollment_date string
• created_at string
• updated_at string

404

Not found

DELETE /api/purple-suite/hris/benefits/{id}

Delete a benefit enrollment

Parameters

Responses

200

Deleted

application/json

• success boolean
• id string

404

Not found

PATCH /api/purple-suite/hris/benefits/{id}

Change or terminate a benefit enrollment

Parameters

Request body

application/json

Benefit

• id string
• employee_id string
• type string
• plan_name string
• status string
• enrollment_date string
• created_at string
• updated_at string

Responses

200

Updated

application/json

Benefit

• id string
• employee_id string
• type string
• plan_name string
• status string
• enrollment_date string
• created_at string
• updated_at string

404

Not found

GET /api/purple-suite/hris/review-cycles

List performance review cycles

Parameters

Responses

200

Paginated list

application/json

• data array

  array of:

  ReviewCycle

  • id string
  • name string
  • period string
  • status string
  • employee_id string
  • manager_id string
  • rating string
  • notes string
  • created_at string
  • updated_at string
• nextCursor string — Cursor for the next page, or null on the last page
• total integer — Total documents in the collection

POST /api/purple-suite/hris/review-cycles

Open a performance review cycle

Parameters

Request body

application/json — required

ReviewCycle

• id string
• name string
• period string
• status string
• employee_id string
• manager_id string
• rating string
• notes string
• created_at string
• updated_at string

Responses

201

Created

application/json

ReviewCycle

• id string
• name string
• period string
• status string
• employee_id string
• manager_id string
• rating string
• notes string
• created_at string
• updated_at string

GET /api/purple-suite/hris/review-cycles/{id}

Get a performance review cycle by id

Parameters

Responses

200

Found

application/json

ReviewCycle

• id string
• name string
• period string
• status string
• employee_id string
• manager_id string
• rating string
• notes string
• created_at string
• updated_at string

404

Not found

DELETE /api/purple-suite/hris/review-cycles/{id}

Delete a performance review cycle

Parameters

Responses

200

Deleted

application/json

• success boolean
• id string

404

Not found

PATCH /api/purple-suite/hris/review-cycles/{id}

Progress or complete a review cycle

Parameters

Request body

application/json

ReviewCycle

• id string
• name string
• period string
• status string
• employee_id string
• manager_id string
• rating string
• notes string
• created_at string
• updated_at string

Responses

200

Updated

application/json

ReviewCycle

• id string
• name string
• period string
• status string
• employee_id string
• manager_id string
• rating string
• notes string
• created_at string
• updated_at string

404

Not found

GET /api/purple-suite/hris/time-off-requests

List time-off (PTO) requests

Parameters

Responses

200

Paginated list

application/json

• data array

  array of:

  TimeOffRequest

  • id string
  • employee_id string required — ID of the requesting employee. Alias accepted on create: employeeId
  • type string — Kind of time off. Defaults to 'vacation'.
  • start_date string required — First day off (inclusive). Alias accepted on create: startDate
  • end_date string required — Last day off (inclusive). Alias accepted on create: endDate
  • hours number — Total hours requested
  • note string — Optional reason / note for the request
  • status string — Request status. Defaults to 'pending' on create; approve/deny via PATCH.
  • created_at string
  • updated_at string
• nextCursor string — Cursor for the next page, or null on the last page
• total integer — Total documents in the collection

POST /api/purple-suite/hris/time-off-requests

Submit a time-off (PTO) request

Parameters

Request body

application/json — required

TimeOffRequest

• id string
• employee_id string required — ID of the requesting employee. Alias accepted on create: employeeId
• type string — Kind of time off. Defaults to 'vacation'.
• start_date string required — First day off (inclusive). Alias accepted on create: startDate
• end_date string required — Last day off (inclusive). Alias accepted on create: endDate
• hours number — Total hours requested
• note string — Optional reason / note for the request
• status string — Request status. Defaults to 'pending' on create; approve/deny via PATCH.
• created_at string
• updated_at string

Responses

201

Created

application/json

TimeOffRequest

• id string
• employee_id string required — ID of the requesting employee. Alias accepted on create: employeeId
• type string — Kind of time off. Defaults to 'vacation'.
• start_date string required — First day off (inclusive). Alias accepted on create: startDate
• end_date string required — Last day off (inclusive). Alias accepted on create: endDate
• hours number — Total hours requested
• note string — Optional reason / note for the request
• status string — Request status. Defaults to 'pending' on create; approve/deny via PATCH.
• created_at string
• updated_at string

400

Missing required field or invalid type/status

404

Employee not found

GET /api/purple-suite/hris/time-off-requests/{id}

Get a time-off (PTO) request by id

Parameters

Responses

200

Found

application/json

TimeOffRequest

• id string
• employee_id string required — ID of the requesting employee. Alias accepted on create: employeeId
• type string — Kind of time off. Defaults to 'vacation'.
• start_date string required — First day off (inclusive). Alias accepted on create: startDate
• end_date string required — Last day off (inclusive). Alias accepted on create: endDate
• hours number — Total hours requested
• note string — Optional reason / note for the request
• status string — Request status. Defaults to 'pending' on create; approve/deny via PATCH.
• created_at string
• updated_at string

404

Not found

PATCH /api/purple-suite/hris/time-off-requests/{id}

Approve, deny or amend a time-off request

Parameters

Request body

application/json

TimeOffRequest

• id string
• employee_id string required — ID of the requesting employee. Alias accepted on create: employeeId
• type string — Kind of time off. Defaults to 'vacation'.
• start_date string required — First day off (inclusive). Alias accepted on create: startDate
• end_date string required — Last day off (inclusive). Alias accepted on create: endDate
• hours number — Total hours requested
• note string — Optional reason / note for the request
• status string — Request status. Defaults to 'pending' on create; approve/deny via PATCH.
• created_at string
• updated_at string

Responses

200

Updated

application/json

TimeOffRequest

• id string
• employee_id string required — ID of the requesting employee. Alias accepted on create: employeeId
• type string — Kind of time off. Defaults to 'vacation'.
• start_date string required — First day off (inclusive). Alias accepted on create: startDate
• end_date string required — Last day off (inclusive). Alias accepted on create: endDate
• hours number — Total hours requested
• note string — Optional reason / note for the request
• status string — Request status. Defaults to 'pending' on create; approve/deny via PATCH.
• created_at string
• updated_at string

404

Not found

GET /api/purple-suite/hris/work-authorizations

List work authorizations (visas / right to work)

Parameters

Responses

200

Paginated list

application/json

• data array

  array of:

  WorkAuthorization

  An employee's right-to-work record for a country: visa/permit type, status, expiry, and renewal tracking. Citizens and permanent residents have no expiry. The agent stitches this with Purple Expense trips to answer travel-eligibility questions.
  • id string
  • employee_email string — The employee this authorization belongs to (matches an Employee.email and the canonical Identity directory).
  • country string — Country this authorization grants the right to work in.
  • authorization_type string
  • status string
  • issued_date string
  • expiry_date string — Null for citizen / permanent_resident.
  • sponsoring_entity string — Employer/entity sponsoring the visa, if any.
  • renewal_status string
  • renewal_due_date string
  • travel_restrictions array — Advisories that affect international travel (e.g. advance_parole_required).
    Advisories that affect international travel (e.g. advance_parole_required).

    array of:

    string

  • notes string
  • createdAt string
  • updatedAt string
• nextCursor string — Cursor for the next page, or null on the last page
• total integer — Total documents in the collection

POST /api/purple-suite/hris/work-authorizations

Record a work authorization for an employee

Parameters

Request body

application/json — required

WorkAuthorization

• id string
• employee_email string — The employee this authorization belongs to (matches an Employee.email and the canonical Identity directory).
• country string — Country this authorization grants the right to work in.
• authorization_type string
• status string
• issued_date string
• expiry_date string — Null for citizen / permanent_resident.
• sponsoring_entity string — Employer/entity sponsoring the visa, if any.
• renewal_status string
• renewal_due_date string
• travel_restrictions array — Advisories that affect international travel (e.g. advance_parole_required).
  Advisories that affect international travel (e.g. advance_parole_required).

  array of:

  string

• notes string
• createdAt string
• updatedAt string

Responses

201

Created

application/json

WorkAuthorization

An employee's right-to-work record for a country: visa/permit type, status, expiry, and renewal tracking. Citizens and permanent residents have no expiry. The agent stitches this with Purple Expense trips to answer travel-eligibility questions.

• id string
• employee_email string — The employee this authorization belongs to (matches an Employee.email and the canonical Identity directory).
• country string — Country this authorization grants the right to work in.
• authorization_type string
• status string
• issued_date string
• expiry_date string — Null for citizen / permanent_resident.
• sponsoring_entity string — Employer/entity sponsoring the visa, if any.
• renewal_status string
• renewal_due_date string
• travel_restrictions array — Advisories that affect international travel (e.g. advance_parole_required).
  Advisories that affect international travel (e.g. advance_parole_required).

  array of:

  string

• notes string
• createdAt string
• updatedAt string

400

Validation error

GET /api/purple-suite/hris/work-authorizations/{id}

Get a work authorization by id

Parameters

Responses

200

Found

application/json

WorkAuthorization

An employee's right-to-work record for a country: visa/permit type, status, expiry, and renewal tracking. Citizens and permanent residents have no expiry. The agent stitches this with Purple Expense trips to answer travel-eligibility questions.

• id string
• employee_email string — The employee this authorization belongs to (matches an Employee.email and the canonical Identity directory).
• country string — Country this authorization grants the right to work in.
• authorization_type string
• status string
• issued_date string
• expiry_date string — Null for citizen / permanent_resident.
• sponsoring_entity string — Employer/entity sponsoring the visa, if any.
• renewal_status string
• renewal_due_date string
• travel_restrictions array — Advisories that affect international travel (e.g. advance_parole_required).
  Advisories that affect international travel (e.g. advance_parole_required).

  array of:

  string

• notes string
• createdAt string
• updatedAt string

404

Not found

DELETE /api/purple-suite/hris/work-authorizations/{id}

Delete a work authorization

Parameters

Responses

200

Deleted

application/json

• success boolean
• id string

404

Not found

PATCH /api/purple-suite/hris/work-authorizations/{id}

Edit a work authorization

Parameters

Request body

application/json

WorkAuthorization

• id string
• employee_email string — The employee this authorization belongs to (matches an Employee.email and the canonical Identity directory).
• country string — Country this authorization grants the right to work in.
• authorization_type string
• status string
• issued_date string
• expiry_date string — Null for citizen / permanent_resident.
• sponsoring_entity string — Employer/entity sponsoring the visa, if any.
• renewal_status string
• renewal_due_date string
• travel_restrictions array — Advisories that affect international travel (e.g. advance_parole_required).
  Advisories that affect international travel (e.g. advance_parole_required).

  array of:

  string

• notes string
• createdAt string
• updatedAt string

Responses

200

Updated

application/json

WorkAuthorization

An employee's right-to-work record for a country: visa/permit type, status, expiry, and renewal tracking. Citizens and permanent residents have no expiry. The agent stitches this with Purple Expense trips to answer travel-eligibility questions.

• id string
• employee_email string — The employee this authorization belongs to (matches an Employee.email and the canonical Identity directory).
• country string — Country this authorization grants the right to work in.
• authorization_type string
• status string
• issued_date string
• expiry_date string — Null for citizen / permanent_resident.
• sponsoring_entity string — Employer/entity sponsoring the visa, if any.
• renewal_status string
• renewal_due_date string
• travel_restrictions array — Advisories that affect international travel (e.g. advance_parole_required).
  Advisories that affect international travel (e.g. advance_parole_required).

  array of:

  string

• notes string
• createdAt string
• updatedAt string

404

Not found

POST /api/purple-suite/hris/work-authorizations/{id}/renew

File a renewal / extension for a work authorization

Parameters

Request body

application/json

• extend_months integer — Months to extend expiry_date by (default 24).
• notes string

Responses

200

Renewal filed

application/json

WorkAuthorization

An employee's right-to-work record for a country: visa/permit type, status, expiry, and renewal tracking. Citizens and permanent residents have no expiry. The agent stitches this with Purple Expense trips to answer travel-eligibility questions.

• id string
• employee_email string — The employee this authorization belongs to (matches an Employee.email and the canonical Identity directory).
• country string — Country this authorization grants the right to work in.
• authorization_type string
• status string
• issued_date string
• expiry_date string — Null for citizen / permanent_resident.
• sponsoring_entity string — Employer/entity sponsoring the visa, if any.
• renewal_status string
• renewal_due_date string
• travel_restrictions array — Advisories that affect international travel (e.g. advance_parole_required).
  Advisories that affect international travel (e.g. advance_parole_required).

  array of:

  string

• notes string
• createdAt string
• updatedAt string

404

Authorization not found

422

Authorization cannot be renewed (no expiry, or already filed)

GET /api/purple-suite/hris/job-families

List job families (career groupings)

Parameters

Responses

200

Paginated list

application/json

• data array

  array of:

  JobFamily

  Career family grouping related job profiles (reference catalog).
  • id string
  • name string required
  • description string
  • createdAt string
  • updatedAt string
• nextCursor string — Cursor for the next page, or null on the last page
• total integer — Total documents in the collection

POST /api/purple-suite/hris/job-families

Create a job family

Parameters

Request body

application/json — required

JobFamily

• id string
• name string required
• description string
• createdAt string
• updatedAt string

Responses

201

Created

application/json

JobFamily

Career family grouping related job profiles (reference catalog).

• id string
• name string required
• description string
• createdAt string
• updatedAt string

400

Validation / missing reference

409

Duplicate

GET /api/purple-suite/hris/job-families/{id}

Get a job family by id

Parameters

Responses

200

Found

application/json

JobFamily

Career family grouping related job profiles (reference catalog).

• id string
• name string required
• description string
• createdAt string
• updatedAt string

404

Not found

DELETE /api/purple-suite/hris/job-families/{id}

Delete a job family

Parameters

Responses

200

Deleted

application/json

• success boolean
• id string

404

Not found

409

Blocked — still referenced by dependents

PATCH /api/purple-suite/hris/job-families/{id}

Rename or edit a job family

Parameters

Request body

application/json

JobFamily

• id string
• name string required
• description string
• createdAt string
• updatedAt string

Responses

200

Updated

application/json

JobFamily

Career family grouping related job profiles (reference catalog).

• id string
• name string required
• description string
• createdAt string
• updatedAt string

400

Validation / missing reference

404

Not found

GET /api/purple-suite/hris/job-levels

List job levels (leveling framework grades)

Parameters

Responses

200

Paginated list

application/json

• data array

  array of:

  JobLevel

  Job level / grade in the leveling framework (reference catalog).
  • id string — Level code (IC1–IC6 / M1–M5).
  • name string required
  • track string — Individual-contributor or management track.
  • tier integer — Numeric rank within the track.
  • management_level string
  • createdAt string
  • updatedAt string
• nextCursor string — Cursor for the next page, or null on the last page
• total integer — Total documents in the collection

POST /api/purple-suite/hris/job-levels

Create a job level

Parameters

Request body

application/json — required

JobLevel

• id string — Level code (IC1–IC6 / M1–M5).
• name string required
• track string — Individual-contributor or management track.
• tier integer — Numeric rank within the track.
• management_level string
• createdAt string
• updatedAt string

Responses

201

Created

application/json

JobLevel

Job level / grade in the leveling framework (reference catalog).

• id string — Level code (IC1–IC6 / M1–M5).
• name string required
• track string — Individual-contributor or management track.
• tier integer — Numeric rank within the track.
• management_level string
• createdAt string
• updatedAt string

400

Validation / missing reference

409

Duplicate

GET /api/purple-suite/hris/job-levels/{id}

Get a job level by id

Parameters

Responses

200

Found

application/json

JobLevel

Job level / grade in the leveling framework (reference catalog).

• id string — Level code (IC1–IC6 / M1–M5).
• name string required
• track string — Individual-contributor or management track.
• tier integer — Numeric rank within the track.
• management_level string
• createdAt string
• updatedAt string

404

Not found

DELETE /api/purple-suite/hris/job-levels/{id}

Delete a job level

Parameters

Responses

200

Deleted

application/json

• success boolean
• id string

404

Not found

409

Blocked — still referenced by dependents

PATCH /api/purple-suite/hris/job-levels/{id}

Rename or edit a job level

Parameters

Request body

application/json

JobLevel

• id string — Level code (IC1–IC6 / M1–M5).
• name string required
• track string — Individual-contributor or management track.
• tier integer — Numeric rank within the track.
• management_level string
• createdAt string
• updatedAt string

Responses

200

Updated

application/json

JobLevel

Job level / grade in the leveling framework (reference catalog).

• id string — Level code (IC1–IC6 / M1–M5).
• name string required
• track string — Individual-contributor or management track.
• tier integer — Numeric rank within the track.
• management_level string
• createdAt string
• updatedAt string

400

Validation / missing reference

404

Not found

GET /api/purple-suite/hris/job-profiles

List job profiles (role templates: title + family + level)

Parameters

Responses

200

Paginated list

application/json

• data array

  array of:

  JobProfile

  Job profile (role template) tying a title to a family + level (reference catalog).
  • id string
  • title string required
  • job_family string — JobFamily name.
  • job_level string — JobLevel code.
  • management_level string
  • createdAt string
  • updatedAt string
• nextCursor string — Cursor for the next page, or null on the last page
• total integer — Total documents in the collection

POST /api/purple-suite/hris/job-profiles

Create a job profile

Parameters

Request body

application/json — required

JobProfile

• id string
• title string required
• job_family string — JobFamily name.
• job_level string — JobLevel code.
• management_level string
• createdAt string
• updatedAt string

Responses

201

Created

application/json

JobProfile

Job profile (role template) tying a title to a family + level (reference catalog).

• id string
• title string required
• job_family string — JobFamily name.
• job_level string — JobLevel code.
• management_level string
• createdAt string
• updatedAt string

400

Validation / missing reference

409

Duplicate

GET /api/purple-suite/hris/job-profiles/{id}

Get a job profile by id

Parameters

Responses

200

Found

application/json

JobProfile

Job profile (role template) tying a title to a family + level (reference catalog).

• id string
• title string required
• job_family string — JobFamily name.
• job_level string — JobLevel code.
• management_level string
• createdAt string
• updatedAt string

404

Not found

DELETE /api/purple-suite/hris/job-profiles/{id}

Delete a job profile

Parameters

Responses

200

Deleted

application/json

• success boolean
• id string

404

Not found

409

Blocked — still referenced by dependents

PATCH /api/purple-suite/hris/job-profiles/{id}

Edit a job profile

Parameters

Request body

application/json

JobProfile

• id string
• title string required
• job_family string — JobFamily name.
• job_level string — JobLevel code.
• management_level string
• createdAt string
• updatedAt string

Responses

200

Updated

application/json

JobProfile

Job profile (role template) tying a title to a family + level (reference catalog).

• id string
• title string required
• job_family string — JobFamily name.
• job_level string — JobLevel code.
• management_level string
• createdAt string
• updatedAt string

400

Validation / missing reference

404

Not found

GET /api/purple-suite/hris/job-roles

List job roles (positions under a family)

Parameters

Responses

200

Paginated list

application/json

• data array

  array of:

  JobRole

  Job role under a family, optionally mapped to a job profile (reference catalog; modeled on sn_hr_core_position).
  • id string
  • name string required
  • description string
  • active boolean
  • job_family string — JobFamily name.
  • job_profile string — JobProfile id.
  • createdAt string
  • updatedAt string
• nextCursor string — Cursor for the next page, or null on the last page
• total integer — Total documents in the collection

POST /api/purple-suite/hris/job-roles

Create a job role

Parameters

Request body

application/json — required

JobRole

• id string
• name string required
• description string
• active boolean
• job_family string — JobFamily name.
• job_profile string — JobProfile id.
• createdAt string
• updatedAt string

Responses

201

Created

application/json

JobRole

Job role under a family, optionally mapped to a job profile (reference catalog; modeled on sn_hr_core_position).

• id string
• name string required
• description string
• active boolean
• job_family string — JobFamily name.
• job_profile string — JobProfile id.
• createdAt string
• updatedAt string

400

Validation / missing reference

409

Duplicate

GET /api/purple-suite/hris/job-roles/{id}

Get a job role by id

Parameters

Responses

200

Found

application/json

JobRole

Job role under a family, optionally mapped to a job profile (reference catalog; modeled on sn_hr_core_position).

• id string
• name string required
• description string
• active boolean
• job_family string — JobFamily name.
• job_profile string — JobProfile id.
• createdAt string
• updatedAt string

404

Not found

DELETE /api/purple-suite/hris/job-roles/{id}

Delete a job role

Parameters