> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getprimo.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get employees, optionally narrowed by a search
> Return your company's employees as a paginated list. Pass `search` to turn a name or an email into the employee it refers to instead of paging: free text over first and last name, full name in either order, work email and personal email, ignoring case and accents, plus text and URL custom field values. Exactly one result is that person; several mean the name is ambiguous and nobody was found — ask which is meant, never take the first. `id` is the employee itself; `managerId`, `deviceIds` and `accessoryIds` name other records, never a search result. Items carry `id`, `firstName`, `lastName`, `email`, `teams` and `jobs` (`{ id, name }` — teams and job titles), `groups`, `workLocation`, `legalEntity`, `managerId`, `startDate`, `terminationDate`, `onboardingStatus`, `offboardingStatus`, `deviceIds`, `accessoryIds`, `createdAt` and `updatedAt`. It omits personal data such as the postal address and the personal email — `getEmployee` with an id returns the full record. Never conclude a field is empty from this list alone.
Key: ReadScope: Company
## OpenAPI
````yaml https://api.getprimo.com/openapi.json get /employees
openapi: 3.1.1
info:
title: Public API - BETA
description: Read docs on https://docs.getprimo.com/
version: '1.0'
contact: {}
servers:
- url: https://api.getprimo.com
security:
- apikey: []
tags: []
paths:
/employees:
get:
tags:
- Employees
summary: Get employees, optionally narrowed by a search
description: >-
Return your company's employees as a paginated list. Pass `search` to
turn a name or an email into the employee it refers to instead of
paging: free text over first and last name, full name in either order,
work email and personal email, ignoring case and accents, plus text and
URL custom field values. Exactly one result is that person; several mean
the name is ambiguous and nobody was found — ask which is meant, never
take the first. `id` is the employee itself; `managerId`, `deviceIds`
and `accessoryIds` name other records, never a search result. Items
carry `id`, `firstName`, `lastName`, `email`, `teams` and `jobs` (`{ id,
name }` — teams and job titles), `groups`, `workLocation`,
`legalEntity`, `managerId`, `startDate`, `terminationDate`,
`onboardingStatus`, `offboardingStatus`, `deviceIds`, `accessoryIds`,
`createdAt` and `updatedAt`. It omits personal data such as the postal
address and the personal email — `getEmployee` with an id returns the
full record. Never conclude a field is empty from this list alone.
operationId: getEmployees
parameters:
- name: page
required: false
in: query
description: Page number
schema:
minimum: 1
maximum: 9007199254740991
default: 1
type: number
- name: perPage
required: false
in: query
description: Number of items per page (max 100)
schema:
minimum: 1
maximum: 100
default: 50
type: number
- name: search
required: false
in: query
description: >-
Free-text search over first name, last name, full name in either
order, work email and personal email, ignoring case and accents.
Text and URL custom field values are also matched,
case-insensitively and without accent folding.
schema:
type: string
minLength: 1
responses:
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetEmployees_Output'
components:
schemas:
GetEmployees_Output:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
firstName:
type: string
lastName:
type: string
email:
type: string
teams:
description: >-
Teams the employee belongs to. Empty only when no team is
assigned — group by `name` to count per team.
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
required:
- id
- name
additionalProperties: false
jobs:
description: >-
Job titles held by the employee. Empty only when no job title
is assigned.
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
required:
- id
- name
additionalProperties: false
groups:
description: Employee groups the employee belongs to.
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
required:
- id
- name
additionalProperties: false
workLocation:
description: >-
Office the employee is attached to. Null for a remote
employee.
anyOf:
- type: object
properties:
id:
type: string
name:
type: string
required:
- id
- name
additionalProperties: false
- type: 'null'
legalEntity:
description: Legal entity employing them.
anyOf:
- type: object
properties:
id:
type: string
name:
type: string
required:
- id
- name
additionalProperties: false
- type: 'null'
managerId:
description: Id of the manager employee.
anyOf:
- type: string
- type: 'null'
startDate:
description: Employment start date (ISO 8601).
anyOf:
- type: string
format: date-time
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
- type: 'null'
terminationDate:
description: Employment end date (ISO 8601).
anyOf:
- type: string
format: date-time
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
- type: 'null'
onboardingStatus:
description: Null when the employee has no onboarding.
anyOf:
- type: string
enum:
- PENDING
- SCHEDULED
- IN_PROGRESS
- CLOSED
- CANCELED
- type: 'null'
offboardingStatus:
description: Null when the employee has no offboarding.
anyOf:
- type: string
enum:
- PENDING
- SCHEDULED
- IN_PROGRESS
- CLOSED
- CANCELED
- type: 'null'
deviceIds:
description: Ids of the devices assigned to the employee.
type: array
items:
type: string
accessoryIds:
description: Ids of the accessories assigned to the employee.
type: array
items:
type: string
createdAt:
type: string
format: date-time
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
updatedAt:
type: string
format: date-time
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
required:
- id
- firstName
- lastName
- email
- teams
- jobs
- groups
- onboardingStatus
- offboardingStatus
- deviceIds
- accessoryIds
- createdAt
- updatedAt
additionalProperties: false
pagination:
type: object
properties:
totalElements:
type: integer
minimum: 0
maximum: 9007199254740991
totalPages:
type: integer
minimum: 0
maximum: 9007199254740991
page:
type: integer
minimum: 1
maximum: 9007199254740991
perPage:
type: integer
minimum: 1
maximum: 100
required:
- totalElements
- totalPages
- page
- perPage
additionalProperties: false
required:
- data
- pagination
additionalProperties: false
securitySchemes:
apikey:
scheme: bearer
bearerFormat: API key
type: http
description: >-
Use your Primo API key in the Authorization header as `Bearer
`.
````