API Documentation

EPHY API

This page is powered by the generated OpenAPI document and rendered with Swagger UI.

OpenAPI document: /openapi/v1.json

API base path: /api/ephy

Jump to Swagger UI Open raw OpenAPI JSON

Before you begin

Your organization must be provisioned for access to the EPHY API before calling protected endpoints.

Microsoft Entra ID Tenant ID
Client ID
Client Secret
API Base URL
API Scope / Audience

Base URL

All API endpoints are relative to the API host provided during onboarding.

Base path: /api/ephy

Example: https://<api-host>/api/ephy/employees

Current endpoints

Method	Path	Description
`GET`	`/api/ephy/clients`	Returns the list of clients available to the API.
`GET`	`/api/ephy/employees`	Returns employee records with optional filters and cursor-based paging.
`GET`	`/api/ephy/test`	Development and staging only. Returns a simple success response.

Authorization

Protected endpoints under /api/ephy require a bearer token from Microsoft Entra ID.

Send the token in the HTTP header: Authorization: Bearer <access_token>.
The token must be issued for this API's audience.
The token must include the Access_as_application application permission.
If the token is missing, expired, or invalid, the API returns 401 Unauthorized.
If the token is valid but lacks the required permission, the API returns 403 Forbidden.

How to obtain an access token

The EPHY API uses Microsoft Entra ID OAuth 2.0 client credentials flow. Use the Tenant ID, Client ID, Client Secret, and API Scope provided during onboarding.

Token endpoint:

https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token

Required form fields:

client_id: Your assigned application Client ID.
client_secret: Your assigned client secret.
grant_type: client_credentials
scope: api://<api-client-id>/.default

cURL token request:

curl -X POST "https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=<client_id>" \
  -d "client_secret=<client_secret>" \
  -d "grant_type=client_credentials" \
  -d "scope=api://<api-client-id>/.default"

Successful token response:

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ..."
}

Use the returned access_token in the Authorization header when calling protected endpoints.

Example API request:

curl -X GET "https://<api-host>/api/ephy/employees?pageSize=100" \
  -H "Authorization: Bearer <access_token>"

Do not send the client secret in API requests.
Access tokens expire and should be refreshed by requesting a new token.
Store client secrets securely. Do not place secrets in browser JavaScript or public repositories.

Pagination

The /api/ephy/employees endpoint supports cursor-based paging.

pageSize: Number of records to return. Maximum value is 1000.
cursorClientId, cursorEmployeeId, and cursorEmailAddress: values returned in nextCursor for the next request.
clientId: Optional filter for a specific client.
includeTerminated: Include terminated employees when set to true.
isUpdated: Return updated employee records when set to true.

Continue requesting pages until no nextCursor is returned.

Example first request:

GET /api/ephy/employees?pageSize=100

Example next page request:

GET /api/ephy/employees?pageSize=100&cursorClientId=<clientId>&cursorEmployeeId=<employeeId>&

Sample response

Collection endpoints return records and may include a cursor for the next page.

                
                    {
                    "items": [
                    {
                    "firstName": "John",
                    "lastName": "Doe",
                    "emailAddress": "john.doe@example.com",
                    "jobTitle": "Manager",
                    "hireDate": "2026-07-01T14:30:00Z",
                    "status": "Active",
                    "clientName": "Test Company",
                    "city": "Any Town",
                    "state": "Any City",
                    "postalCode": "12345",
                    "remoteOrWorksite": "Worksite",
                    "employeeId": "12345",
                    "clientId": 55555555
                    }
                    ],
                    "nextCursor": {
                    "clientId": 55555555,
                    "employeeId": "12345",
                    "emailAddress": "John.doe@example.com",
                    "nextUrl": "https://ephy.puzzlehr.com/api/ephy/employees?clientId=15149908884&pageSize=100&includeTerminated=false&isUpdated=false&cursorClientId=55555555&cursorEmployeeId=125"
                    }
                    }

Date format

Dates are returned using ISO 8601 format.

Example: 2026-07-01T14:30:00Z

Error responses

The API uses standard HTTP status codes.

Status Code	Meaning
`200`	Request succeeded.
`400`	The request was invalid or contained unsupported parameters.
`401`	The access token is missing, expired, or invalid.
`403`	The token is valid, but the caller does not have permission to access the requested resource.
`404`	The requested resource was not found.
`429`	Too many requests. Retry after waiting.
`500`	An unexpected server error occurred.

Rate limits

Clients should avoid excessive concurrent requests. If rate limiting is enabled, the API may return 429 Too Many Requests.

Versioning

Current API version: v1
OpenAPI document: /openapi/v1.json
Base path: /api/ephy

C# example

using System.Net.Http.Headers;

var accessToken = "<access_token>";

using var client = new HttpClient();

client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", accessToken);

var response = await client.GetAsync(
    "https://<api-host>/api/ephy/employees?pageSize=100");

response.EnsureSuccessStatusCode();

var json = await response.Content.ReadAsStringAsync();

Console.WriteLine(json);

Support

If you need API credentials, have trouble obtaining a token, or receive authorization errors, contact PuzzleHR Support.