> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useproxy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# KYC

> Know Your Customer verification for card issuance

# KYC

**KYC (Know Your Customer)** verification is required before customers can issue cards. Proxy handles identity verification through Rain's KYC infrastructure to comply with financial regulations.

## Why KYC?

Card issuance is a regulated activity. Before a customer can:

* Issue virtual cards
* Fund their account
* Make transactions

They must complete identity verification to prevent fraud and money laundering.

## Creating a KYC Application

Submit a KYC application with the customer's identity information:

```bash theme={"system"}
curl -X POST https://api.useproxy.ai/v1/kyc/applications \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_xxx",
    "application": {
      "firstName": "John",
      "lastName": "Doe",
      "birthDate": "1990-01-15",
      "nationalId": "123456789",
      "countryOfIssue": "US",
      "email": "john@example.com",
      "address": {
        "line1": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94102",
        "country": "US"
      },
      "ipAddress": "1.2.3.4",
      "occupation": "SOFTWARE_ENGINEER",
      "annualSalary": "100000_149999",
      "accountPurpose": "PERSONAL_SPENDING",
      "expectedMonthlyVolume": "1000_4999",
      "isTermsOfServiceAccepted": true,
      "phoneCountryCode": "1",
      "phoneNumber": "5551234567"
    }
  }'
```

### Required Fields

| Field                      | Type    | Description                                |
| -------------------------- | ------- | ------------------------------------------ |
| `firstName`                | string  | Customer's first name (max 50 chars)       |
| `lastName`                 | string  | Customer's last name (max 50 chars)        |
| `birthDate`                | string  | Date of birth in `YYYY-MM-DD` format       |
| `nationalId`               | string  | National ID (9-digit SSN for US customers) |
| `countryOfIssue`           | string  | 2-letter country code for national ID      |
| `email`                    | string  | Customer's email address                   |
| `address`                  | object  | Customer's physical address                |
| `ipAddress`                | string  | Customer's IP address                      |
| `occupation`               | string  | Customer's occupation code                 |
| `annualSalary`             | string  | Annual salary range                        |
| `accountPurpose`           | string  | Purpose of account                         |
| `expectedMonthlyVolume`    | string  | Expected monthly spend range               |
| `isTermsOfServiceAccepted` | boolean | Must be `true`                             |
| `phoneCountryCode`         | string  | Phone country code (e.g., "1" for US)      |
| `phoneNumber`              | string  | Phone number without country code          |

### Address Object

| Field        | Type   | Description                       |
| ------------ | ------ | --------------------------------- |
| `line1`      | string | Street address                    |
| `line2`      | string | Apartment, suite, etc. (optional) |
| `city`       | string | City                              |
| `state`      | string | State/province code               |
| `postalCode` | string | Postal/ZIP code                   |
| `country`    | string | 2-letter country code             |

### Optional Fields

| Field           | Type   | Description                                          |
| --------------- | ------ | ---------------------------------------------------- |
| `walletAddress` | string | EVM wallet address (auto-created if not provided)    |
| `solanaAddress` | string | Solana wallet address (auto-created if not provided) |

<Note>
  You don't need to provide a wallet address. Proxy automatically creates a secure server-managed wallet for each customer during KYC.
</Note>

### Occupation Codes

Common values:

* `SOFTWARE_ENGINEER`
* `PRODUCT_MANAGER`
* `BUSINESS_OWNER`
* `ACCOUNTANT`
* `CONSULTANT`
* `OTHER`

### Salary Ranges

* `0_24999`
* `25000_49999`
* `50000_99999`
* `100000_149999`
* `150000_249999`
* `250000_499999`
* `500000_PLUS`

### Monthly Volume Ranges

* `0_999`
* `1000_4999`
* `5000_9999`
* `10000_24999`
* `25000_49999`
* `50000_PLUS`

### Account Purpose

* `PERSONAL_SPENDING`
* `BUSINESS_EXPENSES`
* `PAYROLL`
* `VENDOR_PAYMENTS`

## Response

```json theme={"system"}
{
  "id": "app_xxx",
  "customerId": "cus_xxx",
  "status": "pending",
  "reason": null,
  "completionLink": "https://verify.example.com/complete/xyz789"
}
```

| Field            | Description                                          |
| ---------------- | ---------------------------------------------------- |
| `id`             | Application ID                                       |
| `customerId`     | Your customer ID                                     |
| `status`         | Current application status                           |
| `reason`         | Reason if status is not `approved`                   |
| `completionLink` | URL for customer to complete additional verification |

## Application Statuses

| Status              | Description                                                      |
| ------------------- | ---------------------------------------------------------------- |
| `pending`           | Application submitted, under review                              |
| `approved`          | Verified, customer can issue cards                               |
| `needsInformation`  | Additional info required                                         |
| `needsVerification` | Identity verification needed - send customer to `completionLink` |
| `manualReview`      | Flagged for manual review                                        |
| `denied`            | Application rejected                                             |
| `locked`            | Account locked                                                   |

## KYC Flow

<Steps>
  <Step title="Create Customer">
    Create a customer record via `POST /v1/customers`
  </Step>

  <Step title="Submit KYC Application">
    Submit application with all required identity fields
  </Step>

  <Step title="Check Status">
    Response indicates if additional verification is needed
  </Step>

  <Step title="Complete Verification">
    If `needsVerification`, direct customer to `completionLink` to upload ID documents
  </Step>

  <Step title="Wait for Approval">
    Poll status or receive webhook when application is approved
  </Step>

  <Step title="Issue Cards">
    Once `approved`, customer can issue virtual cards
  </Step>
</Steps>

## Checking Application Status

```bash theme={"system"}
curl https://api.useproxy.ai/v1/kyc/applications/app_xxx \
  -H "Authorization: Bearer sk_live_xxx"
```

Response:

```json theme={"system"}
{
  "id": "app_xxx",
  "customerId": "cus_xxx",
  "status": "needsVerification",
  "reason": "Identity verification required",
  "completionLink": "https://verify.example.com/complete/xyz789"
}
```

## Completion Link

When status is `needsInformation` or `needsVerification`, the response includes a `completionLink`. Direct your customer to this URL to complete the verification process (e.g., upload government ID).

<Warning>
  Completion links expire after 24 hours. Request a new application status to get a fresh link if needed.
</Warning>

## Webhooks

Subscribe to KYC events for real-time updates:

| Event          | Description                         |
| -------------- | ----------------------------------- |
| `kyc.approved` | Customer approved for card issuance |
| `kyc.rejected` | Application was rejected            |

## Next Steps

<CardGroup cols={2}>
  <Card title="Customers" icon="user" href="/concepts/customers">
    Learn about customer management
  </Card>

  <Card title="Cards" icon="credit-card" href="/concepts/cards">
    Issue cards after KYC approval
  </Card>
</CardGroup>