> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truv.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Companies object

> Search employers, check coverage, and map companies to payroll providers

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](/api-reference/data-providers/object) — the payroll system or bank that stores the data.

<Note>
  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.
</Note>

***

## 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

<CardGroup cols={2}>
  <Card title="Company Autocomplete Search" icon="magnifying-glass" href="/api-reference/companies/company_autocomplete_search">
    Search companies by name with autocomplete. Use results to populate or pre-fill Truv Bridge.
  </Card>

  <Card title="Company Info" icon="building" href="/api-reference/companies/company_info">
    Retrieve detailed attributes for a specific company by its mapping ID
  </Card>

  <Card title="Company Mapping" icon="arrow-right-arrow-left" href="/api-reference/companies/company_mapping">
    Map a domain or company name to a Truv company record and mapping ID
  </Card>
</CardGroup>

***

## Example response

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="Pre-fill Truv Bridge (skip employer search)" icon="bolt">
    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.

    ```javascript theme={null}
    // 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();
    ```
  </Accordion>

  <Accordion title="Coverage check before creating an order" icon="shield-check">
    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. |
  </Accordion>
</AccordionGroup>