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

# Entities

> Understanding merchants, locations, intermediaries, and persons in the entities array

Triqai enriches transactions with an **entities array** containing real-world entities relevant to understanding the transaction. Each entity has a `type`, `role`, `confidence` (with reason tags), and type-specific `data`.

Only identified entities are included in the array if no location was found, there is simply no location entity present.

## Entity Types

<CardGroup cols={2}>
  <Card title="Merchants" icon="building">
    The business or company behind the transaction
  </Card>

  <Card title="Locations" icon="location-dot">
    The physical place where the transaction occurred
  </Card>

  <Card title="Intermediaries" icon="credit-card">
    Payment processors, delivery platforms, wallets, and P2P services
  </Card>

  <Card title="Persons" icon="user">
    Recipients in peer-to-peer transfers
  </Card>
</CardGroup>

## Entity Structure

Every entity in the `entities` array follows the same shape:

```json theme={null}
{
  "type": "merchant",
  "role": "organization",
  "confidence": {
    "value": 98,
    "reasons": ["name_closely_matched", "results_consensus"]
  },
  "data": {
    /* type-specific fields */
  }
}
```

| Field        | Type   | Description                                                                    |
| ------------ | ------ | ------------------------------------------------------------------------------ |
| `type`       | string | Entity type: `merchant`, `location`, `intermediary`, or `person`               |
| `role`       | string | Contextual role (depends on type — see below)                                  |
| `confidence` | object | `{ value: 0-100, reasons: string[] }` — confidence score with explanatory tags |
| `data`       | object | Type-specific data fields                                                      |

### Entity Roles

Each entity type has specific roles that describe its function in the transaction context:

| Type           | Possible Roles                                         | Description                       |
| -------------- | ------------------------------------------------------ | --------------------------------- |
| `merchant`     | `organization`, `financial_institution`, `institution` | The kind of business              |
| `location`     | `store_location`, `headquarters`, `office`             | What the location represents      |
| `intermediary` | `processor`, `platform`, `wallet`, `p2p`               | The intermediary's function       |
| `person`       | `recipient`                                            | The person's role in the transfer |

## Merchants

Merchants are the primary entities in most transactions. When identified, you get:

```json theme={null}
{
  "type": "merchant",
  "role": "organization",
  "confidence": {
    "value": 98,
    "reasons": ["name_closely_matched", "results_consensus"]
  },
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Starbucks",
    "alias": ["Starbucks Coffee", "SBUX"],
    "keywords": ["coffee", "cafe", "drinks"],
    "icon": "https://logos.triqai.com/images/starbuckscom",
    "description": "Multinational chain of coffeehouses",
    "color": "#00704A",
    "website": "https://www.starbucks.com",
    "domain": "starbucks.com"
  }
}
```

### Merchant Fields

| Field         | Type           | Description                         |
| ------------- | -------------- | ----------------------------------- |
| `id`          | string         | Unique identifier for the merchant  |
| `name`        | string         | Canonical merchant name             |
| `alias`       | string\[]      | Alternative names and abbreviations |
| `keywords`    | string\[]      | Related search terms                |
| `icon`        | URL \| null    | Logo image URL                      |
| `description` | string         | Brief description of the business   |
| `color`       | string \| null | Brand color (hex format)            |
| `website`     | URL \| null    | Official website                    |
| `domain`      | string \| null | Primary domain name                 |

### Merchant Coverage

Triqai maintains a database of over **150 million companies** worldwide, with:

* **143,000+ logos** for visual branding
* Normalized names for consistent identification
* Multiple aliases to match various transaction formats

## Locations

Location enrichment provides geographic context for transactions:

```json theme={null}
{
  "type": "location",
  "role": "store_location",
  "confidence": {
    "value": 92,
    "reasons": ["city_match", "address_closely_matched"]
  },
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "Starbucks - Times Square",
    "formatted": "1530 Broadway, New York, NY 10036, USA",
    "phoneNumber": "+1-212-555-0123",
    "website": "https://www.starbucks.com/store-locator/store/8289",
    "priceRange": "$$",
    "rating": { "average": 4.2, "count": 1250, "source": "google" },
    "structured": {
      "street": "1530 Broadway",
      "city": "New York",
      "state": "NY",
      "postalCode": "10036",
      "country": "US",
      "countryName": "United States",
      "coordinates": {
        "latitude": 40.758,
        "longitude": -73.9855
      },
      "timezone": "America/New_York"
    }
  }
}
```

### Location Fields

| Field                    | Type           | Description                                         |
| ------------------------ | -------------- | --------------------------------------------------- |
| `id`                     | string         | Unique identifier for the location                  |
| `name`                   | string         | Location name (may include store number)            |
| `formatted`              | string         | Full formatted address                              |
| `phoneNumber`            | string \| null | Contact phone number                                |
| `website`                | URL \| null    | Location-specific website                           |
| `priceRange`             | string \| null | Price range indicator (e.g. "\$", "\$\$", "\$\$\$") |
| `rating`                 | object \| null | Rating with `average`, `count`, and `source`        |
| `structured.street`      | string         | Street address                                      |
| `structured.city`        | string         | City name                                           |
| `structured.state`       | string         | State/province/region                               |
| `structured.postalCode`  | string         | Postal or ZIP code                                  |
| `structured.country`     | string         | ISO country code                                    |
| `structured.countryName` | string         | Full country name                                   |
| `structured.coordinates` | object         | Latitude and longitude                              |
| `structured.timezone`    | string         | IANA timezone identifier                            |

### Location Coverage

* **10M+ places** globally
* **150+ countries** supported
* Store-level precision when available

## Intermediaries

Intermediaries are a unified entity type that replaces the previous separate "payment processor" and "P2P platform" concepts. They represent any service that sits between the customer and the final recipient of funds.

### Intermediary Roles

| Role        | Description                   | Examples                        |
| ----------- | ----------------------------- | ------------------------------- |
| `processor` | Payment processor/gateway     | Stripe, Adyen, Square, Worldpay |
| `platform`  | Delivery/marketplace platform | DoorDash, Uber Eats, Instacart  |
| `wallet`    | Digital wallet/payment app    | Apple Pay, Google Pay, Alipay   |
| `p2p`       | Peer-to-peer transfer service | Venmo, Zelle, Cash App, PayPal  |

```json theme={null}
{
  "type": "intermediary",
  "role": "processor",
  "confidence": { "value": 99, "reasons": ["known_processor_match"] },
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "name": "Stripe",
    "icon": "https://logos.triqai.com/images/stripecom",
    "description": "Online payment processing platform",
    "color": "#635BFF",
    "website": "https://stripe.com",
    "domain": "stripe.com"
  }
}
```

### Intermediary Fields

| Field         | Type           | Description             |
| ------------- | -------------- | ----------------------- |
| `id`          | string         | Unique identifier       |
| `name`        | string         | Intermediary name       |
| `icon`        | URL \| null    | Logo image URL          |
| `description` | string \| null | Brief description       |
| `color`       | string \| null | Brand color (hex)       |
| `website`     | URL \| null    | Official website        |
| `domain`      | string \| null | Domain without protocol |

### Why It Matters

Intermediary detection is valuable for:

* **Identifying the actual merchant** behind processor-branded transactions
* **Understanding payment methods** used by customers
* **Fraud detection** by recognizing unusual processor patterns
* **Analytics** on payment method preferences
* **Delivery platform tracking** for food delivery and marketplace transactions

## Persons

Person entities appear in P2P transfer transactions to identify the recipient:

```json theme={null}
{
  "type": "person",
  "role": "recipient",
  "confidence": { "value": 98, "reasons": [] },
  "data": {
    "displayName": "John Doe"
  }
}
```

### Person Fields

| Field         | Type   | Description                              |
| ------------- | ------ | ---------------------------------------- |
| `displayName` | string | Recipient's name as shown in transaction |

<Note>
  **Privacy**: Person display names are stored per-organization and never shared
  globally. This ensures personal information remains private and
  GDPR-compliant.
</Note>

## P2P Transfer Example

A P2P transfer typically produces both an intermediary entity (the platform) and a person entity (the recipient):

```json theme={null}
{
  "entities": [
    {
      "type": "intermediary",
      "role": "p2p",
      "confidence": { "value": 98, "reasons": ["known_processor_match"] },
      "data": {
        "id": "p2p_venmo",
        "name": "Venmo",
        "icon": "https://logos.triqai.com/images/venmocom",
        "description": null,
        "color": "#3D95CE",
        "website": "https://venmo.com",
        "domain": "venmo.com"
      }
    },
    {
      "type": "person",
      "role": "recipient",
      "confidence": { "value": 98, "reasons": [] },
      "data": {
        "displayName": "John Doe"
      }
    }
  ]
}
```

## Fetching Entity Details

You can fetch full entity details by ID:

<CodeGroup>
  ```typescript Node.js theme={null}
  import Triqai from "triqai";

  const triqai = new Triqai(process.env.TRIQAI_API_KEY!);

  const merchant = await triqai.merchants.get("merchant-uuid");
  console.log(merchant.name, merchant.website, merchant.icon);

  const location = await triqai.locations.get("location-uuid");
  console.log(location.formatted, location.structured.city);

  const intermediary = await triqai.intermediaries.get("intermediary-uuid");
  console.log(intermediary.name);
  ```

  ```bash cURL theme={null}
  # Merchant
  curl https://api.triqai.com/v1/merchants/{id} -H "X-API-Key: YOUR_API_KEY"

  # Location
  curl https://api.triqai.com/v1/locations/{id} -H "X-API-Key: YOUR_API_KEY"

  # Intermediary
  curl https://api.triqai.com/v1/intermediaries/{id} -H "X-API-Key: YOUR_API_KEY"
  ```
</CodeGroup>

## Entity Sharing

Entities are shared resources:

* **Merchants**, **locations**, and **intermediaries** are shared across all organizations
* This ensures consistent identification and reduces duplication
* Entity IDs are stable and can be used for deduplication

<Warning>
  **Exception**: Person display names are scoped to your organization for
  privacy.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Confidence Scores" icon="chart-bar" href="/concepts/confidence-scores">
    Learn how to interpret confidence values and reason tags
  </Card>

  <Card title="Entity APIs" icon="code" href="/api-reference/get-merchant">
    Explore the entity lookup endpoints
  </Card>
</CardGroup>