Customers

Customers are the foundation of the Infinite platform. They represent individuals or businesses that will be onboarded for verification and payment processing.

Restricted Countries

Infinite cannot onboard customers from certain countries due to regulatory restrictions. These include OFAC-sanctioned countries and other jurisdictions with compliance limitations. OFAC Sanctioned Countries:

Cuba (CU)
Iran (IR)
North Korea (KP)
Russia (RU)
Syria (SY)

Additional Restricted Countries:

Ukraine (UA)

Attempting to create or update a customer with a country code from a restricted country will result in a 400 Bad Request error. The country selection will be automatically filtered in the verification UI.

Customer Types

Infinite supports two primary customer types:

Individual Customers

Individual customers represent natural persons who need to complete personal KYC verification.

{
  "id": "cus_individual_123",
  "customerName": "John Doe",
  "email": "john@example.com",
  "type": "INDIVIDUAL",
  "countryCode": "US",
  "status": "DRAFT"
}

Business Customers

Business customers represent companies or organizations that require business verification and beneficial ownership disclosure.

{
  "id": "cus_business_456",
  "customerName": "Acme Corp",
  "email": "compliance@acme.com",
  "type": "BUSINESS",
  "countryCode": "US",
  "status": "IN_REVIEW"
}

Intent-Based State Machine

Customer creation follows an intent-based state machine pattern. This means you create a customer as an “intent” in DRAFT status, progressively add data, and explicitly submit when ready for verification.

Compliance can also move a customer to INACTIVE or SUSPENDED from any non-terminal status, and reopen a REJECTED or INACTIVE customer for re-review.

Why Intent-Based?

Progressive data collection: Build up customer data over multiple API calls without triggering validation until you’re ready
Flexible workflows: Collect information in any order, from any source
Clear submission point: Explicitly control when verification begins
RFI handling: Easy loop for handling requests for additional information

Customer Status

Status	Description	Capabilities
`DRAFT`	Customer intent created, data collection in progress	`IN_REVIEW` at best
`IN_REVIEW`	Submitted for verification, under compliance review	`IN_REVIEW` at best
`NEED_ACTIONS`	Verification requires additional information (RFI)	`IN_REVIEW` at best
`ACTIVE`	KYC/KYB verification passed, compliance approved	`READY` as each capability’s onboarding completes
`REJECTED`	Verification failed or compliance issues	`UNAVAILABLE`
`SUSPENDED`	Account temporarily suspended	`UNAVAILABLE`
`INACTIVE`	Customer offboarded or deactivated	`UNAVAILABLE`

ACTIVE means the customer passed Infinite’s compliance review — it is a prerequisite for transacting, not a guarantee that every capability is ready. Individual capabilities (e.g. balance accounts, specific payment rails) become READY as their underlying onboarding completes. Check the customer capabilities endpoint or subscribe to customer.capability.updated webhooks.

Customer Creation Patterns

Pattern 1: Intent-First (Recommended)

Create customer in DRAFT status, add data progressively, then submit.

Create Intent

Create customer with basic info. Customer starts in DRAFT status.

Add Data

Use PATCH /customers/:id to add verification data, documents, addresses as you collect them.

Submit

Call POST /customers/:id/submit when ready. Customer transitions to IN_REVIEW.

Handle RFI (if needed)

If status becomes NEED_ACTIONS, add missing data via PATCH and re-submit.

Step 1: Create Intent

import requests

response = requests.post(
    'https://api.infinite.dev/v1/customers/individuals',
    headers={
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json',
    },
    json={
        'customerName': 'Jane Smith',
        'countryCode': 'US',
        'email': 'jane@example.com',
    },
)

const response = await fetch(
  'https://api.infinite.dev/v1/customers/individuals',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer sk_live_...',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      customerName: 'Jane Smith',
      countryCode: 'US',
      email: 'jane@example.com',
    }),
  },
);

export INFINITE_API_KEY=sk_live_...
infinite api POST /v1/customers/individuals --body '{
  "customerName": "Jane Smith",
  "countryCode": "US",
  "email": "jane@example.com"
}'

Create an individual customer Jane Smith (jane@example.com) in the US.

# Infinite MCP is read-only today — run the CLI tab to execute.

curl -X POST "https://api.infinite.dev/v1/customers/individuals" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customerName": "Jane Smith",
    "countryCode": "US",
    "email": "jane@example.com"
  }'
# Response: { "id": "cus_abc123", "status": "DRAFT", ... }

Step 2: Add Data

import requests

response = requests.patch(
    'https://api.infinite.dev/v1/customers/cus_abc123',
    headers={
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json',
    },
    json={
        'customerDetails': {
            'firstName': 'Jane',
            'lastName': 'Smith',
            'dateOfBirth': '1990-01-15',
            'phone': '+14155551234',
        },
        'addresses': [
            {
                'addressLine1': '123 Main St',
                'city': 'San Francisco',
                'state': 'CA',
                'postalCode': '94102',
                'country': 'US',
            }
        ],
    },
)

const response = await fetch(
  'https://api.infinite.dev/v1/customers/cus_abc123',
  {
    method: 'PATCH',
    headers: {
      Authorization: 'Bearer sk_live_...',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      customerDetails: {
        firstName: 'Jane',
        lastName: 'Smith',
        dateOfBirth: '1990-01-15',
        phone: '+14155551234',
      },
      addresses: [
        {
          addressLine1: '123 Main St',
          city: 'San Francisco',
          state: 'CA',
          postalCode: '94102',
          country: 'US',
        },
      ],
    }),
  },
);

export INFINITE_API_KEY=sk_live_...
infinite customers update cus_abc123 --body '{
  "customerDetails": {
    "firstName": "Jane",
    "lastName": "Smith",
    "dateOfBirth": "1990-01-15",
    "phone": "+14155551234"
  },
  "addresses": [{
    "addressLine1": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94102",
    "country": "US"
  }]
}'

Update cus_abc123: first name Jane, last name Smith, born 1990-01-15, phone +14155551234, address 123 Main St, San Francisco, CA 94102, US.

# Infinite MCP is read-only today — run the CLI tab to execute.

curl -X PATCH "https://api.infinite.dev/v1/customers/cus_abc123" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customerDetails": {
      "firstName": "Jane",
      "lastName": "Smith",
      "dateOfBirth": "1990-01-15",
      "phone": "+14155551234"
    },
    "addresses": [{
      "addressLine1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94102",
      "country": "US"
    }]
  }'

Step 3: Submit

import requests

response = requests.post(
    'https://api.infinite.dev/v1/customers/cus_abc123/submit',
    headers={
        'Authorization': 'Bearer sk_live_...',
    },
)

const response = await fetch(
  'https://api.infinite.dev/v1/customers/cus_abc123/submit',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer sk_live_...',
    },
  },
);

export INFINITE_API_KEY=sk_live_...
infinite api POST /v1/customers/cus_abc123/submit

Submit customer cus_abc123 for verification.

# Infinite MCP is read-only today — run the CLI tab to execute.

curl -X POST "https://api.infinite.dev/v1/customers/cus_abc123/submit" \
  -H "Authorization: Bearer sk_live_..."
# Response: { "id": "cus_abc123", "status": "IN_REVIEW", ... }

Pattern 2: Immediate Submission

If you have all data upfront, create the customer first, then save verification and request review in the same call using ?submit=true.

Step 1: Create Customer

import requests

response = requests.post(
    'https://api.infinite.dev/v1/customers/individuals',
    headers={
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json',
    },
    json={
        'customerName': 'Jane Smith',
        'countryCode': 'US',
        'email': 'jane@example.com',
    },
)

const response = await fetch(
  'https://api.infinite.dev/v1/customers/individuals',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer sk_live_...',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      customerName: 'Jane Smith',
      countryCode: 'US',
      email: 'jane@example.com',
    }),
  },
);

export INFINITE_API_KEY=sk_live_...
infinite api POST /v1/customers/individuals --body '{
  "customerName": "Jane Smith",
  "countryCode": "US",
  "email": "jane@example.com"
}'

Create an individual customer Jane Smith (jane@example.com) in the US.

# Infinite MCP is read-only today — run the CLI tab to execute.

curl -X POST "https://api.infinite.dev/v1/customers/individuals" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customerName": "Jane Smith",
    "countryCode": "US",
    "email": "jane@example.com"
  }'
# Response: { "id": "cus_abc123", "status": "DRAFT", ... }

Step 2: Save and Submit

import requests

response = requests.post(
    'https://api.infinite.dev/v1/customers/cus_abc123/verification/individual',
    headers={
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json',
    },
    params={'submit': 'true'},
    json={
        'firstName': 'Jane',
        'lastName': 'Smith',
        'email': 'jane@example.com',
        'dateOfBirth': '1990-01-15',
        'phone': '+14155551234',
        'address': {
            'addressLine1': '123 Main St',
            'city': 'San Francisco',
            'state': 'CA',
            'postalCode': '94102',
            'country': 'US',
        },
    },
)

const response = await fetch(
  'https://api.infinite.dev/v1/customers/cus_abc123/verification/individual?submit=true',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer sk_live_...',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      firstName: 'Jane',
      lastName: 'Smith',
      email: 'jane@example.com',
      dateOfBirth: '1990-01-15',
      phone: '+14155551234',
      address: {
        addressLine1: '123 Main St',
        city: 'San Francisco',
        state: 'CA',
        postalCode: '94102',
        country: 'US',
      },
    }),
  },
);

export INFINITE_API_KEY=sk_live_...
infinite api POST '/v1/customers/cus_abc123/verification/individual?submit=true' --body '{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "jane@example.com",
  "dateOfBirth": "1990-01-15",
  "phone": "+14155551234",
  "address": {
    "addressLine1": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94102",
    "country": "US"
  }
}'

Save and submit verification for cus_abc123: Jane Smith, jane@example.com, born 1990-01-15, phone +14155551234, address 123 Main St, San Francisco, CA 94102, US.

# Infinite MCP is read-only today — run the CLI tab to execute.

curl -X POST "https://api.infinite.dev/v1/customers/cus_abc123/verification/individual?submit=true" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "jane@example.com",
    "dateOfBirth": "1990-01-15",
    "phone": "+14155551234",
    "address": {
      "addressLine1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94102",
      "country": "US"
    }
  }'
# Response: data is saved. Status stays DRAFT until every required
# field and document is present, then becomes IN_REVIEW.
# {
#   "customerId": "cus_abc123",
#   "status": "DRAFT",
#   "missingRequirements": [
#     { "requirementType": "FIELD", "key": "metadata.infiniteTosAcceptanceId", "displayName": "Infinite Terms of Service & Privacy Policy" },
#     { "requirementType": "DOCUMENT", "key": "identity.government_id_front", "displayName": "Government ID" }
#   ]
# }

Business customers use POST /customers/businesses then POST /customers/:id/verification/business.

?submit=true does not fail when data is incomplete. The payload is saved and the customer stays in DRAFT with missingRequirements. Status becomes IN_REVIEW only after every required field and document is present. Check customer compliance requirements or the individual verification payload for the full set.

Handling Request for Information (RFI)

When verification requires additional data, the customer status changes to NEED_ACTIONS and the response includes missingFields and/or missingDocuments.

{
  "id": "cus_abc123",
  "status": "NEED_ACTIONS",
  "missingFields": [
    { "fieldPath": "individualData.occupation", "displayName": "Occupation" },
    { "fieldPath": "individualData.sourceOfIncome", "displayName": "Source of Income" }
  ],
  "missingDocuments": [
    { "documentType": "government_id", "displayName": "Government ID" }
  ]
}

To resolve:

Add the missing data via PATCH /customers/:id
Upload any missing documents via POST /documents
Re-submit via POST /customers/:id/submit

Customer Data

Required Fields

customerName - Full name (individual) or company name (business)

Customer type is chosen by the endpoint: POST /customers/individuals or POST /customers/businesses. Do not send type on those requests.

Recommended Fields

email - Primary contact email address
countryCode - ISO 3166-1 alpha-2 country code

Core Profile Fields

Send profile fields at the top level of the create request — POST /customers/individuals for individuals and POST /customers/businesses for businesses. Use customerDetails on PATCH /customers/:id when updating the saved customer profile. Use POST /customers/:id/verification/individual or POST /customers/:id/verification/business for full verification payloads. For Individual customers:

firstName, lastName, middleName
dateOfBirth (YYYY-MM-DD format)
phone with country code
occupation, sourceOfIncome
Transliteration fields when names contain non-Latin characters

occupation should be provided as an occupation code, for example 151252. sourceOfIncome is an enum field and should use values like SALARY, COMPANY_FUNDS, INVESTMENTS_LOANS, INHERITANCE, SAVINGS, or PENSION_RETIREMENT. For Business customers:

businessName, tradeName
businessType (LLC, Corp, etc.)
taxId
yearEstablished
website, industry

Working with Customers

Retrieving Customers

Get All Customers

import requests

response = requests.get(
    'https://api.infinite.dev/v1/customers',
    headers={'Authorization': 'Bearer sk_live_...'},
)

const response = await fetch('https://api.infinite.dev/v1/customers', {
  headers: {
    Authorization: 'Bearer sk_live_...',
  },
});

export INFINITE_API_KEY=sk_live_...
infinite customers list --limit 10

List all my customers.

curl -X GET "https://api.infinite.dev/v1/customers" \
  -H "Authorization: Bearer sk_live_..."

Get Specific Customer

import requests

response = requests.get(
    'https://api.infinite.dev/v1/customers/cus_abc123',
    headers={'Authorization': 'Bearer sk_live_...'},
)

const response = await fetch(
  'https://api.infinite.dev/v1/customers/cus_abc123',
  {
    headers: {
      Authorization: 'Bearer sk_live_...',
    },
  },
);

export INFINITE_API_KEY=sk_live_...
infinite customers get cus_abc123

Show me customer cus_abc123.

curl -X GET "https://api.infinite.dev/v1/customers/cus_abc123" \
  -H "Authorization: Bearer sk_live_..."

Filter by Status

import requests

response = requests.get(
    'https://api.infinite.dev/v1/customers',
    headers={'Authorization': 'Bearer sk_live_...'},
    params={'status': 'DRAFT'},
)

const response = await fetch(
  'https://api.infinite.dev/v1/customers?status=DRAFT',
  {
    headers: {
      Authorization: 'Bearer sk_live_...',
    },
  },
);

export INFINITE_API_KEY=sk_live_...
infinite customers list --status DRAFT --limit 10

List customers still in DRAFT.

curl -X GET "https://api.infinite.dev/v1/customers?status=DRAFT" \
  -H "Authorization: Bearer sk_live_..."

Updating Customers

Update customer data at any time while in DRAFT or NEED_ACTIONS status: For individual customer profile updates, send occupation as an occupation code and sourceOfIncome as an enum value.

import requests

response = requests.patch(
    'https://api.infinite.dev/v1/customers/cus_abc123',
    headers={
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json',
    },
    json={
        'customerDetails': {
            'occupation': '151252',
            'sourceOfIncome': 'SALARY',
        },
    },
)

const response = await fetch(
  'https://api.infinite.dev/v1/customers/cus_abc123',
  {
    method: 'PATCH',
    headers: {
      Authorization: 'Bearer sk_live_...',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      customerDetails: {
        occupation: '151252',
        sourceOfIncome: 'SALARY',
      },
    }),
  },
);

export INFINITE_API_KEY=sk_live_...
infinite customers update cus_abc123 --body '{
  "customerDetails": {
    "occupation": "151252",
    "sourceOfIncome": "SALARY"
  }
}'

Update cus_abc123's occupation to 151252 and source of income to SALARY.

# Infinite MCP is read-only today — run the CLI tab to execute.

curl -X PATCH "https://api.infinite.dev/v1/customers/cus_abc123" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customerDetails": {
      "occupation": "151252",
      "sourceOfIncome": "SALARY"
    }
  }'

Best Practices

Use idempotency keys

Always include an Idempotency-Key header when creating customers to prevent duplicate records from retries.

Collect data progressively

Use the intent pattern to collect data across multiple sessions or sources without worrying about validation until submission.

Handle RFI proactively

Check missingFields and missingDocuments on customer responses to understand what’s needed before submission.

Monitor status via webhooks

Subscribe to customer.status_changed webhooks to react to status changes, and customer.capability.updated to know when a capability becomes ready.

Next Steps

Once you’ve created a customer, the next step is typically to initiate verification to comply with KYC/AML requirements.

Verification

Learn how to verify customer identities for compliance

Create Customer API

Full API reference for customer creation

Get started

Core Concepts

Guides

Restricted Countries

Customer Types

Individual Customers

Business Customers

Intent-Based State Machine

Why Intent-Based?

Customer Status

Customer Creation Patterns

Pattern 1: Intent-First (Recommended)

Step 1: Create Intent

Step 2: Add Data

Step 3: Submit

Pattern 2: Immediate Submission

Step 1: Create Customer

Step 2: Save and Submit

Handling Request for Information (RFI)

Customer Data

Required Fields

Recommended Fields

Core Profile Fields

Working with Customers

Retrieving Customers

Get All Customers

Get Specific Customer

Filter by Status

Updating Customers

Best Practices

Next Steps

Verification

Create Customer API

​Restricted Countries

​Customer Types

​Individual Customers

​Business Customers

​Intent-Based State Machine

​Why Intent-Based?

​Customer Status

​Customer Creation Patterns

​Pattern 1: Intent-First (Recommended)

​Step 1: Create Intent

​Step 2: Add Data

​Step 3: Submit

​Pattern 2: Immediate Submission

​Step 1: Create Customer

​Step 2: Save and Submit

​Handling Request for Information (RFI)

​Customer Data

​Required Fields

​Recommended Fields

​Core Profile Fields

​Working with Customers

​Retrieving Customers

​Get All Customers

​Get Specific Customer

​Filter by Status

​Updating Customers

​Best Practices

​Next Steps

Verification

Create Customer API

Restricted Countries

Customer Types

Individual Customers

Business Customers

Intent-Based State Machine

Why Intent-Based?

Customer Status

Customer Creation Patterns

Pattern 1: Intent-First (Recommended)

Step 1: Create Intent

Step 2: Add Data

Step 3: Submit

Pattern 2: Immediate Submission

Step 1: Create Customer

Step 2: Save and Submit

Handling Request for Information (RFI)

Customer Data

Required Fields

Recommended Fields

Core Profile Fields

Working with Customers

Retrieving Customers

Get All Customers

Get Specific Customer

Filter by Status

Updating Customers

Best Practices

Next Steps