Get employees | Deel. PayAndBill API Documentation

Employees

Retrieves a paginated list of employees for the authenticated tenant.

Method: GET Endpoint: {{baseUrl}}/employees/list

Authentication

This request requires a Bearer token passed via the Authorization header:

Authorization: Bearer {{bearerToken}}

Headers

Header	Value	Description
`Accept`	`application/json`	Specifies the expected response format
`vnd.a1.tenant-id`		Tenant identifier for multi-tenant environments

Query Parameters

Parameter	Type	Required	Description	Example
`page`	number	No	Page number for pagination	`1`
`limit`	number	No	Number of results per page	`20`
`sortColumn`	string	No	Column to sort results by	`lastName`, `firstName`
`sortOrder`	string	No	Sort direction	`asc`, `desc`
`statusFilter`	string/number	No	Filter employees by status	`1` (active)
`searchCol`	string	No	Column to search on	`lastName`
`searchVal`	string	No	Value to search for	`mark`
`payCycleId`	string	No	Filter results by pay cycle ID	`payCycleId`

Response

Returns a paginated response object containing an array of employee records and pagination metadata.

Pagination Metadata

Field	Type	Description
`totalCount`	number	Total number of employees matching the query
`totalPages`	number	Total number of pages available
`limit`	number	Number of results per page
`currentPage`	number	The current page number

Employee Object Fields

Field	Type	Description
`id`	number	Internal employee ID
`UUID`	string	Unique identifier (UUID) for the employee
`firstName`	string	Employee’s first name
`lastName`	string	Employee’s last name
`middleName`	string	Employee’s middle name
`nameKnowAs`	string	Preferred or known-as name
`name`	string	Full name in `lastName,firstName` format
`primaryemail`	string	Primary email address of the employee
`type`	string	Employment type — `PAYE` or `Subcontractor`
`payType`	string	Pay type — `PAYE` or `Subcontractor`
`employeeStatus`	string	Current status of the employee (e.g. `active`)
`employeeNo`	number	Employee number
`userID`	string	Associated user ID
`activeJobs`	number	Number of currently active job assignments
`inactiveJobs`	number	Number of inactive job assignments
`futureJobs`	number	Number of future job assignments
`engagementUuid`	string	UUID of the associated engagement
`createdAt`	string (ISO 8601)	Timestamp when the employee record was created
`sortColumn`	string	Column used for sorting in the response
`lastSyncStatus`	object	Sync status per category (e.g. `JOB`, `TAX`, `BANK`, `EMPLOYEE`, `PERSONAL`, `ENGAGEMENT`) — each containing `message`, `success`, and `updatedAt`

Example Response

1 {
2   "rows": [
3     {
4       "id": 1000,
5       "UUID": "e2ed0e36-de0f-445e-9340-68974de2664b",
6       "firstName": "John",
7       "lastName": "Doe",
8       "middleName": "",
9       "nameKnowAs": "Johnny",
10       "name": "Doe,John",
11       "primaryemail": "john.doe@example.com",
12       "type": "PAYE",
13       "payType": "PAYE",
14       "employeeStatus": "active",
15       "employeeNo": 0,
16       "userID": "axb6yJYVScrv9t5ZMakNmqQ5",
17       "activeJobs": 6,
18       "inactiveJobs": 0,
19       "futureJobs": 0,
20       "engagementUuid": "a3b3d8a6-49bc-4b68-9745-16818eaf20b5",
21       "createdAt": "2025-12-11T00:47:17.292Z",
22       "sortColumn": "",
23       "lastSyncStatus": {
24         "PERSONAL": { "message": "Employee synced successfully!", "success": true },
25         "ENGAGEMENT": { "message": "Employee synced successfully!", "success": true },
26         "updatedAt": "2026-02-02T04:49:34.453Z"
27       }
28     }
29   ],
30   "totalCount": 1310,
31   "totalPages": 66,
32   "limit": 20,
33   "currentPage": 1
34 }

## Employees Retrieves a paginated list of employees for the authenticated tenant. **Method:** `GET` **Endpoint:** `{{baseUrl}}/employees/list` --- ## Authentication This request requires a Bearer token passed via the `Authorization` header: ``` Authorization: Bearer {{bearerToken}} ``` --- ## Headers | Header | Value | Description | | --- | --- | --- | | `Accept` | `application/json` | Specifies the expected response format | | `vnd.a1.tenant-id` | | Tenant identifier for multi-tenant environments | --- ## Query Parameters | Parameter | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `page` | number | No | Page number for pagination | `1` | | `limit` | number | No | Number of results per page | `20` | | `sortColumn` | string | No | Column to sort results by | `lastName`, `firstName` | | `sortOrder` | string | No | Sort direction | `asc`, `desc` | | `statusFilter` | string/number | No | Filter employees by status | `1` (active) | | `searchCol` | string | No | Column to search on | `lastName` | | `searchVal` | string | No | Value to search for | `mark` | | `payCycleId` | string | No | Filter results by pay cycle ID | `payCycleId` | --- ## Response Returns a paginated response object containing an array of employee records and pagination metadata. ### Pagination Metadata | Field | Type | Description | | --- | --- | --- | | `totalCount` | number | Total number of employees matching the query | | `totalPages` | number | Total number of pages available | | `limit` | number | Number of results per page | | `currentPage` | number | The current page number | ### Employee Object Fields | Field | Type | Description | | --- | --- | --- | | `id` | number | Internal employee ID | | `UUID` | string | Unique identifier (UUID) for the employee | | `firstName` | string | Employee's first name | | `lastName` | string | Employee's last name | | `middleName` | string | Employee's middle name | | `nameKnowAs` | string | Preferred or known-as name | | `name` | string | Full name in `lastName,firstName` format | | `primaryemail` | string | Primary email address of the employee | | `type` | string | Employment type — `PAYE` or `Subcontractor` | | `payType` | string | Pay type — `PAYE` or `Subcontractor` | | `employeeStatus` | string | Current status of the employee (e.g. `active`) | | `employeeNo` | number | Employee number | | `userID` | string | Associated user ID | | `activeJobs` | number | Number of currently active job assignments | | `inactiveJobs` | number | Number of inactive job assignments | | `futureJobs` | number | Number of future job assignments | | `engagementUuid` | string | UUID of the associated engagement | | `createdAt` | string (ISO 8601) | Timestamp when the employee record was created | | `sortColumn` | string | Column used for sorting in the response | | `lastSyncStatus` | object | Sync status per category (e.g. `JOB`, `TAX`, `BANK`, `EMPLOYEE`, `PERSONAL`, `ENGAGEMENT`) — each containing `message`, `success`, and `updatedAt` | ### Example Response ``` json { "rows": [ { "id": 1000, "UUID": "e2ed0e36-de0f-445e-9340-68974de2664b", "firstName": "John", "lastName": "Doe", "middleName": "", "nameKnowAs": "Johnny", "name": "Doe,John", "primaryemail": "john.doe@example.com", "type": "PAYE", "payType": "PAYE", "employeeStatus": "active", "employeeNo": 0, "userID": "axb6yJYVScrv9t5ZMakNmqQ5", "activeJobs": 6, "inactiveJobs": 0, "futureJobs": 0, "engagementUuid": "a3b3d8a6-49bc-4b68-9745-16818eaf20b5", "createdAt": "2025-12-11T00:47:17.292Z", "sortColumn": "", "lastSyncStatus": { "PERSONAL": { "message": "Employee synced successfully!", "success": true }, "ENGAGEMENT": { "message": "Employee synced successfully!", "success": true }, "updatedAt": "2026-02-02T04:49:34.453Z" } } ], "totalCount": 1310, "totalPages": 66, "limit": 20, "currentPage": 1 } ```

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Query parameters

pageintegerOptional

searchColstringOptional

searchValstringOptional

sortColumnanyOptional

sortOrderstringOptional

payCycleIdstringOptional

statusFilteranyOptional

limitanyOptional

Response

Successful Response

rowslist of objects

limitdouble

totalCountdouble

currentPagedouble

totalPagesdouble

Employees

Retrieves a paginated list of employees for the authenticated tenant.

Method: GET Endpoint: {{baseUrl}}/employees/list

Authentication

This request requires a Bearer token passed via the Authorization header:

Authorization: Bearer {{bearerToken}}

Headers

Header	Value	Description
`Accept`	`application/json`	Specifies the expected response format
`vnd.a1.tenant-id`		Tenant identifier for multi-tenant environments

Query Parameters

Parameter	Type	Required	Description	Example
`page`	number	No	Page number for pagination	`1`
`limit`	number	No	Number of results per page	`20`
`sortColumn`	string	No	Column to sort results by	`lastName`, `firstName`
`sortOrder`	string	No	Sort direction	`asc`, `desc`
`statusFilter`	string/number	No	Filter employees by status	`1` (active)
`searchCol`	string	No	Column to search on	`lastName`
`searchVal`	string	No	Value to search for	`mark`
`payCycleId`	string	No	Filter results by pay cycle ID	`payCycleId`

Response

Returns a paginated response object containing an array of employee records and pagination metadata.

Pagination Metadata

Field	Type	Description
`totalCount`	number	Total number of employees matching the query
`totalPages`	number	Total number of pages available
`limit`	number	Number of results per page
`currentPage`	number	The current page number

Employee Object Fields

Field	Type	Description
`id`	number	Internal employee ID
`UUID`	string	Unique identifier (UUID) for the employee
`firstName`	string	Employee’s first name
`lastName`	string	Employee’s last name
`middleName`	string	Employee’s middle name
`nameKnowAs`	string	Preferred or known-as name
`name`	string	Full name in `lastName,firstName` format
`primaryemail`	string	Primary email address of the employee
`type`	string	Employment type — `PAYE` or `Subcontractor`
`payType`	string	Pay type — `PAYE` or `Subcontractor`
`employeeStatus`	string	Current status of the employee (e.g. `active`)
`employeeNo`	number	Employee number
`userID`	string	Associated user ID
`activeJobs`	number	Number of currently active job assignments
`inactiveJobs`	number	Number of inactive job assignments
`futureJobs`	number	Number of future job assignments
`engagementUuid`	string	UUID of the associated engagement
`createdAt`	string (ISO 8601)	Timestamp when the employee record was created
`sortColumn`	string	Column used for sorting in the response
`lastSyncStatus`	object	Sync status per category (e.g. `JOB`, `TAX`, `BANK`, `EMPLOYEE`, `PERSONAL`, `ENGAGEMENT`) — each containing `message`, `success`, and `updatedAt`

Example Response

1 {
2   "rows": [
3     {
4       "id": 1000,
5       "UUID": "e2ed0e36-de0f-445e-9340-68974de2664b",
6       "firstName": "John",
7       "lastName": "Doe",
8       "middleName": "",
9       "nameKnowAs": "Johnny",
10       "name": "Doe,John",
11       "primaryemail": "john.doe@example.com",
12       "type": "PAYE",
13       "payType": "PAYE",
14       "employeeStatus": "active",
15       "employeeNo": 0,
16       "userID": "axb6yJYVScrv9t5ZMakNmqQ5",
17       "activeJobs": 6,
18       "inactiveJobs": 0,
19       "futureJobs": 0,
20       "engagementUuid": "a3b3d8a6-49bc-4b68-9745-16818eaf20b5",
21       "createdAt": "2025-12-11T00:47:17.292Z",
22       "sortColumn": "",
23       "lastSyncStatus": {
24         "PERSONAL": { "message": "Employee synced successfully!", "success": true },
25         "ENGAGEMENT": { "message": "Employee synced successfully!", "success": true },
26         "updatedAt": "2026-02-02T04:49:34.453Z"
27       }
28     }
29   ],
30   "totalCount": 1310,
31   "totalPages": 66,
32   "limit": 20,
33   "currentPage": 1
34 }

$	curl -G https://{{baseurl}}/employees/list \
>	-H "Authorization: Bearer <token>" \
>	-d page=1 \
>	-d searchCol=lastName \
>	-d searchVal=mark \
>	-d sortColumn=firstName \
>	-d sortOrder=asc \
>	-d payCycleId=payCycleId \
>	-d statusFilter=string \
>	-d limit=20

1	{
2	"rows": [
3	{
4	"UUID": "string",
5	"name": "string",
6	"nameKnowAs": "string",
7	"firstName": "string",
8	"middleName": "string",
9	"lastName": "string",
10	"type": "string",
11	"primaryemail": "string",
12	"activeJobs": 3897.095481733628,
13	"inactiveJobs": 870.7854733643571,
14	"futureJobs": 6529.9810807371505,
15	"sortColumn": "string",
16	"employeeStatus": "string",
17	"employeeNo": 7856.346770238092,
18	"userID": "string",
19	"lastSyncStatus": {},
20	"engagementUuid": "string"
21	},
22	{
23	"UUID": "string",
24	"name": "string",
25	"nameKnowAs": "string",
26	"firstName": "string",
27	"middleName": "string",
28	"lastName": "string",
29	"type": "string",
30	"primaryemail": "string",
31	"activeJobs": 9120.026606933587,
32	"inactiveJobs": 5620.367121645473,
33	"futureJobs": 5736.244263552042,
34	"sortColumn": "string",
35	"employeeStatus": "string",
36	"employeeNo": 7257.84784329228,
37	"userID": "string",
38	"lastSyncStatus": {},
39	"engagementUuid": "string"
40	}
41	],
42	"limit": 1454.5715066436537,
43	"totalCount": 6898.647433868347,
44	"currentPage": 8400.848827081789,
45	"totalPages": 3029.429470886813
46	}

1	{
2	"rows": [
3	{
4	"id": 1000,
5	"UUID": "e2ed0e36-de0f-445e-9340-68974de2664b",
6	"firstName": "John",
7	"lastName": "Doe",
8	"middleName": "",
9	"nameKnowAs": "Johnny",
10	"name": "Doe,John",
11	"primaryemail": "john.doe@example.com",
12	"type": "PAYE",
13	"payType": "PAYE",
14	"employeeStatus": "active",
15	"employeeNo": 0,
16	"userID": "axb6yJYVScrv9t5ZMakNmqQ5",
17	"activeJobs": 6,
18	"inactiveJobs": 0,
19	"futureJobs": 0,
20	"engagementUuid": "a3b3d8a6-49bc-4b68-9745-16818eaf20b5",
21	"createdAt": "2025-12-11T00:47:17.292Z",
22	"sortColumn": "",
23	"lastSyncStatus": {
24	"PERSONAL": { "message": "Employee synced successfully!", "success": true },
25	"ENGAGEMENT": { "message": "Employee synced successfully!", "success": true },
26	"updatedAt": "2026-02-02T04:49:34.453Z"
27	}
28	}
29	],
30	"totalCount": 1310,
31	"totalPages": 66,
32	"limit": 20,
33	"currentPage": 1
34	}