Get Consumer

Overview

The Get Consumer endpoint retrieves a single consumer record by consumer_id.

Business value

This endpoint gives applications a reliable way to fetch one consumer for profile screens, enrollment, and eligibility checks. It returns core demographic data by default and lets you expand the response only when you need contact, employment, citizenship, identification, or protected personal data.

Features

• Retrieve one consumer by UUID.
• Return a small default response with core demographics.
• Expand optional sections such as addresses, phone numbers, and employment.
• Control SSN presentation with ssn_mode when protected personal data is requested.
• Use X-Request-Id to trace a request across your systems.

Use Cases

• Load a consumer profile page.
• Fill enrollment forms or account screens with known consumer data.
• Retrieve limited contact data without always exposing protected personal data.
• Request additional sections only when a business process requires them.

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 not allowed to access the resource.

Core Concepts

Consumer Resource Model

This endpoint returns a single Consumer identified by the consumer_id path parameter. The default response focuses on core demographic data, and the operation does not define filtering, sorting, or search parameters.

Consumer Data Model

The 200 OK response uses the Consumerschema. Required fields in a successful response are:

• consumer_id (uuid)
• first_name
• last_name
• gender
• marital_status

Optional fields may include middle_name, addresses, email_addresses, phone_numbers, protected_personal_data, citizenship, identification, and employment.

Use the expand query parameter to request optional sections. The contract documents these values:

• ADDRESSES
• PHONE_NUMBERS
• PROTECTED_PERSONAL_DATA
• EMAIL_ADDRESSES
• CITIZENSHIP
• IDENTIFICATION
• EMPLOYMENT

When PROTECTED_PERSONAL_DATA is expanded, ssn_mode controls the SSN representation:

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

Consumer Retrieval Workflow

Call this endpoint without expandto get the default response. Call it again with only the expand values you need. If you request PROTECTED_PERSONAL_DATA, choose the ssn_mode that fits your use case.

Common Use Cases

1. Retrieve default consumer demographics

Example request

curl --request GET \
  --url 'https://platform.sandbox.wexglobal.com/api/v1/consumers/A1B20000-0000-0000-0000-000000000000' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Request-Id: 6f7d4f3b-bf9a-4b68-a4b2-3a4f8adfb001'

Example response

{
  "consumer_id": "A1B20000-0000-0000-0000-000000000000",
  "first_name": "John",
  "middle_name": "Michael",
  "last_name": "Doe",
  "gender": "MALE",
  "marital_status": "MARRIED"
}

2. Retrieve expanded contact and protected personal data

Example request

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

Example response

{
  "consumer_id": "A1B20000-0000-0000-0000-000000000000",
  "first_name": "John",
  "middle_name": "Michael",
  "last_name": "Doe",
  "gender": "MALE",
  "marital_status": "MARRIED",
  "addresses": {
    "home_address": {
      "line1": "123 Main Street",
      "line2": "Apt 4B",
      "city": "Portland",
      "state": "ME",
      "zip_code": "04101",
      "country": "US"
    }
  },
  "email_addresses": {
    "primary": {
      "address": "john.doe@example.com"
    }
  },
  "protected_personal_data": {
    "social_security_number": "1234",
    "date_of_birth": "2012-01-13",
    "date_of_death": null
  }
}

Pagination

Pagination does not apply to this endpoint because it returns a single consumer resource.

Error Handling

HTTP status codes

• 200 OK: consumer returned successfully
• 400 Bad Request: invalid query parameters
• 401 Unauthorized: authentication failed
• 403 Forbidden: caller lacks permission
• 404 Not Found: no consumer 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 ProblemDetailsschema 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/consumers/A1B20000-0000-0000-0000-000000000000"
}

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.