Getting Started

The Netchex External API lets you build integrations with HR, payroll, time, and benefits data. This guide walks you through authentication, making your first request, and understanding the response format.

Base URL

All requests go to:

https://external-app-prod.netchexonline.net

API Versions

The API has three versions. Use the api-version query parameter on every request.

GET /organizations?api-version=3.0

Authentication

Every request must include your API key. Two header formats are accepted:

X-API-KEY: YOUR_API_KEY

Authorization: ApiKey YOUR_API_KEY

Your API key is issued when your integration is provisioned. Contact the Netchex Integrations team to get one.

Your First Request

Verify your key works by fetching your integration account:

curl -X GET "https://external-app-prod.netchexonline.net/accounts/me?api-version=3.0" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"

const response = await fetch(
  'https://external-app-prod.netchexonline.net/accounts/me?api-version=3.0',
  {
    headers: {
      'X-API-KEY': 'YOUR_API_KEY',
      'Accept': 'application/json',
    },
  }
);
const account = await response.json();
console.log(account.applicationName);

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-KEY", "YOUR_API_KEY");

var response = await client.GetAsync(
    "https://external-app-prod.netchexonline.net/accounts/me?api-version=3.0");
var account = await response.Content.ReadFromJsonAsync<AccountResponse>();

A successful response looks like:

{
  "id": 42,
  "applicationName": "My Integration",
  "description": "Syncs employee data to our HR platform",
  "contactEmail": "integrations@example.com",
  "contactFirstName": "Jane",
  "contactLastName": "Doe",
  "logoLink": "https://example.com/logo.png",
  "moreInfoLink": "https://example.com",
  "webhooksEnabled": true
}

Response Format

Paginated lists

Endpoints returning collections use a PagedResponse<T> envelope:

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalItems": 342,
  "items": [ ... ]
}

Use page-number and page-size query parameters to paginate:

GET /organizations?api-version=3.0&page-number=2&page-size=50

See Pagination for full details.

Errors

Errors follow the RFC 9457 Problem Details format:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "start-date is required."
}

See Error Handling for the full list of status codes.

What's Available

Explore the full API Reference for all endpoints, request/response schemas, and a live playground.

Next Steps

• Authentication — API key details and security practices
• Pagination — How to page through large result sets
• Error Handling — Status codes and problem details
• Integrations — Common patterns and recipes