Get Authorized Signers

Overview

The Get Authorized Signers endpoint retrieves the authorized signer records associated with a specific consumer.

Business value

This endpoint shows who can act on behalf of a consumer. Use it to display delegated access, account access type, and protected signer data when you need it.

Features

• Retrieve authorized signers for a specific consumer.
• Return a collection of signer 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

• Display authorized signer information in your application.
• Check whether a signer can access protected health information.
• Show account access and signer status before allowing an action on the consumer’s behalf.
• Retrieve protected signer data only when a business process requires 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

Authorized Signer Collection Model

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

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

Authorized Signer Data Model

The 200 OK response uses GetAuthorizedSignersResponse, which contains:

• items: array of AuthorizedSigner

Each AuthorizedSignerrequires these fields:

• first_name
• last_name
• hipaa_authorized
• account_access
• status
• type

Optional fields include middle_name, address, phone, and protected_personal_data.

The OpenAPI schema documents these signer-related enums:

• account_access: NONE, PHI, PHI_AND_ACCOUNT_UPDATES, UNSPECIFIED
• status: ACTIVE, INACTIVE, PENDING, ARCHIVED
• type: AUTHORIZED_SIGNER, POWER_OF_ATTORNEY, AUTHORIZED_REPRESENTATIVE, GUARDIAN, PARENT, CONSERVATOR

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

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

Authorized Signer 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 signer data.

Common Use Cases

1. Retrieve authorized signers for a consumer

Example request

curl --request GET \
  --url 'https://platform.sandbox.wexglobal.com/api/v1/authorized-signers?consumer_id=A1B20000-0000-0000-0000-000000000000' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Request-Id: 9c21f326-a6f7-42b1-9a6f-ec7137d91001'

Example response

{
  "items": [
    {
      "first_name": "John",
      "middle_name": "Michael",
      "last_name": "Doe",
      "hipaa_authorized": false,
      "account_access": "PHI",
      "status": "ACTIVE",
      "type": "POWER_OF_ATTORNEY",
      "address": {
        "line1": "123 Main Street",
        "line2": "Apt 4B",
        "city": "Portland",
        "state": "ME",
        "zip_code": "04101",
        "country": "US"
      },
      "phone": {
        "country_code": "+1",
        "area_code": "555",
        "number": "555-1234",
        "extension": "1234"
      }
    }
  ]
}

2. Retrieve authorized signers with protected personal data

Example request

curl --request GET \
  --url 'https://platform.sandbox.wexglobal.com/api/v1/authorized-signers?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",
      "hipaa_authorized": false,
      "account_access": "PHI",
      "status": "ACTIVE",
      "type": "POWER_OF_ATTORNEY",
      "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: authorized signers returned successfully
• 400 Bad Request: invalid query parameters
• 401 Unauthorized: authentication failed
• 403 Forbidden: caller lacks permission
• 404 Not Found: no authorized signers 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/authorized-signers"
}

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.