Triqai

https://docs.triqai.com
Admin
A developer-first API platform that enriches raw bank transaction data into structured, reliable,...
Tokens:64,270
Snippets:448
Trust Score:5.2
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install SDK with pnpm

Source: https://docs.triqai.com/sdk/overview

Install the Triqai SDK using pnpm.

```bash
pnpm add triqai
```

--------------------------------

### Install SDK with npm

Source: https://docs.triqai.com/sdk/overview

Install the Triqai SDK using npm.

```bash
npm install triqai
```

--------------------------------

### Install SDK with yarn

Source: https://docs.triqai.com/sdk/overview

Install the Triqai SDK using yarn.

```bash
yarn add triqai
```

--------------------------------

### Quick Start: Enrich Transaction

Source: https://docs.triqai.com/sdk/overview

Initialize the SDK with your API key and enrich a transaction. This example shows how to get the primary category name and entities from the enrichment result.

```typescript
import Triqai from "triqai";

const triqai = new Triqai("triq_your_api_key");

const result = await triqai.transactions.enrich({
  title: "STARBUCKS SEATTLE WA",
  country: "US",
  type: "expense",
});

console.log(result.data.transaction.category.primary.name);
// => "Food & Dining"

console.log(result.data.entities);
// => [{ type: "merchant", data: { name: "Starbucks", ... } }, ...]
```

--------------------------------

### Full Success Response Example

Source: https://docs.triqai.com/guides/handling-responses

An example of a successful Triqai API response where all enrichment modules completed successfully. The 'entities' array contains all identified entities.

```json
{
  "success": true,
  "partial": false,
  "data": {
    "transaction": {
      "category": { "primary": { "name": "Coffee Shops" }, "confidence": { "value": 95, "reasons": ["merchant_category_match"] } },
      "confidence": { "value": 92, "reasons": [] }
    },
    "entities": [
      { "type": "merchant", "role": "organization", "confidence": { "value": 98, "reasons": ["name_closely_matched"] }, "data": { "name": "Starbucks" } },
      { "type": "location", "role": "store_location", "confidence": { "value": 85, "reasons": ["city_match"] }, "data": { "formatted": "1530 Broadway, New York" } }
    ]
  }
}
```

--------------------------------

### Complete Transaction Processing Example

Source: https://docs.triqai.com/guides/handling-responses

A comprehensive example demonstrating how to initialize the Triqai client, process a transaction, and extract various entities like merchant, location, intermediary, and person. Includes robust error handling for API-specific errors.

```typescript
import Triqai, { TriqaiError } from "triqai";

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

async function processTransaction(title: string, country: string, type: "expense" | "income") {
  try {
    const result = await triqai.transactions.enrich({ title, country, type });

    const { transaction, entities } = result.data;
    const find = (t: string) => entities.find(e => e.type === t);

    const merchant = find("merchant");
    const location = find("location");
    const intermediary = find("intermediary");
    const person = find("person");

    return {
      category: transaction.category.primary.name,
      subcategory: transaction.category.secondary?.name,
      confidence: transaction.confidence.value,

      merchant: merchant ? {
        name: merchant.data.name,
        logo: merchant.data.icon,
        confidence: merchant.confidence.value,
      } : null,

      location: location ? {
        formatted: location.data.formatted,
        coordinates: location.data.structured.coordinates,
        confidence: location.confidence.value,
      } : null,

      intermediary: intermediary ? {
        name: intermediary.data.name,
        role: intermediary.role,
        confidence: intermediary.confidence.value,
      } : null,

      person: person ? {
        displayName: person.data.displayName,
        confidence: person.confidence.value,
      } : null,
    };
  } catch (err) {
    if (err instanceof TriqaiError) {
      console.error(`API error ${err.statusCode}: ${err.message}`);
    }
    throw err;
  }
}
```

--------------------------------

### Partial Success Response Example

Source: https://docs.triqai.com/guides/handling-responses

An example of a partial success response from the Triqai API, where some enrichment modules succeeded while others failed. The 'meta.errors' field indicates which modules failed.

```json
{
  "success": true,
  "partial": true,
  "data": {
    "transaction": {
      "confidence": { "value": 75, "reasons": [] }
    },
    "entities": [
      {
        "type": "merchant",
        "role": "organization",
        "confidence": { "value": 95, "reasons": ["name_closely_matched"] },
        "data": { "name": "Acme Corp" }
      }
    ]
  },
  "meta": {
    "errors": ["location_timeout"]
  }
}
```

--------------------------------

### OpenAPI Error Response Example

Source: https://docs.triqai.com/api-reference/transactions/get-transaction

Example of an internal server error response structure defined in OpenAPI.

```yaml
InternalError:
  description: Internal server error
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ErrorResponse'
```

--------------------------------

### Category Versioning Example

Source: https://docs.triqai.com/concepts/categories

Example JSON response showing the category version. The `meta.categoryVersion` field indicates the current version of the taxonomy, which changes when the taxonomy is updated.

```json
{
  "meta": {
    "categoryVersion": "triqai-2026.01"
  }
}
```

--------------------------------

### OpenAPI Security Scheme Example

Source: https://docs.triqai.com/api-reference/transactions/get-transaction

Example of an API key security scheme definition within an OpenAPI specification.

```yaml
securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-API-Key
    description: Public API key
```

--------------------------------

### Store API Key in .env file

Source: https://docs.triqai.com/authentication

Example of how to store your Triqai API key in a .env file for secure access.

```bash
TRIQAI_API_KEY=triq_your_api_key_here
```

--------------------------------

### P2P Transfer Entity Example

Source: https://docs.triqai.com/concepts/entities

This example shows a P2P transfer transaction containing both an intermediary (platform) and a person (recipient) entity.

```json
{
  "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"
      }
    }
  ]
}
```

--------------------------------

### Batch Delete Transactions - Delete All

Source: https://docs.triqai.com/api-reference/transactions/batch-delete-transactions

Use this example to delete all transactions for your organization. Ensure you have a backup if needed, as this action is irreversible.

```json
{
  "all": true
}
```

--------------------------------

### Error Response Example

Source: https://docs.triqai.com/guides/handling-responses

An example of a failed Triqai API response, indicated by 'success: false'. The 'error' object contains details about the failure, such as the error code, message, and specific field errors.

```json
{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": {
      "fieldErrors": {
        "title": ["Title is required"],
        "country": ["Invalid country code"]
      }
    }
  },
  "meta": { }
}
```

--------------------------------

### Category Confidence Example

Source: https://docs.triqai.com/concepts/confidence-scores

Demonstrates how confidence scores are applied to categorize transaction data, including primary and secondary categories.

```json
{
  "category": {
    "primary": { "name": "Shopping" },
    "secondary": { "name": "Online Shopping" },
    "confidence": { "value": 95, "reasons": ["merchant_category_match"] }
  }
}
```

--------------------------------

### Overall Transaction Confidence Example

Source: https://docs.triqai.com/concepts/confidence-scores

This snippet shows the structure for overall transaction confidence, indicating the general quality of the enrichment.

```json
{
  "data": {
    "transaction": {
      "confidence": { "value": 92, "reasons": [] }
    }
  }
}
```

--------------------------------

### Basic Income Enrichment

Source: https://docs.triqai.com/api-reference/transactions/enrich-transaction

Use this example to enrich a basic income transaction. It requires the transaction title, country, and type.

```json
{
  "title": "PAYPAL REFUND EBAY INC",
  "country": "US",
  "type": "income"
}
```

--------------------------------

### Deduplicate Transactions Before Enriching

Source: https://docs.triqai.com/guides/best-practices

Group identical transactions before enriching to save credits. This example demonstrates how to group transactions by title, country, and type before sending them for enrichment.

```typescript
import Triqai from "triqai";

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

interface Transaction {
  id: string;
  title: string;
  country: string;
  type: "expense" | "income";
}

async function enrichBatch(transactions: Transaction[]) {
  const groups = new Map<string, { representative: Transaction; all: Transaction[] }>();

  for (const tx of transactions) {
    const key = `${tx.title.toUpperCase()}|${tx.country}|${tx.type}`;
    if (!groups.has(key)) {
      groups.set(key, { representative: tx, all: [] });
    }
    groups.get(key)!.all.push(tx);
  }

  const results = new Map();

  for (const [, group] of groups) {
    const result = await triqai.transactions.enrich({
      title: group.representative.title,
      country: group.representative.country,
      type: group.representative.type,
    });
    for (const tx of group.all) {
      results.set(tx.id, result);
    }
  }

  return results;
}
```

--------------------------------

### Regular Purchase Transaction Input

Source: https://docs.triqai.com/guides/enriching-transactions

Example of a standard transaction input for a regular purchase, specifying title, country, and type.

```json
{ "title": "STARBUCKS STORE 1234", "country": "US", "type": "expense" }
```

--------------------------------

### Per-Entity Confidence Example

Source: https://docs.triqai.com/concepts/confidence-scores

Illustrates confidence scores applied to individual entities within the enrichment results, such as merchants, locations, and intermediaries.

```json
{
  "entities": [
    {
      "type": "merchant",
      "role": "organization",
      "confidence": {
        "value": 98,
        "reasons": ["name_closely_matched", "results_consensus"]
      },
      "data": { "name": "Starbucks" }
    },
    {
      "type": "location",
      "role": "store_location",
      "confidence": {
        "value": 72,
        "reasons": ["city_match", "multiple_plausible_locations"]
      },
      "data": { "name": "Starbucks - Downtown" }
    },
    {
      "type": "intermediary",
      "role": "processor",
      "confidence": { "value": 99, "reasons": ["known_processor_match"] },
      "data": { "name": "Square" }
    }
  ]
}
```

--------------------------------

### Good Transaction Data Example

Source: https://docs.triqai.com/guides/best-practices

Include the full, original transaction string for better matching accuracy. Use ISO 3166-1 alpha-2 codes for countries.

```json
{
  "title": "POS 4392 STARBUCKS STORE #1234 NEW YORK NY 10001",
  "country": "US",
  "type": "expense"
}
```

--------------------------------

### Full Configuration Example

Source: https://docs.triqai.com/sdk/configuration

Instantiate the Triqai client with a full set of configuration options including base URL, retry settings, timeout, default headers, and debug hooks.

```typescript
const triqai = new Triqai("triq_your_api_key", {
  // Base URL (default: https://api.triqai.com)
  baseUrl: "https://api.triqai.com",

  // Retry configuration
  maxRetries: 3,          // default: 3
  retryDelay: 500,        // base delay in ms (default: 500)
  maxRetryDelay: 30_000,  // max delay in ms (default: 30000)

  // Request timeout in ms (default: 60000)
  timeout: 60_000,

  // Extra headers for every request
  defaultHeaders: {
    "X-Custom-Header": "value",
  },

  // Debug hooks
  onRequest: (info) => console.log(`${info.method} ${info.url}`),
  onResponse: (info) => console.log(`${info.status} in ${info.durationMs}ms`),
});
```

--------------------------------

### Make a Transaction Enrichment Request with Go

Source: https://docs.triqai.com/quickstart

This Go program demonstrates how to make a POST request to the Triqai API for transaction enrichment using the standard 'net/http' package.

```go
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    payload := map[string]string{
        "title":   "PP* #56789 MK:678321 LELLO, PORTO Ref:hwjk2-23123 PAGAMENTO",
        "country": "BR",
        "type":    "expense",
    }

    jsonData, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", "https://api.triqai.com/v1/transactions/enrich", bytes.NewBuffer(jsonData))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", "YOUR_API_KEY")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result)
}
```

--------------------------------

### Valid Country Codes Example

Source: https://docs.triqai.com/guides/enriching-transactions

Examples of valid ISO 3166-1 alpha-2 country codes in JavaScript. These codes specify the transaction's origin country.

```javascript
// Valid country codes
"US"; // United States
"NL"; // Netherlands
"GB"; // United Kingdom
"DE"; // Germany
"FR"; // France
```

--------------------------------

### Access API Key from Environment Variable (Node.js)

Source: https://docs.triqai.com/authentication

Initialize the Triqai SDK using an API key stored in the environment variable TRIQAI_API_KEY.

```typescript
import Triqai from "triqai";

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

--------------------------------

### Access API Key from Environment Variable (Go)

Source: https://docs.triqai.com/authentication

Retrieve the Triqai API key from the environment variable TRIQAI_API_KEY using Go's os module.

```go
apiKey := os.Getenv("TRIQAI_API_KEY")
```

--------------------------------

### Get Raw Rate Limit Info

Source: https://docs.triqai.com/guides/best-practices

Retrieve detailed rate limit information by making raw GET requests. This allows you to check remaining rate limits for specific endpoints.

```typescript
const resp = await triqai.rawGet("/v1/categories");
console.log(resp.rateLimitInfo.remaining);
console.log(resp.rateLimitInfo.concurrencyRemaining);
```

--------------------------------

### Fetch Entity Details using Triqai SDK (Node.js)

Source: https://docs.triqai.com/concepts/entities

Use the Triqai Node.js SDK to retrieve full details for merchants, locations, and intermediaries by their unique IDs. Ensure your TRIQAI_API_KEY is set in your environment variables.

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

--------------------------------

### Get Merchant OpenAPI Specification

Source: https://docs.triqai.com/api-reference/entities/get-merchant

This OpenAPI 3.1 specification defines the GET /v1/merchants/{id} endpoint for retrieving merchant details. It includes request parameters, response schemas, and error codes.

```yaml
openapi: 3.1.0
info:
  title: Triqai Transaction Enrichment API
  version: 1.3.21
  description: >
    The Triqai API provides transaction enrichment capabilities for financial
    applications.


    ## Authentication


    All API endpoints require an API key in the `X-API-Key` header.


    ## Rate Limiting


    Per-organization limits use a token bucket (RPS) plus a concurrent in-flight
    cap.

    Headers may include:

    - `X-RateLimit-Limit`

    - `X-RateLimit-Remaining`

    - `X-RateLimit-Reset`

    - `X-RateLimit-Scope` (`rps` or `concurrency`)

    - `X-RateLimit-Concurrency-Limit`

    - `X-RateLimit-Concurrency-Remaining`


    `Retry-After` is returned in **seconds** on throttled responses.


    ## Idempotency


    You can supply `Idempotency-Key` (or `X-Idempotency-Key`) to make retries
    safer.

    Keys must match `^[a-zA-Z0-9_-]{1,64}$`.

    Reusing a key returns `409`:

    - `state=completed`: request with this key already finished

    - `state=in_progress`: request with this key is still processing
    (`Retry-After` included)
  contact:
    name: Triqai Contact
    url: https://triqai.com/contact
  license:
    name: Proprietary
    url: https://triqai.com/terms
servers:
  - url: https://api.triqai.com
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Health
  - name: API
  - name: Transactions
  - name: Categories
  - name: Entities
  - name: Issue Reports
paths:
  /v1/merchants/{id}:
    get:
      tags:
        - Entities
      summary: Get merchant
      operationId: getMerchant
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: Merchant found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    IdPath:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
  schemas:
    MerchantResponse:
      type: object
      required:
        - success
        - data
        - meta
      properties:
        success:
          type: boolean
          enum:
            - true
        data:
          type: object
          required:
            - merchant
          properties:
            merchant:
              $ref: '#/components/schemas/MerchantData'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    MerchantData:
      type: object
      required:
        - id
        - name
        - alias
        - icon
        - color
        - website
        - domain
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        alias:
          type: array
          items:
            type: string
        keywords:
          type: array
          description: Search keywords associated with this merchant. May be absent.
          items:
            type: string
        icon:
          oneOf:
            - type: string
              format: uri
            - type: 'null'
        description:
          type: string
          description: Brief description of the merchant. May be absent.
        color:
          oneOf:
            - type: string
            - type: 'null'
        website:
          oneOf:
            - type: string
              format: uri
            - type: 'null'
        domain:
          oneOf:
            - type: string
            - type: 'null'
        category:
          oneOf:
            - $ref: '#/components/schemas/CategoryStructure'
            - type: 'null'
          description: >-
            Merchant category classification. Present on `GET
            /v1/merchants/{id}` responses.
    ResponseMeta:
      type: object
      required:
        - generatedAt
        - requestId
        - version
      properties:
        generatedAt:
          type: string
          format: date-time
        requestId:
          type: string
        version:
          type: string
      additionalProperties: true
    ErrorResponse:
      type: object
      required:
        - success
        - error
        - meta
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          $ref: '#/components/schemas/ErrorObject'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    CategoryStructure:
      type: object
      required:
        - primary
        - secondary
        - tertiary

```

--------------------------------

### Make a Transaction Enrichment Request with Python

Source: https://docs.triqai.com/quickstart

Use the Python requests library to make a POST request to the Triqai API for transaction enrichment. Ensure you have the 'requests' library installed.

```python
import requests

response = requests.post(
    'https://api.triqai.com/v1/transactions/enrich',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': 'YOUR_API_KEY'
    },
    json={
        'title': 'PP* #56789 MK:678321 LELLO, PORTO Ref:hwjk2-23123 PAGAMENTO',
        'country': 'BR',
        'type': 'expense'
    }
)

print(response.json())
```

--------------------------------

### Get Issue Report OpenAPI Specification

Source: https://docs.triqai.com/api-reference/issue-reports/get-issue-report

This snippet shows the OpenAPI 3.1 specification for the GET /v1/report-issue/{id} endpoint. It details the parameters, responses, and schemas involved in retrieving an issue report.

```yaml
openapi: 3.1.0
info:
  title: Triqai Transaction Enrichment API
  version: 1.3.21
  description: >
    The Triqai API provides transaction enrichment capabilities for financial
    applications.


    ## Authentication


    All API endpoints require an API key in the `X-API-Key` header.


    ## Rate Limiting


    Per-organization limits use a token bucket (RPS) plus a concurrent in-flight
    cap.

    Headers may include:

    - `X-RateLimit-Limit`

    - `X-RateLimit-Remaining`

    - `X-RateLimit-Reset`

    - `X-RateLimit-Scope` (`rps` or `concurrency`)

    - `X-RateLimit-Concurrency-Limit`

    - `X-RateLimit-Concurrency-Remaining`


    `Retry-After` is returned in **seconds** on throttled responses.


    ## Idempotency


    You can supply `Idempotency-Key` (or `X-Idempotency-Key`) to make retries
    safer.

    Keys must match `^[a-zA-Z0-9_-]{1,64}$`.

    Reusing a key returns `409`:

    - `state=completed`: request with this key already finished

    - `state=in_progress`: request with this key is still processing
    (`Retry-After` included)
  contact:
    name: Triqai Contact
    url: https://triqai.com/contact
  license:
    name: Proprietary
    url: https://triqai.com/terms
servers:
  - url: https://api.triqai.com
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Health
  - name: API
  - name: Transactions
  - name: Categories
  - name: Entities
  - name: Issue Reports
paths:
  /v1/report-issue/{id}:
    get:
      tags:
        - Issue Reports
      summary: Get issue report
      operationId: getIssueReport
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: Issue report detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueReportResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    IdPath:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
  schemas:
    IssueReportResponse:
      type: object
      required:
        - success
        - data
        - meta
      properties:
        success:
          type: boolean
          enum:
            - true
        data:
          type: object
          required:
            - issueReport
          properties:
            issueReport:
              $ref: '#/components/schemas/IssueReport'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    IssueReport:
      type: object
      required:
        - id
        - transactionId
        - description
        - fields
        - status
        - statusMessage
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
        transactionId:
          type: string
          format: uuid
        description:
          type: string
        fields:
          type: array
          items:
            type: string
        status:
          $ref: '#/components/schemas/IssueReportStatus'
        statusMessage:
          oneOf:
            - type: string
            - type: 'null'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ResponseMeta:
      type: object
      required:
        - generatedAt
        - requestId
        - version
      properties:
        generatedAt:
          type: string
          format: date-time
        requestId:
          type: string
        version:
          type: string
      additionalProperties: true
    ErrorResponse:
      type: object
      required:
        - success
        - error
        - meta
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          $ref: '#/components/schemas/ErrorObject'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    IssueReportStatus:
      type: string
      enum:
        - pending
        - reviewing
        - resolved
        - dismissed
    ErrorObject:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
        details:
          $ref: '#/components/schemas/ErrorDetails'
    ErrorDetails:
      type: object
      properties:
        fieldErrors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string

```

--------------------------------

### Fetch All Categories (cURL)

Source: https://docs.triqai.com/concepts/categories

Retrieve the complete category taxonomy using a cURL command. Ensure you replace 'YOUR_API_KEY' with your actual Triqai API key.

```bash
curl https://api.triqai.com/v1/categories \
  -H "X-API-Key: YOUR_API_KEY"
```

--------------------------------

### Basic Transaction Enrichment Request (cURL)

Source: https://docs.triqai.com/guides/enriching-transactions

Make a basic transaction enrichment request using cURL. Replace YOUR_API_KEY with your actual Triqai API key.

```bash
curl -X POST https://api.triqai.com/v1/transactions/enrich \
    -H "Content-Type: application/json" \
    -H "X-API-Key: YOUR_API_KEY" \
    -d '{
      "title": "NETFLIX.COM",
      "country": "US",
      "type": "expense"
    }'
```

--------------------------------

### Get a Transaction

Source: https://docs.triqai.com/sdk/transactions

Retrieve a single enriched transaction by its unique ID.

```APIDOC
## Get a Transaction

### Description
Retrieve a single enriched transaction by ID.

### Method
`get`

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the transaction to retrieve.

### Request Example
```json
"550e8400-e29b-41d4-a716-446655440000"
```
```

--------------------------------

### Get Transaction

Source: https://docs.triqai.com/api-reference/transactions/get-transaction

Retrieves the details of a specific transaction using its ID.

```APIDOC
## GET /transactions/{id}

### Description
Retrieves the details of a specific transaction.

### Method
GET

### Endpoint
/transactions/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the transaction.

### Response
#### Success Response (200)
- **message** (string) - A success message indicating the transaction was retrieved.
- **meta** (object) - Metadata about the response.
  - **generatedAt** (string) - The timestamp when the response was generated.
  - **requestId** (string) - The unique identifier for the request.
  - **version** (string) - The version of the API.

#### Error Response
- **InternalError** (object)
  - **description** (string) - Description of the internal error.
  - **content** (object)
    - **application/json** (object)
      - **schema** (object)
        - **$ref** (string) - Reference to the error response schema.

### Security
#### ApiKeyAuth
- **type**: apiKey
- **in**: header
- **name**: X-API-Key
- **description**: Public API key
```

--------------------------------

### OpenAPI Specification for Get Intermediary

Source: https://docs.triqai.com/api-reference/entities/get-intermediary

This OpenAPI 3.1.0 specification defines the GET /v1/intermediaries/{id} endpoint. It details the request parameters, including the required 'id' path parameter, and the structure of successful responses (200 OK) and various error responses (401, 403, 404, 422, 429, 500).

```yaml
openapi: 3.1.0
info:
  title: Triqai Transaction Enrichment API
  version: 1.3.21
  description: >
    The Triqai API provides transaction enrichment capabilities for financial
    applications.


    ## Authentication


    All API endpoints require an API key in the `X-API-Key` header.


    ## Rate Limiting


    Per-organization limits use a token bucket (RPS) plus a concurrent in-flight
    cap.

    Headers may include:

    - `X-RateLimit-Limit`

    - `X-RateLimit-Remaining`

    - `X-RateLimit-Reset`

    - `X-RateLimit-Scope` (`rps` or `concurrency`)

    - `X-RateLimit-Concurrency-Limit`

    - `X-RateLimit-Concurrency-Remaining`


    `Retry-After` is returned in **seconds** on throttled responses.


    ## Idempotency


    You can supply `Idempotency-Key` (or `X-Idempotency-Key`) to make retries
    safer.

    Keys must match `^[a-zA-Z0-9_-]{1,64}$`.

    Reusing a key returns `409`:

    - `state=completed`: request with this key already finished

    - `state=in_progress`: request with this key is still processing
    (`Retry-After` included)
  contact:
    name: Triqai Contact
    url: https://triqai.com/contact
  license:
    name: Proprietary
    url: https://triqai.com/terms
servers:
  - url: https://api.triqai.com
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Health
  - name: API
  - name: Transactions
  - name: Categories
  - name: Entities
  - name: Issue Reports
paths:
  /v1/intermediaries/{id}:
    get:
      tags:
        - Entities
      summary: Get intermediary
      operationId: getIntermediary
      parameters:
        - $ref: '#/components/parameters/IdPath'
      responses:
        '200':
          description: Intermediary found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntermediaryResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    IdPath:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
  schemas:
    IntermediaryResponse:
      type: object
      required:
        - success
        - data
        - meta
      properties:
        success:
          type: boolean
          enum:
            - true
        data:
          type: object
          required:
            - intermediary
          properties:
            intermediary:
              $ref: '#/components/schemas/IntermediaryData'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    IntermediaryData:
      type: object
      required:
        - id
        - name
        - icon
        - description
        - color
        - website
        - domain
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        icon:
          oneOf:
            - type: string
              format: uri
            - type: 'null'
        description:
          oneOf:
            - type: string
            - type: 'null'
        color:
          oneOf:
            - type: string
            - type: 'null'
        website:
          oneOf:
            - type: string
              format: uri
            - type: 'null'
        domain:
          oneOf:
            - type: string
            - type: 'null'
    ResponseMeta:
      type: object
      required:
        - generatedAt
        - requestId
        - version
      properties:
        generatedAt:
          type: string
          format: date-time
        requestId:
          type: string
        version:
          type: string
      additionalProperties: true
    ErrorResponse:
      type: object
      required:
        - success
        - error
        - meta
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          $ref: '#/components/schemas/ErrorObject'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    ErrorObject:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
        details:
          $ref: '#/components/schemas/ErrorDetails'
    ErrorDetails:
      type: object
      properties:
        fieldErrors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
      additionalProperties: true
  responses:
    Unauthorized:
      description: Authentication failed or missing credentials
      content:

```

--------------------------------

### Basic Transaction Enrichment Request (Python)

Source: https://docs.triqai.com/guides/enriching-transactions

Send a basic transaction enrichment request using Python's requests library. The API key should be stored in the TRIQAI_API_KEY environment variable.

```python
import requests
import os

response = requests.post(
    'https://api.triqai.com/v1/transactions/enrich',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': os.environ['TRIQAI_API_KEY']
    },
    json={
        'title': 'NETFLIX.COM',
        'country': 'US',
        'type': 'expense'
    }
)

result = response.json()
```

--------------------------------

### Access API Key from Environment Variable (Python)

Source: https://docs.triqai.com/authentication

Retrieve the Triqai API key from the environment variable TRIQAI_API_KEY using Python's os module.

```python
import os
api_key = os.environ.get('TRIQAI_API_KEY')
```

--------------------------------

### Get a Specific Issue Report

Source: https://docs.triqai.com/sdk/resources

Retrieves a single issue report by its unique identifier.

```typescript
const report = await triqai.issueReports.get("report-uuid");
```

--------------------------------

### Get Location by ID

Source: https://docs.triqai.com/sdk/resources

Retrieves a specific location's details using its unique identifier.

```APIDOC
## Get Location by ID

### Description
Looks up a location by its ID.

### Method
`GET` (implied by SDK method `get`)

### Endpoint
`/locations/{locationId}` (implied by SDK method `locations.get`)

### Parameters
#### Path Parameters
- **locationId** (string) - Required - The unique identifier of the location.

### Response
#### Success Response
- **formatted** (string) - The formatted address of the location.
- **structured** (object) - An object containing structured address components, including `city`.

### Request Example
```typescript
const location = await triqai.locations.get("location-uuid");
```

### Response Example
```json
{
  "formatted": "123 Main St, Anytown, USA",
  "structured": {
    "city": "Anytown",
    "state": "CA",
    "zip": "90210"
  }
}
```
```

--------------------------------

### Fetch Entity Details using cURL

Source: https://docs.triqai.com/concepts/entities

Retrieve entity details for merchants, locations, and intermediaries via cURL by making GET requests to the Triqai API. Replace '{id}' with the specific entity ID and 'YOUR_API_KEY' with your actual API key.

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

--------------------------------

### Get Issue Report by ID

Source: https://docs.triqai.com/api-reference/issue-reports/get-issue-report

Fetches a specific issue report using its unique identifier.

```APIDOC
## GET /v1/report-issue/{id}

### Description
Retrieves a specific issue report by its ID.

### Method
GET

### Endpoint
/v1/report-issue/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the issue report (UUID format).

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the issue report details.
  - **issueReport** (object) - The issue report object.
    - **id** (string) - The unique identifier of the issue report.
    - **transactionId** (string) - The ID of the associated transaction.
    - **description** (string) - A description of the issue.
    - **fields** (array) - A list of fields related to the issue.
    - **status** (string) - The current status of the issue report (e.g., pending, reviewing, resolved, dismissed).
    - **statusMessage** (string | null) - An optional message providing more details about the status.
    - **createdAt** (string) - The timestamp when the issue report was created.
    - **updatedAt** (string) - The timestamp when the issue report was last updated.
- **meta** (object) - Metadata about the response.
  - **generatedAt** (string) - The timestamp when the response was generated.
  - **requestId** (string) - The unique identifier for the request.
  - **version** (string) - The API version.

#### Error Responses
- **401** - Unauthorized: Authentication failed.
- **403** - Forbidden: Insufficient permissions.
- **404** - Not Found: The specified issue report ID does not exist.
- **422** - Validation Error: The request parameters are invalid.
- **429** - Rate Limited: Too many requests.
- **500** - Internal Server Error: An unexpected error occurred.
```

--------------------------------

### Basic Transaction Enrichment Request (Node.js)

Source: https://docs.triqai.com/guides/enriching-transactions

Perform a basic transaction enrichment using the Triqai Node.js SDK. Ensure your TRIQAI_API_KEY is set in the environment.

```typescript
import Triqai from "triqai";

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

const result = await triqai.transactions.enrich({
    title: "NETFLIX.COM",
    country: "US",
    type: "expense",
  });
```

--------------------------------

### List Transactions

Source: https://docs.triqai.com/api-reference/transactions/list-transactions

Fetches a list of transactions. Supports pagination and filtering by start and end dates.

```APIDOC
## GET /v1/transactions

### Description
Retrieves a paginated list of transactions. You can filter transactions by specifying a date range using `startDate` and `endDate`.

### Method
GET

### Endpoint
/v1/transactions

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number to retrieve. Minimum value is 1. Defaults to 1.
- **size** (integer) - Optional - The number of transactions per page. Minimum value is 1, maximum is 100. Defaults to 25.
- **startDate** (string) - Optional - Inclusive lower bound for filtering transactions by date (ISO 8601 timestamp).
- **endDate** (string) - Optional - Inclusive upper bound for filtering transactions by date (ISO 8601 timestamp).

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the transaction data and pagination information.
  - **transactions** (array) - An array of enriched transaction objects.
  - **pagination** (object) - Pagination details for the transaction list.
- **meta** (object) - Metadata about the response.

#### Response Example
{
  "success": true,
  "data": {
    "transactions": [
      {
        "transaction": {
          "id": "txn_123",
          "amount": 1000,
          "currency": "USD",
          "timestamp": "2023-10-27T10:00:00Z",
          "description": "Online purchase"
        },
        "entities": [
          {
            "id": "ent_456",
            "name": "Example Merchant"
          }
        ]
      }
    ],
    "pagination": {
      "page": 1,
      "size": 25,
      "total": 100,
      "totalPages": 4
    }
  },
  "meta": {
    "generatedAt": "2023-10-27T10:05:00Z",
    "requestId": "req_abc",
    "version": "1.3.21"
  }
}

#### Error Responses
- **401** - Unauthorized: Invalid API key.
- **403** - Forbidden: Insufficient permissions.
- **422** - Validation Error: Invalid query parameters.
- **429** - Rate Limited: Too many requests.
- **500** - Internal Server Error: An unexpected error occurred.
```

--------------------------------

### Get a Single Transaction by ID

Source: https://docs.triqai.com/sdk/transactions

Retrieve a specific enriched transaction record using its unique identifier.

```typescript
const tx = await triqai.transactions.get(
  "550e8400-e29b-41d4-a716-446655440000"
);
```

--------------------------------

### Triqai Validation Error Details

Source: https://docs.triqai.com/guides/error-handling

Example of a `validation_error` response, detailing specific field errors that occurred during a request.

```json
{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": {
      "fieldErrors": {
        "title": ["Title is required"],
        "country": ["Invalid country code. Use ISO 3166-1 alpha-2 format."],
        "type": ["Type must be 'expense' or 'income'"]
      }
    }
  }
}
```
Tokens:
Raw