Sender

The Sender is the participant who initiates and pays for a transaction. Every sender must pass through KYC (Know Your Customer) screening, and their transaction limits are determined by their compliance level.

Initial Compliance Setup

At the beginning of your integration, the Inyo compliance team works with your organization to define a custom compliance framework tailored to your product and customer profile. This framework determines:

• Compliance levels — tiers that define how much a customer can send within set timeframes (24h, 30d, 180d)
• Validation rules — the required data and documents for each level (e.g., name, SSN, proof of income)
• Risk controls — thresholds that trigger enhanced due diligence

This configuration is unique per tenant and directly impacts how participants are verified and which operations they can perform.

Creating a Sender

Endpoint: POST /organizations/{tenant}/people
Authentication: Tenant-level (x-api-key)

No fields are technically required to create a person — but to use them as a sender, they must reach at least Compliance Level 1, which typically requires first name, last name, address, and phone number.

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/people \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --data '{
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "birthDate": "1990-01-15",
  "phoneNumber": "+15551234567",
  "gender": "Male",
  "externalId": "your-internal-id-001",
  "address": {
    "countryCode": "US",
    "stateCode": "CA",
    "city": "San Francisco",
    "line1": "123 Market St",
    "zipcode": "94105"
  },
  "documents": [
    {
      "type": "SSN",
      "document": "123456789",
      "countryCode": "US"
    }
  ],
  "occupation": "Software Engineer"
}'

Request Fields

Sample Response

{
  "id": "48066496-9445-41b7-acbe-85e069a77cb7",
  "firstName": "John",
  "lastName": "Doe",
  "mainAddressId": "9c2ea7e5-51a2-4ea1-83cf-8948754486f8",
  "phoneNumber": "+15551234567",
  "email": "[email protected]",
  "gender": "Male",
  "birthDate": "1990-01-15",
  "externalId": "your-internal-id-001",
  "updatedAt": "2025-01-15T12:00:00",
  "documents": [],
  "occupation": "Software Engineer",
  "documentId": null,
  "sourceOfFundsId": null,
  "employerName": null,
  "employerAddressId": null
}

⚠️ Save the returned id — this is the senderId used in all subsequent API calls.

Updating a Sender

Endpoint: PATCH /organizations/{tenant}/people/{personId}
Authentication: Tenant-level

Only fields included in the request body are updated; omitted fields remain unchanged.

curl --request PATCH \
  --url https://{FQDN}/organizations/$TENANT/people/$PERSON_ID \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --data '{
  "occupation": "Consultant",
  "documents": [
    {
      "type": "SSN",
      "document": "987654321",
      "countryCode": "US"
    }
  ]
}'

Address Verification

US addresses are automatically validated through USPS APIs. If validation fails, the sender's transactions will be placed on hold until the compliance team manually verifies the address.

Verify an address before submitting:

curl --request GET \
  --url "https://{FQDN}/organizations/$TENANT/addresses/check?countryCode=US&stateCode=CA&city=San+Francisco&line1=123+Market+St&line2=&zipCode=94105" \
  --header "x-api-key: $API_KEY"

Creating Business Senders (KYB)

For B2B use cases, you can create a company as a sender:

Endpoint: POST /organizations/{tenant}/companies
Authentication: Tenant-level

Companies follow a similar compliance level system but with different required fields (business registration, EIN, etc.). Contact your Inyo account manager for your tenant-specific KYB configuration.

Compliance Levels

⚠️ These are customizable per tenant. See Trust Level Limits for details.

Best Practices

• Progressive onboarding — Collect only Level 1 fields at signup. Prompt for more data when the user needs higher limits.
• Pre-validate addresses — Use the address check endpoint before creating the sender to avoid holds.
• Sync compliance state — After profile updates, re-check the compliance level to see if it has upgraded.
• Handle restricted users — If a sender is Restricted, check GET /participants/{id}/complianceLevels to understand why and what action is needed.

Related Pages

• Trust Level Limits — Check and upgrade compliance levels
• Uploading Documents — Submit ID and source-of-funds documents
• Test Data — Sandbox testing scenarios for compliance flows

All Endpoints

Interactive API Documentation