🚀 Getting Started with the Lucy KYB API Suite

Welcome to the Lucy KYB API Suite! This guide walks you through the core steps to get up and running quickly, from authentication to document validation and data extraction.

✅ Step 1: Authenticate

All requests to the Lucy API require a bearer token. Make sure you have your credentials from the Zenpli team.

Example: Get a token

POST /auth/token
Content-Type: application/json

{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret"
}

🧾 Step 2: Create a KYB Session

Before attaching documents, create a session that links your file submissions.

http 
POST /kyb/session 
{ 
"external_reference_id": "onboarding-case-123" 
}

🔗 Create Session →

📎 Step 3: Attach a Document

Upload a corporate document (PDF, PNG, or JPG) to your session for pre-validation and processing.

http 
POST /kyb/session/{session_id}/document 

{ 
"document_uri": "https://your-storage.com/document.pdf", "expected_document_type": "ArticlesOfIncorporation" 
}

🔗 Attach File →

🧪 Step 4: Pre-process & Validate

Run initial validation to check quality, type, dates, and more:

http 
POST /kyb/preprocess

Response includes:

• Match status

• Document quality score

• Data validation

• Verdict object (pass/fail)

🔗 Pre-process Docs →

📊 Step 5: Extract Structured Data

Trigger the extraction process once documents pass validation:

http
POST /kyb/extract

Response contains:

json
{ 
"extracted_data": { "business_name": { "value": "TechCorp S.A.", "page": 1, "line": 3 } } 
}

🔗 Start Extraction →

🧠 Tips for First-Time Integrators

• Use a sandbox environment for testing (contact us to enable)

• Validate documents before extraction to avoid document pre-processing and extraction failures

• Start with common doc types: Articles of Incorporation, Power of Attorney, RFC

• Always capture session_id and external_reference_id for traceability

🌀 Step 6: Retrieve Results (Async Option)

If using async mode, retrieve results later via:

http GET /kyb/session/{session_id}/result

Alternatively, you can configure a webhook callback for automatic delivery. For detailed implementation guidance, refer to our Callback Flow Documentation and choose the method that best fits your architecture.

🔗 Async/Sync Flow →

Need help? Reach us at support@zenpli.com

Ready to try it out? → Postman Collection Setup →