Trust Level Limits

The Trust Level (Compliance Level) system controls how much a sender is allowed to transact. Higher levels require more KYC data and documents but unlock higher transaction limits across three rolling time windows: 24 hours, 30 days, and 180 days.

Checking Compliance Level

Endpoint: GET /organizations/{tenant}/participants/{participantId}/complianceLevels
Authentication: Tenant-level (x-api-key)

curl --request GET \
  --url https://{FQDN}/organizations/$TENANT/participants/$SENDER_ID/complianceLevels \
  --header "x-api-key: $API_KEY"

This endpoint returns:

• The participant's current compliance level and its limits
• The next available level and its required fields
• The fields the participant is still missing to reach the next level

Sample Response

A participant at LEVEL_0 (cannot transact yet) with upgrade path to LEVEL_1:

{
  "participantId": "48066496-9445-41b7-acbe-85e069a77cb7",
  "currentComplianceLevel": {
    "level": "LEVEL_0",
    "limits": {
      "oneDayLimit": { "amount": "0.00", "currency": "USD" },
      "thirtyDaysLimit": { "amount": "0.00", "currency": "USD" },
      "oneHundredAndEightyDaysLimit": { "amount": "0.00", "currency": "USD" }
    },
    "requiredFields": [],
    "perTransactionFields": []
  },
  "nextComplianceLevel": {
    "level": "LEVEL_1",
    "limits": {
      "oneDayLimit": { "amount": "2999.00", "currency": "USD" },
      "thirtyDaysLimit": { "amount": "6000.00", "currency": "USD" },
      "oneHundredAndEightyDaysLimit": { "amount": "9999.00", "currency": "USD" }
    },
    "requiredFields": [
      "firstName",
      "lastName",
      "phoneNumber",
      "residentialAddress"
    ],
    "perTransactionFields": []
  },
  "missingFieldsForNextComplianceLevel": [
    "phoneNumber",
    "residentialAddress"
  ]
}

Key fields:

• currentComplianceLevel — the level the participant qualifies for right now (LEVEL_0 with zero limits when no data has been provided)
• nextComplianceLevel.requiredFields — everything the next level requires
• missingFieldsForNextComplianceLevel — the subset the participant hasn't provided yet — drive your progressive-onboarding UI from this list

Compliance Level Overview

These levels are customizable per tenant. Your specific required fields and limits are defined during the Inyo onboarding process and may differ from the defaults shown above.

Checking Transaction Limits & Usage

To see how much of their limit a sender has already used:

Endpoint: GET /organizations/{tenant}/fx/participants/{participantId}/limits
Authentication: Agent-level (x-api-key + x-agent-id + x-agent-api-key)

curl --request GET \
  --url https://{FQDN}/organizations/$TENANT/fx/participants/$SENDER_ID/limits \
  --header "x-api-key: $API_KEY" \
  --header "x-agent-id: $AGENT_ID" \
  --header "x-agent-api-key: $AGENT_KEY"

Sample Response:

{
  "oneDayLimit": {
    "limit": { "amount": "2999.00", "currency": "USD" },
    "used": { "amount": "500.00", "currency": "USD" },
    "available": { "amount": "2499.00", "currency": "USD" }
  },
  "thirtyDaysLimit": {
    "limit": { "amount": "6000.00", "currency": "USD" },
    "used": { "amount": "2959.99", "currency": "USD" },
    "available": { "amount": "3040.01", "currency": "USD" }
  },
  "oneHundredAndEightyDaysLimit": {
    "limit": { "amount": "9999.00", "currency": "USD" },
    "used": { "amount": "5000.00", "currency": "USD" },
    "available": { "amount": "4999.00", "currency": "USD" }
  }
}

Key fields:

• limit — Maximum amount for this time window (from the participant's current compliance level)
• used — Amount already consumed in the rolling window (only transactions that count toward limits — declined/cancelled ones don't)
• available — Remaining capacity (limit - used)

The limits reported here stay in lockstep with GET /participants/{id}/complianceLevels — both endpoints answer with the same numbers, and available is computed with the same rules the transaction validator applies.

Upgrading a Sender's Level

To move a sender from one level to the next:

1. Check current level — GET /participants/{id}/complianceLevels
2. Identify missing fields — Look at missingFieldsForNextComplianceLevel
3. Collect the data — Update the sender's profile with the missing fields:
   • Use PATCH /people/{personId} for profile fields (SSN, occupation, etc.)
   • Use PUT /people/{personId}/address for address updates
   • Use document upload endpoints for ID documents and source of funds
4. Verify the upgrade — Call the compliance levels endpoint again to confirm the level increased

flowchart TD
    L0["LEVEL_0<br/>cannot transact"] -->|"+ name, address"| L1["LEVEL_1<br/>standard limits"]
    L1 -->|"+ SSN, documents"| L2["LEVEL_2<br/>enhanced limits"]
    L2 -->|"+ proof of funds"| L3["LEVEL_3<br/>maximum limits"]

Use Cases

• Progressive onboarding — Start with minimal data (Level 1) and prompt for more only when the user needs higher limits.
• Limit warnings — Show users their remaining capacity before they initiate a transaction.
• Upgrade prompts — When a transaction would exceed the current limit, show exactly which fields are missing and guide the user to complete them.
• Compliance dashboard — Display a visual progress bar showing the user's level and what's needed for the next tier.

Tracking Document Review

To show users that their documents are under review, subscribe to the DocumentUpdatedEvents webhook — it covers both KYC verification sessions and uploads. Either flow can also be polled: read the session for a KYC verification, or verification status per document for an upload. Neither poll covers the other flow.