Businesses

Overview

The Businesses resource group provides endpoints for searching and managing Business entities within the WEX Health and Benefits platform.A Business represents an organizational entity – such as an employer, administrator, or plan sponsor – identified by a unique GUID and associated with attributes including a legal name, alias, Employer Identification Number (EIN), and exchange integration identifier.

This resource group contains two endpoints:

Endpoint Summary

Key Concepts

Search vs. Direct Lookup

The Businesses resource does not include a direct GET-by-ID endpoint. To retrieve a specific Business record, use GET /businesses/search with a known name, EIN, or alias to locate the record and obtain its id GUID. Once the GUID is known, it can be used with PUT /businesses/{id}.

Partial Name Matching

GET /businesses/search supports partial name matching. Supplying a fragment of a business name (for example, “Acme”) will return all businesses whose name contains that string. Results are sorted by relevance. EIN and alias filters use exact matching.

Update Semantics (PUT with Partial-Update Behavior)

Despite using the PUT HTTP method, PUT /businesses/{id} behaves as a partial update: only fields included in the request body are changed; omitted fields retain their current values. This differs from standard PUT semantics (which would clear omitted fields) and is more consistent with PATCH behavior.

Practically, this means you do not need to read the full record before updating a single field – only supply the fields you want to change.

HATEOAS Navigation

GET /businesses/search returns HATEOAS links alongside paginated results to support navigation between pages without manually constructing URLs.

EIN Sensitivity

The ein field is a tax identifier (Employer Identification Number). Treat it as sensitive business data. Avoid logging EIN values and handle in accordance with your organization’s data handling policies.

Common Workflows

1. Find a Business by Name, Then Update It
Search by name to locate the business and retrieve its GUID:
GET /businesses/search?name=Acme+Corp


2. Use the GUID from the search result to update the business:


PUT /businesses/{id}
{ "alias": "ACME-001" }


### Find a Business by EIN
Use the `ein` query parameter for a deterministic lookup when the EIN is known:


GET /businesses/search?ein=12-3456789


### Update `exchange_id` After Integration Setup
When a business is connected to a new exchange platform, update its `exchange_id`:


PUT /businesses/{id}
{ "exchange_id": 4419 }



1. Find a Business by Name, Then Update It
Search by name to locate the business and retrieve its GUID:
GET /businesses/search?name=Acme+Corp


2. Use the GUID from the search result to update the business:


PUT /businesses/{id}
{ "alias": "ACME-001" }


### Find a Business by EIN
Use the `ein` query parameter for a deterministic lookup when the EIN is known:


GET /businesses/search?ein=12-3456789


### Update `exchange_id` After Integration Setup
When a business is connected to a new exchange platform, update its `exchange_id`:


PUT /businesses/{id}
{ "exchange_id": 4419 }

Authentication and Authorization

Both endpoints require a valid Bearer token in the Authorization header. Token permissions determine which Business records are accessible and updatable. Attempting to access or modify a Business outside your authorized scope returns 403 Forbidden.

Authorization: Bearer {your_token}Authorization: Bearer {your_token}

Error Handling

Both endpoints return RFC 7807 Problem Details on error. The standard error shape is:

{
  "type": "https://developer.wex.com/errors/...",
  "title": "Short summary.",
  "status": 400,
  "detail": "Specific explanation of this error.",
  "instance": "/businesses/search",
  "invalid_params": [ ... ]
}

Common status codes across both endpoints:

Pagination (Search)

GET /businesses/search uses offset-based pagination via page and page_size query parameters. Results include HATEOAS links for page navigation.

Response includes has_next to indicate whether additional pages exist. The pagination field is present for legacy compatibility.

Related Resource Groups

Businesses sit within the broader Users & Identity section of the WEX API. Related resource groups that may be used in conjunction with Businesses:

Endpoint Quick Reference