Skip to main content

Quickstart Guide

This guide walks you through authenticating with Aptia One and executing your first API call to retrieve participant records in the sandbox environment.

1. Prerequisites​

Before making requests to the Aptia One Public Partner API, obtain your partner credentials from the Aptia Integration Architecture Team:

  • Client ID: Unique client identifier issued by AWS Cognito.
  • Client Secret: Cryptographic secret used for machine-to-machine authentication.
  • Tenant Scope: Your assigned tenant identifier or authorized multi-tenant carrier whitelist.

2. Environment Selection​

All external endpoints adhere to standard REST semantics prefixed with /v1. Choose the appropriate base URL:

  • Sandbox (Recommended for development): https://api.development.aptiaone.com
  • Production: https://api.development.aptiaone.com

3. Step 1: Obtain an OAuth 2.0 Access Token​

The Aptia One API uses OAuth 2.0 Client Credentials Grant. Submit a POST request to the token endpoint:

curl -X POST https://auth-api-development-us-east-1.auth.us-east-1.amazoncognito.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=aptia/participants.read aptia/enrollments.read aptia/payroll.read"

Token Response​

{
  "access_token": "eyJraWQiOiJ...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "aptia/participants.read aptia/enrollments.read aptia/payroll.read"
}

4. Step 2: Execute Your First API Call​

Use the received access_token as a Bearer token in the Authorization header to query participants:

curl -X GET "https://api.development.aptiaone.com/v1/participants?pageSize=5&pageNumber=1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "X-Correlation-Id: c3f8e02d-98e3-4f91-87a2-bb53d8650172" \
  -H "X-Aptia-Tenant-Id: tenant-001"

Standard Response (200 OK)​

{
  "items": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "tenantId": "tenant-001",
      "ssn": "XXX-XX-1234",
      "firstName": "Jane",
      "lastName": "Doe",
      "dateOfBirth": "1985-04-12",
      "gender": "Female",
      "employmentStatus": "Active",
      "hireDate": "2020-01-15",
      "email": "jane.doe@example.com",
      "dependentsCount": 2,
      "createdAt": "2026-01-10T08:30:00Z",
      "updatedAt": "2026-03-01T14:22:10Z"
    }
  ],
  "totalCount": 1,
  "pageNumber": 1,
  "pageSize": 5,
  "totalPages": 1
}

5. Standard Request Headers​

HeaderRequiredDescription
AuthorizationYesBearer JWT obtained from OAuth token endpoint (Bearer <token>).
AcceptYesapplication/json (or application/problem+json for error handling).
X-Correlation-IdRecommendedUUID propagated across internal microservices for distributed tracing and rapid troubleshooting.
X-Aptia-Tenant-IdOptionalTarget tenant identifier (UUID or human-readable clientOnecode) for multi-tenant carrier partners. For single-tenant partners, tenant binding is configured server-side and automatically enforced without this header.

6. Standard Error Format (RFC 7807)​

When an error occurs, the API returns a structured Problem Details payload with clear guidance:

{
  "type": "https://developer.aptiaone.com/errors/invalid-request",
  "title": "Invalid Request Parameters",
  "status": 400,
  "detail": "Query parameter 'pageSize' must not exceed 100.",
  "instance": "/v1/participants",
  "correlationId": "c3f8e02d-98e3-4f91-87a2-bb53d8650172"
}

7. Next Steps​