Skip to main content

Automating Participant Census Ingestion

This guide details how HRIS and payroll partners synchronize employee census records and dependent data into Aptia One using the REST API.

Workflow Overview​

1. Create Participant ──► POST /v1/participants
                               │
2. Add Dependents    ──► POST /v1/participants/{id}/dependents
                               │
3. Update Demographics ──► PATCH /v1/participants/{id}
                               │
4. Verify Census State ──► GET  /v1/participants/{id}

1. Creating a Participant Record​

Submit new employee census records via POST /v1/participants:

curl -X POST "https://api.development.aptiaone.com/v1/participants" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Aptia-Tenant-Id: tenant-001" \
  -d '{
    "ssn": "987-65-4321",
    "firstName": "Robert",
    "lastName": "Chen",
    "dateOfBirth": "1990-06-15",
    "gender": "Male",
    "maritalStatus": "Married",
    "employmentStatus": "Active",
    "hireDate": "2024-03-01",
    "email": "robert.chen@example.com",
    "phoneNumber": "+1-555-019-2834",
    "address": {
      "line1": "742 Evergreen Terrace",
      "city": "Springfield",
      "state": "IL",
      "postalCode": "62704",
      "country": "USA"
    }
  }'

Response (201 Created)​

{
  "id": "22222222-2222-2222-2222-222222222222",
  "tenantId": "tenant-001",
  "ssn": "XXX-XX-4321",
  "firstName": "Robert",
  "lastName": "Chen",
  "dateOfBirth": "1990-06-15",
  "gender": "Male",
  "employmentStatus": "Active",
  "hireDate": "2024-03-01",
  "email": "robert.chen@example.com",
  "dependentsCount": 0,
  "createdAt": "2026-10-14T03:50:00Z",
  "updatedAt": "2026-10-14T03:50:00Z"
}

2. Registering Dependents​

Once a participant exists, associate spouses, domestic partners, or children using POST /v1/participants/{participantId}/dependents:

curl -X POST "https://api.development.aptiaone.com/v1/participants/22222222-2222-2222-2222-222222222222/dependents" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Emily",
    "lastName": "Chen",
    "relationship": "Spouse",
    "dateOfBirth": "1992-08-22",
    "gender": "Female",
    "ssn": "987-65-8888"
  }'

Response (201 Created)​

{
  "id": "33333333-3333-3333-3333-333333333333",
  "participantId": "22222222-2222-2222-2222-222222222222",
  "firstName": "Emily",
  "lastName": "Chen",
  "relationship": "Spouse",
  "dateOfBirth": "1992-08-22",
  "gender": "Female",
  "ssnMasked": "XXX-XX-8888",
  "isStudent": false,
  "isDisabled": false,
  "createdAt": "2026-10-14T03:55:00Z",
  "updatedAt": "2026-10-14T03:55:00Z"
}

3. Applying Partial Demographic Updates​

When an employee changes address, email, or marital status, send a PATCH request with only the modified fields:

curl -X PATCH "https://api.development.aptiaone.com/v1/participants/22222222-2222-2222-2222-222222222222" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "robert.chen.updated@example.com",
    "address": {
      "line1": "100 Innovation Way",
      "city": "Chicago",
      "state": "IL",
      "postalCode": "60601",
      "country": "USA"
    }
  }'
Partial Update Safety

Fields omitted from the PATCH body are preserved untouched in the underlying 3X database. Omitted properties are never overwritten or nullified.