Employee Write-Back

Update an employee's work location, or schedule a termination, from your system.

Sync Employees covers reading employee data out of Netchex. This guide covers the other direction: a couple of employee fields your system can write back to Netchex.

Both endpoints on this page are in the beta API group (api-version=3.0-beta), not stable v3. Schema and behavior may still change here, talk to your Netchex representative before building against these for production.

Update work location

Assign an employee to a specific location by ID, or mark them as working from home. Look up valid location IDs with GET /locations first.

Request

PUT https://external-app-prod.netchexonline.net/employees/work-locations?api-version=3.0-beta
Authorization: ApiKey YOUR_API_KEY
Content-Type: application/json

Request body

{
  "items": [
    { "employeeId": 5001, "locationId": 3 },
    { "employeeId": 5002, "isWorkFromHome": true }
  ]
}

Each item specifies exactly one of locationId or isWorkFromHome, not both. Up to 100 items per request.

Response (200)

{
  "totalSucceeded": 2,
  "totalFailed": 0,
  "errors": []
}

Items for employees that don't exist or belong to companies you don't have access to are silently excluded rather than erroring individually. If nothing remains after filtering, the whole request returns 404.

Schedule a termination

Request

PUT https://external-app-prod.netchexonline.net/employees/5001/terminate?api-version=3.0-beta
Authorization: ApiKey YOUR_API_KEY
Content-Type: application/json

Request body

{
  "terminationDate": "2024-02-01",
  "reasonId": 4,
  "terminationType": "Voluntary",
  "includeInPayroll": true
}

Field	Required	Notes
`terminationDate`	Yes	When the termination takes effect
`reasonId`	Yes	Must be greater than 0, one of your company's configured termination reasons
`terminationType`	No	Distinguishes a voluntary resignation from an involuntary termination
`includeInPayroll`	No	Defaults to `true`. Whether the employee stays in payroll runs through the termination date

This is scheduled, not immediate. It takes effect on terminationDate and is processed the next time the employee's status is refreshed on or after that date. The response is 202 Accepted, not 200.

This covers the common fields, but Netchex tracks a fair amount more about a termination than this endpoint exposes today: COBRA eligibility and the qualifying event date, FMLA status, whether deductions stay active, whether a termination payroll run starts immediately, and manager reassignment. If your integration needs any of that, talk to your Netchex representative before assuming this endpoint alone covers your case.

Create a new hire

This is a v1 endpoint, not yet in the beta group above, and not previously covered by this guide. Schema and behavior may still change — talk to your Netchex representative before building against it for production.

If your system is the source of truth for a hiring decision — an applicant tracking system marking a candidate hired, for example — this endpoint creates that person directly as a Netchex employee, instead of someone re-typing them in by hand. Accepts a batch:

Request

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

Request body — fields we care about most, the ones with no reasonable default

[
  {
    "sourceSystemEmployeeId": "your system's own id for this person, for idempotent retries",
    "companyId": 101,
    "departmentId": 10,
    "firstName": "Jane",
    "lastName": "Smith",
    "socialSecurityNumber": "XXX-XX-XXXX",
    "birthDate": "1990-03-15",
    "sex": "string",
    "streetAddress1": "100 Main St",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "position": "free text, e.g. job title",
    "hireDate": "2024-02-01"
  }
]

A handful of other fields (location, job code, employee type, payroll group/schedule, tax classification, pay amount, manager) can also be set directly, but may instead be auto-filled by your company's configured Position Attributes if you don't have a source for them — talk to your Netchex representative about whether that's set up for you.

Response (200)

[
  {
    "isSuccess": true,
    "messages": [],
    "objectInstance": { "employeeCode": "E001", "sourceSystemEmployeeId": "...", "companyId": 101, "...": "the rest of the request fields, echoed back" }
  }
]

The response is a per-record result array, not an all-or-nothing batch — check isSuccess and messages on each item rather than assuming the whole request succeeded or failed together.

Try it in the playground

Test these endpoints interactively in the API reference:

Employee Write-Back

Update work location

Schedule a termination

Create a new hire

Try it in the playground

On this page