> ## Documentation Index
> Fetch the complete documentation index at: https://developer.payrollintegrations.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Employee Data
> Returns a list of employee data for a payroll connection
export const PaginationInfo = ({defaultSortField, sortFields = [], maxLimit = 100, defaultLimit = 20}) => {
return <>
Pagination & Sorting
{(maxLimit || defaultLimit) &&
{defaultLimit && - Default: {defaultLimit}
}
{maxLimit && - Maximum: {maxLimit}
}
}
{sortFields.map(field => {
if (field == defaultSortField || sortFields.length == 1) {
return -
{field} (Default) ;
} else {
return -
{field} ;
}
})}
;
};
export const FilteringInfo = ({fields = []}) => {
const operatorsByType = {
'string': ['eq', 'ne', 'contains', 'not_contains', 'in', 'not_in'],
'text': ['eq', 'ne', 'contains', 'not_contains', 'in', 'not_in'],
'number': ['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'not_in'],
'numeric': ['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'not_in'],
'integer': ['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'not_in'],
'date': ['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'not_in'],
'datetime': ['eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'not_in'],
'boolean': ['eq', 'ne'],
'uuid': ['eq', 'ne', 'in', 'not_in']
};
const getOperators = field => {
const baseType = field.type.toLowerCase().replace('?', '');
const isNullable = field.type.includes('?') || field.nullable;
const baseOperators = field.operators || operatorsByType[baseType] || ['eq', 'ne'];
return isNullable ? [...baseOperators, 'empty', 'not_empty'] : baseOperators;
};
return <>
Filtering
{fields.map(field => {
const operators = getOperators(field);
return -
{field.name}: {operators.map(op => {op}).reduce((prev, curr) => [prev, ', ', curr])}
;
})}
;
};
The `employeeSummary` field will be `null` when an employee has multiple profiles. In that case, query the individual profiles using the `employeeProfiles` array to retrieve the full employee data for each profile.
## OpenAPI
````yaml api-reference/openapi.demo.json GET /v1/payroll-connections/{payroll_connection}/employee-data
openapi: 3.0.3
info:
title: Payroll Integrations Public API
version: 1.0.0
description: Public API for Payroll Integrations platform
license:
name: MIT
servers:
- url: https://demo1-api.payrollintegrationsdemo.com
description: Demo
- url: https://demo2-api.payrollintegrationsdemo.com
description: Demo
- url: https://demo3-api.payrollintegrationsdemo.com
description: Demo
security: []
tags:
- name: auth
- name: employer-identifiers
- name: meta
- name: payroll-connections
- name: payroll-platforms
- name: roles
- name: users
- name: webhooks
paths:
/v1/payroll-connections/{payroll_connection}/employee-data:
get:
tags:
- payroll-connections
description: Returns a list of employee data for a payroll connection
operationId: get_v1_payroll_connections_payroll_connection_employee_data
parameters:
- name: payroll_connection
in: path
required: true
schema:
description: ID of the payroll connection
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
description: ID of the payroll connection
example: 00000000-0000-0000-0000-000000000000
- name: limit
in: query
required: false
schema:
description: Maximum number of records to return
type: integer
minimum: 1
maximum: 4294967295
description: Maximum number of records to return
- name: offset
in: query
required: false
schema:
description: Number of records to skip from the beginning
type: integer
minimum: 0
maximum: 4294967295
description: Number of records to skip from the beginning
- name: sort
in: query
required: false
schema:
description: >-
Comma-separated list of fields to sort by. Prefix with - for
descending order
type: string
pattern: ^(-?\w{1,100})(?:,(-?\w{1,100})){0,2}$
description: >-
Comma-separated list of fields to sort by. Prefix with - for
descending order
responses:
'200':
description: Employee data retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ListPayrollConnectionEmployeeDataResponse'
example:
data:
- id: 11111111-1111-1111-1111-111111111111
employeeProfiles:
- id: aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa
employeeSummary:
addresses:
- address1: 123 Main St
address2: Apt 4B
city: San Francisco
countryCode: US
state: CA
zip: '94102'
adjustedServiceDate: null
contact:
emailPersonal: null
emailWork: john.doe@example.com
phoneNumberPersonal: null
phoneNumberPersonalHome: null
phoneNumberPersonalMobile: '+11235550123'
phoneNumberWork: null
phoneNumberWorkHome: null
phoneNumberWorkMobile: null
dateOfBirth: '1985-06-15'
employmentStatus: A
employmentType: F
firstName: John
hireDate: '2020-03-15'
isContractor: false
lastName: Doe
leaveEndDate: null
leaveStartDate: null
maritalStatus: M
middleName: Robert
payFrequency: BI_WEEKLY
payRates:
- amount: '75000.00'
default: true
type: ANNUAL
payrollConnectionId: 00000000-0000-0000-0000-000000000000
payrollPlatformDisplayIdentifier: EMP-12345
payrollPlatformEmployeeIdentifier: PPL-98765
payType: S
rehireDate: null
seniorityDate: '2020-03-15'
sex: M
ssn: 123-45-6789
terminationDate: null
updatedAt: '2024-03-15T14:30:00Z'
- id: 22222222-2222-2222-2222-222222222222
employeeProfiles:
- id: bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb
- id: cccccccc-cccc-cccc-cccc-cccccccccccc
employeeSummary: null
updatedAt: '2024-03-15T14:30:00Z'
meta:
currentCount: 2
filters:
updatedAt:
gte: '2024-01-01T00:00:00Z'
limit: 20
offset: 0
sort: lastName
totalCount: 2
headers:
Link:
schema:
type: string
pattern: >-
^(?:<[^>]+>;\s*rel="(?:self|first|last|prev|next)"(?:,\s+<[^>]+>;\s*rel="(?:self|first|last|prev|next)")*)$
'400':
description: Invalid request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Invalid or missing token
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
headers:
WWW-Authenticate:
schema:
description: Authentication challenge (Bearer)
type: string
description: Authentication challenge (Bearer)
'403':
description: Insufficient permissions or access denied
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
headers:
Retry-After:
schema:
description: Number of seconds to wait before retrying
type: string
description: Number of seconds to wait before retrying
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- bearerAuth: []
components:
schemas:
ListPayrollConnectionEmployeeDataResponse:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
description: Payroll Integrations employee specific uuid
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
employeeProfiles:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
required:
- id
additionalProperties: false
updatedAt:
description: ISO 8601 timestamp when the employee data was updated
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|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
employeeSummary:
description: >-
Summary of the employee data. Populated when there is a single
profile, null when there are multiple profiles.
nullable: true
type: object
properties:
addresses:
type: array
items:
type: object
properties:
address1:
nullable: true
type: string
address2:
nullable: true
type: string
city:
nullable: true
type: string
countryCode:
nullable: true
type: string
state:
nullable: true
type: string
zip:
nullable: true
type: string
required:
- address1
- address2
- city
- countryCode
- state
- zip
additionalProperties: false
adjustedServiceDate:
description: >-
Adjusted date of when the employee's service began in case
of transfers, leaves of absence, etc. in ISO format
YYYY-MM-DD
nullable: true
type: string
format: date
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])))$
contact:
type: object
properties:
emailPersonal:
nullable: true
type: string
emailWork:
nullable: true
type: string
phoneNumberPersonal:
nullable: true
type: string
phoneNumberPersonalHome:
nullable: true
type: string
phoneNumberPersonalMobile:
nullable: true
type: string
phoneNumberWork:
nullable: true
type: string
phoneNumberWorkHome:
nullable: true
type: string
phoneNumberWorkMobile:
nullable: true
type: string
required:
- emailPersonal
- emailWork
- phoneNumberPersonal
- phoneNumberPersonalHome
- phoneNumberPersonalMobile
- phoneNumberWork
- phoneNumberWorkHome
- phoneNumberWorkMobile
additionalProperties: false
dateOfBirth:
description: Date of Birth in ISO format YYYY-MM-DD
nullable: true
type: string
format: date
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])))$
employmentStatus:
anyOf:
- description: Active
type: string
enum:
- A
nullable: true
- description: Terminated
type: string
enum:
- T
nullable: true
- description: Deceased
type: string
enum:
- C
nullable: true
- description: Disabled
type: string
enum:
- D
nullable: true
- description: Retired
type: string
enum:
- R
nullable: true
- description: Leave of Absence
type: string
enum:
- L
nullable: true
employmentType:
anyOf:
- description: Full time
type: string
enum:
- F
nullable: true
- description: Part time
type: string
enum:
- P
nullable: true
- description: Temporary
type: string
enum:
- T
nullable: true
- description: Intern
type: string
enum:
- I
nullable: true
- description: Seasonal
type: string
enum:
- S
nullable: true
- description: Contractor
type: string
enum:
- C
nullable: true
firstName:
nullable: true
type: string
hireDate:
description: Hire Date in ISO format YYYY-MM-DD
nullable: true
type: string
format: date
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])))$
isContractor:
nullable: true
type: boolean
lastName:
nullable: true
type: string
leaveEndDate:
description: Leave End Date in ISO format YYYY-MM-DD
nullable: true
type: string
format: date
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])))$
leaveStartDate:
description: Leave Start Date in ISO format YYYY-MM-DD
nullable: true
type: string
format: date
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])))$
maritalStatus:
anyOf:
- description: Divorced
type: string
enum:
- D
nullable: true
- description: Married
type: string
enum:
- M
nullable: true
- description: Single
type: string
enum:
- S
nullable: true
- description: Widowed
type: string
enum:
- W
nullable: true
- description: Head of House
type: string
enum:
- H
nullable: true
- description: Domestic Partner
type: string
enum:
- P
nullable: true
middleName:
nullable: true
type: string
payFrequency:
description: >-
The frequency at which the employee is paid. Used to
calculate pay period amount from annual salary amount or
vice versa.
anyOf:
- type: string
enum:
- DAILY
nullable: true
- type: string
enum:
- WEEKLY
nullable: true
- type: string
enum:
- BI_WEEKLY
nullable: true
- type: string
enum:
- SEMI_MONTHLY
nullable: true
- type: string
enum:
- MONTHLY
nullable: true
- type: string
enum:
- QUARTERLY
nullable: true
- type: string
enum:
- YEARLY
nullable: true
- type: string
enum:
- UNSCHEDULED
nullable: true
payRates:
nullable: true
type: array
items:
type: object
properties:
amount:
nullable: true
type: string
default:
description: >-
Indicates if this is the default pay rate for the
employee.
nullable: true
type: boolean
type:
anyOf:
- type: string
enum:
- PER_PAY_PERIOD
nullable: true
- type: string
enum:
- ANNUAL
nullable: true
- type: string
enum:
- HOURLY
nullable: true
- type: string
enum:
- DAILY
nullable: true
- type: string
enum:
- WEEKLY
nullable: true
- type: string
enum:
- MONTHLY
nullable: true
- type: string
enum:
- PIECEWORK
nullable: true
- type: string
enum:
- SEMI_MONTHLY
nullable: true
- type: string
enum:
- BI_WEEKLY
nullable: true
required:
- amount
- default
- type
additionalProperties: false
payrollConnectionId:
type: string
format: uuid
pattern: >-
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
payrollPlatformDisplayIdentifier:
description: The payroll platform specific display employee identifier.
nullable: true
type: string
payrollPlatformEmployeeIdentifier:
description: The payroll platform specific unique employee identifier.
type: string
payType:
description: >-
Denotes whether the employee is salaried or paid an hourly
wage.
anyOf:
- description: Hourly
type: string
enum:
- H
nullable: true
- description: Salaried
type: string
enum:
- S
nullable: true
rehireDate:
description: Rehire Date in ISO format YYYY-MM-DD
nullable: true
type: string
format: date
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])))$
seniorityDate:
description: Seniority Date in ISO format YYYY-MM-DD
nullable: true
type: string
format: date
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])))$
sex:
anyOf:
- type: string
enum:
- M
nullable: true
- type: string
enum:
- F
nullable: true
ssn:
description: 'Social security number in the format ###-##-####'
nullable: true
type: string
terminationDate:
description: Termination Date in ISO format YYYY-MM-DD
nullable: true
type: string
format: date
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])))$
required:
- addresses
- adjustedServiceDate
- contact
- dateOfBirth
- employmentStatus
- employmentType
- firstName
- hireDate
- isContractor
- lastName
- leaveEndDate
- leaveStartDate
- maritalStatus
- middleName
- payFrequency
- payRates
- payrollConnectionId
- payrollPlatformDisplayIdentifier
- payrollPlatformEmployeeIdentifier
- payType
- rehireDate
- seniorityDate
- sex
- ssn
- terminationDate
additionalProperties: false
required:
- id
- employeeProfiles
- updatedAt
- employeeSummary
additionalProperties: false
meta:
type: object
properties:
currentCount:
description: Number of results in current page
type: integer
minimum: 0
maximum: 4294967295
filters:
description: Applied filters with field names and operators
type: object
additionalProperties:
type: object
properties:
eq:
type: string
ne:
type: string
gt:
type: string
gte:
type: string
lt:
type: string
lte:
type: string
in:
type: array
items:
type: string
not_in:
type: array
items:
type: string
like:
type: string
not_like:
type: string
contains:
type: string
not_contains:
type: string
empty:
type: string
not_empty:
type: string
additionalProperties: false
limit:
description: Maximum number of results per page
type: integer
minimum: 0
maximum: 4294967295
offset:
description: Number of results to skip
type: integer
minimum: 0
maximum: 4294967295
sort:
description: Sort order
type: string
pattern: ^(-?\w{1,100})(?:,(-?\w{1,100})){0,2}$
totalCount:
description: Total number of results
type: integer
minimum: 0
maximum: 9007199254740991
required:
- currentCount
- filters
- limit
- offset
- sort
- totalCount
additionalProperties: false
required:
- data
- meta
additionalProperties: false
ErrorResponse:
type: object
properties:
message:
description: Human-readable error message
type: string
errors:
description: Array of specific error details
type: array
items:
type: string
required:
- message
- errors
additionalProperties: false
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
Bearer token obtained from the /v1/auth/token endpoint. Send as:
Authorization: Bearer .
````