Skip to main content
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

ProviderFeatures
PersonaDocument verification, selfie matching, watchlist screening
AlloyIdentity verification, fraud detection, decisioning
SocureIdentity verification, document verification, KYC
ManualManual review workflow

​
Verification Levels

LevelDescription
basicName + email verification
standardID document + selfie verification
enhancedID + address verification + watchlist screening
businessBusiness 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:
ParameterTypeRequiredDescription
customer_idstring*Atlas customer ID
external_customer_idstring*Your customer ID (if not using Atlas customers)
verification_levelstringNobasic, standard, enhanced, business (default: standard)
providerstringNopersona, alloy, socure, manual (default: persona)
pii_tokensobjectNoMap of identity tokens (e.g., ssn: “id_xxx”)
metadataobjectNoCustom 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:
ParameterTypeDescription
statusstringFilter by status
customer_idstringFilter by customer
limitintegerResults per page (max 100)
offsetintegerPagination 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

StatusDescription
pendingVerification created, awaiting customer action
submittedCustomer submitted documents, under review
approvedVerification passed
rejectedVerification 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 });
});