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: <API_TOKEN>

• 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: <API_TOKEN>

📤 Request body

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

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

curl -X POST "(CRM origin)/api/public/buckets/<bucketId>/<affiliateID>/leads" \
  -H "Content-Type: application/json" \
  -H "Authorization: <API_TOKEN>" \
  -d '{
    "emails": ["user1@example.com"],
    "ids": ["69ce524d741e8f2238329fff"],
    "limit": 50,
    "offset": 0
  }'

With sourceId

curl -X POST "(CRM origin)/api/public/buckets/<bucketId>/<affiliateID>/leads/<sourceId>" \
  -H "Content-Type: application/json" \
  -H "Authorization: <API_TOKEN>" \
  -d '{
    "filters": {
      "createdDate": ["1676172330450", "1776172330450"]
    }
  }'