Get Dependents

Overview

The Get Dependents endpoint retrieves the dependent records associated with a specific consumer.

Business value

This endpoint returns a consumer’s dependents. Use it for enrollment, eligibility checks, and dependent verification. Add protected personal data only when you need it.

Features

• Retrieve dependents for a specific consumer.
• Return a collection of dependent records in a single response.
• Optionally expand protected personal data.
• Control SSN presentation with ssn_mode.
• Use X-Request-Id to trace a request across your systems.

Use Cases

• Show a consumer’s dependents in your application.
• Check relationship and active status before the next step in your process.
• Determine whether a dependent is marked as a full-time student.
• Retrieve protected dependent data only when you need it.

Scopes & Permissions

• OAuth 2.0 scope: read:persons
• A bearer token may also satisfy the operation through the BearerAuth security scheme in the OpenAPI contract.
• The endpoint returns 403 Forbidden when the caller is authenticated but does not have access to this resource.

Core Concepts

Dependent Collection Model

This endpoint returns the dependents for one consumer. It uses the required consumer_id query parameter rather than a path parameter.

• consumer_id (required, uuid): the consumer whose dependents should be returned.

Dependent Data Model

The 200 OK response uses GetDependentsResponse, which contains:

• items: array of Dependent

Each Dependent requires these fields:

• first_name
• last_name
• full_time_student
• gender
• relationship
• status

Optional fields include middle_name and protected_personal_data.

The OpenAPI schema documents these dependent-related enums:

• gender: UNKNOWN, MALE, FEMALE, NEUTRAL
• relationship: SPOUSE, CHILD, DOMESTIC_PARTNER, OTHER
• status: ACTIVE, INACTIVE, PENDING, ARCHIVED

When protected personal data is requested, ssn_mode controls the SSN representation:

• MASKED (default): xxx-xx-1234
• LAST4: 1234
• UNMASKED: 555441234

Dependent Retrieval Workflow

Call this endpoint with only consumer_id to get the default response. Add expand=PROTECTED_PERSONAL_DATA and the right ssn_mode only when you need protected dependent data.

Common Use Cases

1. Retrieve dependents for a consumer

Example request

curl --request GET \
  --url 'https://platform.sandbox.wexglobal.com/api/v1/dependents?consumer_id=A1B20000-0000-0000-0000-000000000000' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Request-Id: 8a43ef4d-6e37-4459-a55d-8b9fd9421001'

Example resource

{
  "items": [
    {
      "first_name": "John",
      "middle_name": "Michael",
      "last_name": "Doe",
      "full_time_student": false,
      "gender": "MALE",
      "relationship": "SPOUSE",
      "status": "ACTIVE"
    }
  ]
}

2. Retrieve dependents with protected personal data

Example request

curl --request GET \
  --url 'https://platform.sandbox.wexglobal.com/api/v1/dependents?consumer_id=A1B20000-0000-0000-0000-000000000000&expand=PROTECTED_PERSONAL_DATA&ssn_mode=LAST4' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'

Example response

{
  "items": [
    {
      "first_name": "John",
      "middle_name": "Michael",
      "last_name": "Doe",
      "full_time_student": false,
      "gender": "MALE",
      "relationship": "SPOUSE",
      "status": "ACTIVE",
      "protected_personal_data": {
        "social_security_number": "1234",
        "date_of_birth": "2012-01-13"
      }
    }
  ]
}

Pagination

Pagination is not defined for this endpoint in the OpenAPI contract. The response returns a single object with an itemsarray and no page, size, cursor, or total-count fields.

Error Handling

HTTP status codes

• 200 OK: dependents returned successfully
• 400 Bad Request: invalid query parameters
• 401 Unauthorized: authentication failed
• 403 Forbidden: caller lacks permission
• 404 Not Found: no dependents found for the supplied consumer_id
• 500 Internal Server Error: server error; the OpenAPI contract does not define a response schema for this status
• default: unexpected error with ProblemDetails

Problem details format

When the contract defines an error body, it uses the ProblemDetails schema with these fields:

• type
• title
• status
• detail
• instance

Example:

{
  "type": "https://example.com/probs/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "The request contains invalid parameters",
  "instance": "/api/v1/dependents"
}

Idempotency

GETis safe and idempotent. Repeating the same request does not change server state. If you retry after a network issue, you can reuse X-Request-Id to trace the request.