Sync Employees

Discover companies, paginate through employees, and maintain external system synchronization.

This guide covers discovering accessible companies, paginating through employees, and maintaining external system synchronization.

See the Glossary for what "connected employee," "employee code," and similar terms mean.

Overview

GET /companies: list accessible companies (v3)
GET /api/Employees: list employees by company (v1)
GET /api/Employees/{id}: fetch a single employee by internal ID (v1)
GET /api/Employees/code/{empCode}: fetch a single employee by employee code (v1)
POST /api/Employees: fetch a batch of employees by internal ID (v1)
GET /api/connected-employees: resolve employees linked across companies (v1)

Step 1: Discover accessible companies

Request

GET https://external-api.netchexonline.net/companies?api-version=3.0
Authorization: ApiKey YOUR_API_KEY

Response (200)

{
  "pageNumber": 1,
  "pageSize": 50,
  "totalItemsCount": 2,
  "items": [
    { "id": 101, "name": "Acme Corp", "code": "ACME", "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "organizationName": "Acme Corporation" },
    { "id": 102, "name": "Acme West", "code": "ACMEW", "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "organizationName": "Acme Corporation" }
  ]
}

Filter to a specific organization using the organization-ids query parameter, or filter to known companies using company-ids.

Step 2: List employees per company

Request

GET https://external-api.netchexonline.net/api/Employees?companyId=101&limit=100&page=0&api-version=1.0
Authorization: ApiKey YOUR_API_KEY

Key parameters:

Parameter	Type	Description
`companyId`	integer	Required. Repeatable, e.g. `?companyId=101&companyId=102`
`limit`	integer	Optional, capped at 500. Omitting it fetches all employees for the company and can be slow for large companies, specifying a limit is recommended
`page`	integer	Optional, 0-based. Ignored if `limit` is omitted or 0

The response is a bare array. Pagination is controlled entirely by limit and page.

Response (200)

[
  {
    "id": 5001,
    "employeeCode": "E001",
    "firstName": "Jane",
    "middleName": null,
    "lastName": "Smith",
    "dateOfBirth": "1990-03-15",
    "currentEmploymentStatus": "Active",
    "hireDate": "2021-03-15",
    "terminationDate": null,
    "companyOrganizationalLocation": { "companyId": 101 },
    "emailAddresses": [{ "address": "jane.smith@acme.com", "type": "Work" }],
    "phoneNumbers": [],
    "gender": "Female",
    "currentAddress": { "streetLineOne": "100 Main St", "streetLineTwo": null, "city": "New York", "county": null, "state": "NY", "zipCode": "10001", "country": null }
  }
]

This is a partial view. The real record is large (identification, employment history, pay information, addresses, phone numbers, managers, and more nested under it), this example only shows the fields most integrations reach for first. See the API Reference for the complete schema.

To page through everything, keep incrementing page (0-based) until a page comes back with fewer than limit results.

Step 3: Fetch a single employee record

Request

# By internal ID
GET https://external-api.netchexonline.net/api/Employees/5001?api-version=1.0

# By employee code
GET https://external-api.netchexonline.net/api/Employees/code/E001?api-version=1.0

Both return 404 if the employee doesn't exist or you don't have access to their company.

Fetch a batch by ID instead

If you already know the internal IDs you need (rather than paging by company), fetch them directly:

Request

POST https://external-api.netchexonline.net/api/Employees?api-version=1.0
Authorization: ApiKey YOUR_API_KEY
Content-Type: application/json

Request body

[5001, 5002, 5003]

A separate POST /api/Employees/ssn endpoint exists for looking up employees by Social Security Number. It's real, but sensitive enough that most integrations shouldn't need it, treat it as a last resort and confirm with your Netchex representative whether your integration actually needs it before using it.

Step 4: Resolve connected employees

Employees who are the same physical person across multiple companies share a connected employee group (also called a Universal ID).

Request

GET https://external-api.netchexonline.net/api/connected-employees?organizationId=a1b2c3d4-e5f6-7890-abcd-ef1234567890&pageNumber=1&pageSize=50&api-version=1.0
Authorization: ApiKey YOUR_API_KEY

This is a v1 endpoint — its query parameters are camelCase (organizationId, companyId, employeeIds, pageNumber, pageSize), not the kebab-case convention used by v3/beta endpoints elsewhere on this site.

Key parameters:

Parameter	Type	Description
`organizationId`	GUID	Required if `companyId` isn't provided
`companyId`	integer	Required if `organizationId` isn't provided
`employeeIds`	integer[]	Optional, up to 1,000
`pageNumber`	integer	Default 1
`pageSize`	integer	Default 50, max 1,000

Response (200)

{
  "pageSize": 50,
  "currentPageNumber": 1,
  "totalNumberOfPages": 1,
  "totalRecords": 1,
  "data": [
    {
      "connectedEmployeeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "organizationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "organizationName": "Acme Corporation",
      "employees": [
        { "firstName": "Jane", "lastName": "Smith", "employeeId": 5001, "employeeCode": "E001", "companyId": 101, "companyName": "Acme Corp" },
        { "firstName": "Jane", "lastName": "Smith", "employeeId": 6002, "employeeCode": "AW-E001", "companyId": 102, "companyName": "Acme West" }
      ]
    }
  ]
}

This endpoint's envelope fields are pageSize/currentPageNumber/totalNumberOfPages/totalRecords/data. Reuse client-side pagination code written for the pageNumber/totalItemsCount/items shape used elsewhere on this site with care.

Try it in the playground

Test these endpoints interactively in the API reference:

Sync Employees

Overview

Step 1: Discover accessible companies

Step 2: List employees per company

Step 3: Fetch a single employee record

Fetch a batch by ID instead

Step 4: Resolve connected employees

Try it in the playground

On this page