Developers

Request Access

Contact our Service Team to initiate an access request.

Include the following:

• The company codes you are requesting access to
• The APIs and web-hooks you are requesting access to
• If you already have one, your existing API access code

Our team will reply with further instructions and your access credentials.

Support

At this time, Netchex does not offer custom development capabilities, but we do offer technical support. Support requests initiated through the Netchex Service Team may be upgraded to any of the support options below from the Netchex Engineering team.

Included Support

Access to APIs, web-hooks, and online help resources is included with your Netchex purchase.

Enhanced Support

Enhanced support grants email and remote assistance from a Netchex engineer. This includes:

• Explaining the technical functionality of Netchex services
• Configuring test environments
• Reviewing client integration implementation and suggesting improvements
• Assistance with debugging client implementations

Support does not include:

• Executing tests
• Custom development
• Fixing bugs in Netchex APIs

Response time: 1 to 5 business days

Availability: 9:00 A.M. to 3:00 P.M. central time, Monday – Friday

Pricing: $300 / hour of support, purchasable in 5 hour blocks

Contact our Service Team to initiate a purchase.

API Documentation

• Browse our current APIs here: Open API Browser
  • Base URL for making API calls: https://external-api.netchexonline.net
• Browse our legacy APIs here: Legacy API Browser
  • Base URL for making API calls: https://api.netchexonline.net

Authentication

For Open APIs, use API key authentication. In each request to the Netchex API, include the following header:

Authorization: ApiKey {api-key}

Legacy APIs use basic authentication.

Web-hooks

Netchex uses Azure Event Grid to send web-hook events. Events are POSTed as JSON HTTP requests to your selected endpoint with the following format:

[
  {
    "topic": string,
    "subject": string,
    "id": string,
    "eventType": string,
    "eventTime": string,
    "data":{
      object-unique-to-each-event-type
    },
    "dataVersion": string,
    "metadataVersion": string
  }
]

Property	Type	Description
topic	string	unique identifier for this event stream
subject	string	unique identifier for the subject of the event
id	string in .NET Guid format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	unique identifier for this event
eventType	string	unique identifier for this event type
eventTime	string in ISO 8601 format	date and time of the event
data	object	custom metadata object for the event – see Event Types below
dataVersion	string	schema version of the event message format
metadataVersion	string	schema version of the event metadata format

Web-hook Authentication

You can authenticate the sender of events using a shared secret embedded in a query parameter.

The query parameter will be token, and the value of the parameter will be unique to your account. Check the value on each POST to authenticate.

Web-hook Endpoint Validation

Before receiving events, you must validate your web-hook endpoint. At the time that the webhook endpoint is registered, you’ll receive a validation event with the following format:

[
  {
    "id": "",
    "topic": "",
    "subject": "",
    "data": {
      "validationCode": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "validationUrl": "https://validation-url.com/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    },
    "eventType": "Microsoft.EventGrid.SubscriptionValidationEvent",
    "eventTime": "",
    "metadataVersion": "1",
    "dataVersion": "1"
  }
]

To prove ownership of the endpoint, echo back the validation code in this format:

{
  "validationResponse": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

You must respond with the HTTP 200 response code.

Web-hook Event Types

Each event type is listed below with its properties in list form below it.

Event type: companyPayrollInvoiced

• payrollId: int32 as number
• companyId: int32 as number

Event type: employeeAdded

• employeeId: int64 as number
• companyId: int32 as number

Event type: employeeBenefitCoverageEnded

• employeeBenefitId: int64 as number
• employeeId: int64 as number
• companyId: int32 as number

Event type: employeeBenefitEnrolled

• employeeBenefitId: int64 as number
• employeeId: int64 as number
• companyId: int32 as number

Event type: employeeBenefitUpdated

• employeeBenefitId: int64 as number
• employeeId: int64 as number
• companyId: int32 as number

Event type: employeeDependentAdded

• dependentId: int64 as number
• employeeId: int64 as number
• companyId: int32 as number

Event type: employeeDependentUpdated

• dependentId: int64 as number
• employeeId: int64 as number
• companyId: int32 as number

Event type: employeeEnrollmentCompleted

• employeeId: int64 as number
• companyId: int32 as number

Event type: employeeTerminated

• employeeId: int64 as number
• companyId: int32 as number

Event type: employeeUpdated

• employeeId: int64 as number
• companyId: int32 as number