# Buckets Leads Status API The Buckets Leads Status API allows authorized systems to retrieve lead data for a given **bucket** and **affiliate**, using **emails and/or client IDs**, with optional filtering, pagination, and flexible response structure. These endpoints are **read-only** and implemented as **POST** to support bulk lookups. --- #### 📍 Base path ``` /api/public ``` --- #### 🔐 Authentication **Method:** Token-based via `Authorization` header ``` Authorization: ``` - No Bearer prefix - Token must be passed as-is **Required permission:** 👉 Buckets: View Own If authentication fails: ``` 401 Unauthorized { "message": "Access with the provided credentials is incorrect. CODE: X-0005", "statusCode": 401 } ``` --- #### ⚙️ Common behavior - Method: POST - Format: JSON - Client type: Server-to-server - Supports pagination via `limit` and `offset` --- ### 📦 Endpoint: Leads by bucket & affiliate ``` POST /buckets/{bucketId}/{affiliateID}/leads ``` --- #### 🧠 Description Returns lead data for clients identified by: - emails - client IDs - or both Includes validation: - Bucket existence - Bucket ownership by affiliate --- #### 📌 Path parameters - `bucketId` — bucket identifier - `affiliateID` — affiliate identifier --- #### 📥 Request headers - Content-Type: application/json - Authorization: `` --- #### 📤 Request body ```json { "emails": ["user1@example.com"], "ids": ["69ce524d741e8f2238329fff"], "keyBy": "email", "filters": { "createdDate": ["1676172330450", "1776172330450"] }, "limit": 100, "offset": 0 } ``` --- #### 🧩 Fields - `emails` — array of emails (optional) - `ids` — array of client IDs (optional) - `keyBy` — `"email"` (default) or `"id"` - `filters.createdDate` — optional created date range (epoch ms strings) - `limit` — number of records to return (default: 100) - `offset` — number of records to skip (default: 0) --- #### ⚠️ Notes - If both `emails` and `ids` are empty → returns data based on filters only - `keyBy = "id"`: - uses client `_id` as key - falls back to email if `_id` is missing - Pagination is applied **after filtering** --- #### ✅ Successful response ``` 200 OK ``` Response is an object keyed by `email` or `id` (based on `keyBy`). ```json { "user1@example.com": { "id": "69ce524d741e8f2238329fff", "email": "user1@example.com", "affiliateID": "1234567890", "status": "active", "createdDate": "2021-01-01T00:00:00.000Z", "ftd": "2021-01-01T00:00:00.000Z" } } ``` --- #### ❌ Errors **400 Bad Request** - Bucket with corresponding affiliateID doesn't exist - Provided bucketId does not belong to the provided affiliateID **401 Unauthorized** - Invalid or missing token - Missing required permissions --- ### 🧩 Endpoint: Leads by bucket, affiliate & source ``` POST /buckets/{bucketId}/{affiliateID}/leads/{sourceId} ``` --- #### 🧠 Description Same as previous endpoint, with an additional **source validation step**. Used for **source-level access control**. --- #### 📌 Path parameters - `bucketId` — bucket identifier - `affiliateID` — affiliate identifier - `sourceId` — source identifier --- #### 📤 Request body Same as previous endpoint. --- #### ⚠️ Source validation behavior - If `sourceId` is provided → system checks that **bucket has a source assigned** - If validation fails → request is rejected --- #### ✅ Successful response Same structure as previous endpoint. --- #### ❌ Errors **400 Bad Request** All previous errors, plus: - Provided sourceId does not belong to bucket **401 Unauthorized** Same as previous endpoint. --- #### 🔧 Example requests **Without sourceId** ```bash curl -X POST "(CRM origin)/api/public/buckets///leads" \ -H "Content-Type: application/json" \ -H "Authorization: " \ -d '{ "emails": ["user1@example.com"], "ids": ["69ce524d741e8f2238329fff"], "limit": 50, "offset": 0 }' ``` --- **With sourceId** ```bash curl -X POST "(CRM origin)/api/public/buckets///leads/" \ -H "Content-Type: application/json" \ -H "Authorization: " \ -d '{ "filters": { "createdDate": ["1676172330450", "1776172330450"] } }' ```