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.

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:

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

List Verifications

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

curl https://api.atlas.co/functions/v1/kyc-verifications/kyc_abc123 \
  -H "Authorization: Bearer sk_test_xxx"

Response:

{
  "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.

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.

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.

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:

<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

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 });
});

Getting Started

Payments

UI Components

Billing

Data & Security

Mobile

Developer

KYC Verification

Overview

Supported Providers

Verification Levels

API Reference

Create Verification

List Verifications

Get Verification

Submit for Review

Approve Verification

Reject Verification

Verification Statuses

Frontend Integration (Persona)

Webhooks

​Overview

​Supported Providers

​Verification Levels

​API Reference

​Create Verification

​List Verifications

​Get Verification

​Submit for Review

​Approve Verification

​Reject Verification

​Verification Statuses

​Frontend Integration (Persona)

​Webhooks

Overview

Supported Providers

Verification Levels

API Reference

Create Verification

List Verifications

Get Verification

Submit for Review

Approve Verification

Reject Verification

Verification Statuses

Frontend Integration (Persona)

Webhooks