🧪 Using the Lucy KYB API Suite with Postman

Want to explore the Lucy KYB API Suite without writing a single line of code? This guide shows you how to test all key endpoints using Postman, the most popular tool for working with APIs.

🧰 Step 1: Import the API Collection

You can import the Lucy KYB API collection in two ways:

Option A: Import via Link

Coming soon — we'll publish an official public workspace.

Option B: Import Manually

1. Open Postman

2. Go to Collections > Import

3. Paste the OpenAPI spec URL or file: https://developers.zenpli.com/docs/kyb/openapi.json

⚙️ Step 2: Set Up Your Environment

Postman lets you use environments to manage variables like tokens and session IDs.

Example Variables:

Create the environment:

1. Click the gear icon (⚙️) > Manage Environments

2. Create a new environment named Lucy KYB

3. Add the variables above

🔐 Step 3: Authenticate

Use the Auth Token request to generate a valid bearer token.

POST {{base_url}}/auth/token

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

✅ Copy the returned token to your access_token variable.

📤 Step 4: Create a Session

http
POST 
{{base_url}}/kyb/session Headers: Authorization: Bearer {{access_token}} Body: { "external_reference_id": "test-case-001" }

🔁 Save the returned session_id into your environment.

📎 Step 5: Attach a Document

http 
POST 
{
{base_url}}/kyb/session/{{session_id}}/document Body: { "document_uri": "https://your-bucket.com/docs/invoice.pdf", "expected_document_type": "ArticlesOfIncorporation" 
}

🧪 Step 6: Validate the Document

http 
POST 
{
{base_url}}/kyb/preprocess Body: { "documents": [ { "expected_document_type": "ArticlesOfIncorporation", "document_uri": "https://your-bucket.com/docs/invoice.pdf" } ] 
}

Check for:

• verdict.boolean = true

• Field-level match statuses

📊 Step 7: Extract Data

http 
POST 
{
{base_url}}/kyb/extract Body: { "documents": [ { "document_type": "ArticlesOfIncorporation", "document_uri": "https://your-bucket.com/docs/invoice.pdf" } ] 
}

Inspect extracted_data in the response.

🌀 Step 8: (Async Mode) Get Results

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

Use this only if you opted into async flows. Otherwise, the extraction response will be immediate.

✅ Testing Tips

• Use the “Pre-request Script” in Postman to dynamically inject access_token

• Chain requests by using Tests > Set Environment Variable for session values

• Test with multiple document types (PDF, PNG, JPG)

Need the official collection?

📩 Contact luis@zenpli.com to request access.