Developer Guide Navigation

• Getting Started
• HR: Employee Compliance

Getting Started

Everything you need to authenticate with the HCM API and start making requests.

Prerequisites — System Setup Required

Authentication

HCM uses IdentityServer4 (OpenID Connect / OAuth 2.0) as its central authentication service. All four API services (Main, Timetracking, Payroll, Billing) authenticate through the same Identity Server. The primary grant type for API integrations is Resource Owner Password — you exchange a username, password, and client credentials for a JWT bearer token.

curl -X POST https://identity.myhcit.com/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "username=YOUR_USERNAME" \
  -d "password=YOUR_PASSWORD" \
  -d "scope=openid profile hcmwebapiserver" \
  -d "companyId=YOUR_COMPANY_ID"

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 2400,
  "token_type": "Bearer",
  "scope": "openid profile hcmwebapiserver"
}

Include the token in the Authorization header using the Bearer scheme. The same token works for any endpoint within the scope you requested.

curl -X GET https://api.myhcit.com/api/leads \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json"

Scopes & API Clients

Each HCM API service has its own client credentials and scopes. You need a separate token for each API service you want to call — a token scoped to hcmwebapiserver will not work for the Payroll API.

Additional scopes you can request alongside the primary scope:

openid — OpenID Connect identity profile — User profile claims roles — User role claims report.read — Reporting API access

Token Claims

The JWT access token contains these claims that the API uses to determine identity and authorization:

Swagger / OpenAPI Explorer

Each HCM API exposes a Swagger UI for interactive exploration and testing. The Swagger UI is available at /swagger on each API's base URL.

Authenticating in Swagger: Swagger accepts your access token via a query parameter or the authorize button. You can pass the token as ?access_token=YOUR_TOKEN in the URL, or use the Bearer Authorization header in the Swagger UI's authorize dialog.

Common Authentication Errors

Environments

HCM provides separate testing and production environments for each service. Use the toggle in the top bar to switch all URLs in this guide between environments.

API Conventions

Pagination

Most list endpoints accept pageSize and currentPage query parameters. Responses include pagination metadata alongside the result set using the structure: { currentPage, pageSize, totalInSearchResult, data: [...] }.

Sorting

Pass a sortingOptions array in the request body with objects containing { columnName, direction } where direction is Asc or Desc.

Date Format

All dates use ISO 8601 format: 2026-01-15T08:00:00

Standard Response Wrapper

Many endpoints return responses wrapped in an OperationResult pattern: { isSuccess: true, message: "", data: {...} }

Error Responses

The API uses standard HTTP status codes:

{
  "currentPage": 1,
  "pageSize": 25,
  "totalInSearchResult": 148,
  "data": [
    {
      "id": 1042,
      "firstName": "Jane",
      "lastName": "Doe",
      "status": "Active"
    },
    // ... more results
  ]
}

{
  "isSuccess": false,
  "message": "Validation failed",
  "errors": [
    {
      "field": "firstName",
      "message": "First name is required."
    },
    {
      "field": "dateOfBirth",
      "message": "Date of birth must be a valid ISO 8601 date."
    }
  ]
}

User Info

{
  "userId": 4821,
  "displayName": "Maria Garcia",
  "email": "maria.garcia@example.com",
  "currentCompanyId": 12,
  "currentCompanyName": "Sunrise Home Health",
  "tenantCode": "SUNRISEHH",
  "userRoles": [
    "Administrator",
    "Scheduler",
    "BillingManager"
  ],
  "permissions": [
    "leads.read",
    "leads.write",
    "referrals.read",
    "referrals.write",
    "scheduling.read",
    "scheduling.write",
    "billing.read",
    "billing.write",
    "payroll.read"
  ]
}