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-api.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

If you have the client-admin role on a company, you can self-serve your own key from the API Keys portal. Otherwise, your key is issued when your integration is provisioned; contact the Netchex Integrations team to get one. See Authentication for details on both key types.

Your First Request

Verify your key works by listing your organizations. This call works with both Client API keys and Integration keys:

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

const response = await fetch(
  'https://external-api.netchexonline.net/organizations?api-version=3.0',
  {
    headers: {
      'X-API-KEY': 'YOUR_API_KEY',
      'Accept': 'application/json',
    },
  }
);
const organizations = await response.json();
console.log(response.status, organizations.items.length);

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

var response = await client.GetAsync(
    "https://external-api.netchexonline.net/organizations?api-version=3.0");
var organizations = await response.Content.ReadFromJsonAsync<PagedResponse<OrganizationResponse>>();
Console.WriteLine($"{(int)response.StatusCode} {organizations?.Items?.Count ?? 0}");

Try it directly in the API Reference.

A 200 means your key authenticated. A key with no accessible companies still gets a 200 with an empty items array. A successful response looks like:

{
  "pageNumber": 1,
  "pageSize": 50,
  "totalItemsCount": 1,
  "items": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Acme Corporation",
      "companies": [
        { "id": 101, "code": "ACME", "name": "Acme Corp" }
      ]
    }
  ]
}

Response Format

Paginated lists

Endpoints returning collections use a PagedResponse<T> envelope:

{
  "pageNumber": 1,
  "pageSize": 100,
  "totalItemsCount": 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
• Glossary: what a time punch, direct-entry earning, and other domain terms mean