Get Person

Overview

The Get Person endpoint retrieves a single person record by its unique identifier.

Business Value

This endpoint lets you look up a person by ID without knowing whether the ID belongs to a consumer or a business contact. Use it to load a basic profile and decide which API or screen to use next.

Features

• Retrieve a person by unique identifier.

• Search across consumers and business contacts.

• Return a small, stable response for basic person data.

• Use X-Request-Id to trace a request across your systems.

• Enforce read access through the documented security requirements.

Use Cases

• Resolve a person ID to a basic profile record.

• Fill a screen with basic person details before calling a more specific API.

• Determine whether a person is a CONSUMER or BUSINESS_CONTACT.

• Route a user from a shared people list to the right next step.

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

Person Resource Model

This endpoint returns a single Person identified by the person_id path parameter.

• person_id (path, required, uuid): the unique person identifier to retrieve

Per the operation description, the service searches across consumers and business contacts when resolving the supplied person_id.

Person Data Model

The 200 OK response uses the Person schema. Required fields are:

• person_id

• business_id

• first_name

• last_name

• type

Optional fields include middle_name.

The typefield identifies the entity category. The OpenAPI schema documents these values:

• CONSUMER

• BUSINESS_CONTACT

Person Lookup Workflow

Call this endpoint with person_id, inspect the returned type, and then route the user to the right consumer or business-contact flow. This endpoint does not define filtering, sorting, expansion, or pagination parameters.

Common Use Cases

1. Retrieve a person record

Example request

curl --request GET \
  --url 'https://platform.sandbox.wexglobal.com/api/v1/persons/A1B20000-0000-0000-0000-000000000000' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Request-Id: 60d8f56d-0ac0-4588-b47d-8e1fbbfe1001'

Example response

{
  "person_id": "A1B20000-0000-0000-0000-000000000000",
  "business_id": "B2C30000-0000-0000-0000-000000000000",
  "first_name": "John",
  "middle_name": "Michael",
  "last_name": "Doe",
  "type": "CONSUMER"
}

2. Use the person type to choose the next step.

Applications can use the returned type field to decide whether to route the user into a consumer flow or a business-contact flow.

Example Response

{
  "person_id": "A1B20000-0000-0000-0000-000000000000",
  "business_id": "B2C30000-0000-0000-0000-000000000000",
  "first_name": "Jane",
  "last_name": "Smith",
  "type": "BUSINESS_CONTACT"
}

Pagination

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

Error Handling

HTTP status codes

• 200 OK: person returned successfully

• 400 Bad Request: invalid request parameters

• 401 Unauthorized: authentication failed

• 403 Forbidden: caller lacks permission

• 404 Not Found: no person found for the supplied person_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

{
  "type": "https://example.com/probs/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "The request contains invalid parameters",
  "instance": "/api/v1/persons/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.