The Companies object

A Company represents an organization where a user works and receives income. Truv Bridge prompts users with a company search by default, allowing users to find and connect their employer’s payroll system. When a company_mapping_id is passed directly into Truv Bridge, the user skips the search step entirely and goes straight to authentication. Each company typically maps to one data provider — the payroll system or bank that stores the data.

Check a company’s success_rate and mapping_status before creating an order to optimize the user experience and decide whether to fall back to document upload.

Attributes

Attribute	Type	Description
`company_mapping_id`	String	Unique company identifier. Pass to Truv Bridge to bypass employer search.
`name`	String	Company name
`domain`	String	Unique web domain of the company
`logo_url`	String	URL to the company’s logo
`confidence_level`	String	Predicted success rate as a numeric string (`"0.0"`–`"1.0"`; values ≥ 0.5 indicate high success)
`success_rate`	String	Predicted verification success: `"high"` — expected to succeed; `"low"` — may succeed (send if the user knows their payroll provider and is confident); `"unsupported"` — payroll verification not feasible; `null` — not enough attempts to determine
`mapping_status`	String	Mapping to the payroll system: `"verified"` — Truv manually verified the mapped provider; `"mapped"` — a provider is mapped and the user won’t select one in Bridge; `"unmapped"` — no provider mapped, the user must select one manually

Endpoints

Company Autocomplete Search

Search companies by name with autocomplete. Use results to populate or pre-fill Truv Bridge.

Company Info

Retrieve detailed attributes for a specific company by its mapping ID

Company Mapping

Map a domain or company name to a Truv company record and mapping ID

Example response

{
  "company_mapping_id": "48427a36d43c4d5aa6324bc06c692456",
  "name": "Facebook Demo",
  "domain": "facebook.com",
  "logo_url": "https://citadelid-resources.s3-us-west-2.amazonaws.com/facebook.png",
  "confidence_level": "0.9",
  "success_rate": "high",
  "mapping_status": "verified"
}

Common use cases

Pre-fill Truv Bridge (skip employer search)

Search for a company using the autocomplete endpoint, retrieve its company_mapping_id, and pass it when creating the Bridge token. The user lands straight on the login screen for their employer. No search step needed.

// 1. Search for the company (the response is an array of companies)
const results = await fetch('https://prod.truv.com/v1/company-mappings-search/?query=Facebook', {
  headers: { 'X-Access-Client-Id': CLIENT_ID, 'X-Access-Secret': SECRET }
});
const companies = await results.json();
const { company_mapping_id } = companies[0];

// 2. Pass company_mapping_id when creating the Bridge token (server-side),
//    then initialize Truv Bridge with the returned token.
const bridgeToken = await createBridgeToken({ company_mapping_id });
TruvBridge.init({ bridgeToken }).open();

Coverage check before creating an order

Use success_rate and mapping_status to decide whether to offer payroll-based verification or prompt the user to upload documents instead.

`success_rate`	`mapping_status`	Recommendation
`"high"`	`"verified"`	Proceed with payroll verification
`"low"`	`"mapped"`	Offer document upload as primary path
`"unsupported"`	`"unmapped"`	Skip payroll. Go straight to document upload.

​Attributes

​Endpoints

Company Autocomplete Search

Company Info

Company Mapping

​Example response

​Common use cases

Attributes

Endpoints

Example response

Common use cases