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

# KYC Verification

Identity verification and compliance screening with provider abstraction.

## Overview

Atlas provides KYC orchestration that integrates with leading identity verification providers. Start verifications, track status, and handle compliance workflows.

## Supported Providers

| Provider    | Features                                                    |
| ----------- | ----------------------------------------------------------- |
| **Persona** | Document verification, selfie matching, watchlist screening |
| **Alloy**   | Identity verification, fraud detection, decisioning         |
| **Socure**  | Identity verification, document verification, KYC           |
| **Manual**  | Manual review workflow                                      |

## Verification Levels

| Level      | Description                                      |
| ---------- | ------------------------------------------------ |
| `basic`    | Name + email verification                        |
| `standard` | ID document + selfie verification                |
| `enhanced` | ID + address verification + watchlist screening  |
| `business` | Business entity verification + beneficial owners |

## API Reference

### Create Verification

Start a new KYC verification for a customer.

```bash theme={null}
curl -X POST https://api.atlas.co/functions/v1/kyc-verifications \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_abc123",
    "verification_level": "standard",
    "provider": "persona",
    "metadata": {
      "purpose": "account_opening"
    }
  }'
```

**Parameters:**

| Parameter              | Type   | Required | Description                                             |
| ---------------------- | ------ | -------- | ------------------------------------------------------- |
| `customer_id`          | string | \*       | Atlas customer ID                                       |
| `external_customer_id` | string | \*       | Your customer ID (if not using Atlas customers)         |
| `verification_level`   | string | No       | basic, standard, enhanced, business (default: standard) |
| `provider`             | string | No       | persona, alloy, socure, manual (default: persona)       |
| `pii_tokens`           | object | No       | Map of identity tokens (e.g., ssn: "id\_xxx")           |
| `metadata`             | object | No       | Custom metadata                                         |

\*One of `customer_id` or `external_customer_id` is required.

**Response:**

```json theme={null}
{
  "id": "kyc_abc123",
  "status": "pending",
  "verification_level": "standard",
  "provider": "persona",
  "provider_session_token": "inq_xxx...",
  "created_at": "2025-01-21T12:00:00Z"
}
```

### List Verifications

```bash theme={null}
curl "https://api.atlas.co/functions/v1/kyc-verifications?status=pending&limit=20" \
  -H "Authorization: Bearer sk_test_xxx"
```

**Query Parameters:**

| Parameter     | Type    | Description                |
| ------------- | ------- | -------------------------- |
| `status`      | string  | Filter by status           |
| `customer_id` | string  | Filter by customer         |
| `limit`       | integer | Results per page (max 100) |
| `offset`      | integer | Pagination offset          |

### Get Verification

```bash theme={null}
curl https://api.atlas.co/functions/v1/kyc-verifications/kyc_abc123 \
  -H "Authorization: Bearer sk_test_xxx"
```

**Response:**

```json theme={null}
{
  "id": "kyc_abc123",
  "status": "approved",
  "verification_level": "standard",
  "provider": "persona",
  "risk_score": 15,
  "created_at": "2025-01-21T12:00:00Z",
  "submitted_at": "2025-01-21T12:05:00Z",
  "completed_at": "2025-01-21T12:06:00Z",
  "checks": [
    {
      "id": "chk_xxx",
      "check_type": "document_verification",
      "status": "passed",
      "confidence_score": 0.98
    },
    {
      "id": "chk_yyy",
      "check_type": "selfie_match",
      "status": "passed",
      "confidence_score": 0.95
    }
  ]
}
```

### Submit for Review

Move a pending verification to submitted status.

```bash theme={null}
curl -X POST https://api.atlas.co/functions/v1/kyc-verifications/kyc_abc123/submit \
  -H "Authorization: Bearer sk_test_xxx"
```

### Approve Verification

Manually approve a verification.

```bash theme={null}
curl -X POST https://api.atlas.co/functions/v1/kyc-verifications/kyc_abc123/approve \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Documents verified manually",
    "risk_score": 10
  }'
```

### Reject Verification

Manually reject a verification.

```bash theme={null}
curl -X POST https://api.atlas.co/functions/v1/kyc-verifications/kyc_abc123/reject \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Document appears fraudulent"
  }'
```

## Verification Statuses

| Status      | Description                                    |
| ----------- | ---------------------------------------------- |
| `pending`   | Verification created, awaiting customer action |
| `submitted` | Customer submitted documents, under review     |
| `approved`  | Verification passed                            |
| `rejected`  | Verification failed                            |

## Frontend Integration (Persona)

Use the provider session token to embed the verification flow:

```html theme={null}
<script src="https://cdn.withpersona.com/dist/persona-v4.js"></script>

<script>
const client = new Persona.Client({
  templateId: 'tmpl_xxx',
  sessionToken: 'inq_xxx...', // From kyc-verifications response
  onComplete: ({ inquiryId, status }) => {
    // Notify your backend
    fetch('/api/kyc-complete', {
      method: 'POST',
      body: JSON.stringify({ inquiryId, status })
    });
  }
});

client.open();
</script>
```

## Webhooks

Listen for KYC events:

* `identity.verification.submitted` - Customer submitted verification
* `identity.verification.approved` - Verification approved
* `identity.verification.rejected` - Verification rejected

```javascript theme={null}
app.post('/webhooks/atlas', (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'identity.verification.approved':
      await activateAccount(event.data.customer_id);
      break;
    case 'identity.verification.rejected':
      await notifyCustomer(event.data);
      break;
  }

  res.json({ received: true });
});
```