Entities

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

Merchants

The business or company behind the transaction

Locations

The physical place where the transaction occurred

Intermediaries

Payment processors, delivery platforms, wallets, and P2P services

Persons

Recipients in peer-to-peer transfers

Entity Structure

Every entity in the entities array follows the same shape:

{
  "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:

{
  "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:

{
  "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

{
  "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:

{
  "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

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

P2P Transfer Example

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

{
  "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:

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);

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

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

Exception: Person display names are scoped to your organization for privacy.

Getting Started

Core Concepts

Guides

Platform

Entity Types

Merchants

Locations

Intermediaries

Persons

Entity Structure

Entity Roles

Merchants

Merchant Fields

Merchant Coverage

Locations

Location Fields

Location Coverage

Intermediaries

Intermediary Roles

Intermediary Fields

Why It Matters

Persons

Person Fields

P2P Transfer Example

Fetching Entity Details

Next Steps

Confidence Scores

Entity APIs

​Entity Types

Merchants

Locations

Intermediaries

Persons

​Entity Structure

​Entity Roles

​Merchants

​Merchant Fields

​Merchant Coverage

​Locations

​Location Fields

​Location Coverage

​Intermediaries

​Intermediary Roles

​Intermediary Fields

​Why It Matters

​Persons

​Person Fields

​P2P Transfer Example

​Fetching Entity Details

​Entity Sharing

​Next Steps

Confidence Scores

Entity APIs

Entity Types

Entity Structure

Entity Roles

Merchants

Merchant Fields

Merchant Coverage

Locations

Location Fields

Location Coverage

Intermediaries

Intermediary Roles

Intermediary Fields

Why It Matters

Persons

Person Fields

P2P Transfer Example

Fetching Entity Details

Entity Sharing

Next Steps