Skip to main content

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,IDs, with optional filteringfiltering, 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 authentication 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 constraintsbehavior

  • Method: POST

  • Format: JSON

  • Max lookup size: 100 (emails + ids combined)

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

  • emails

    and/

  • client IDs

  • or clientboth

    IDs.

Includes validation:

  • Bucket existence

  • Bucket ownership by affiliate

  • Request size limits

📌 Path parameters

  • bucketId — bucket identifier

  • affiliateID — affiliate identifier

📥 Request headers

  • Content-Type: application/json

  • Authorization: <API_TOKEN>

📤 Request body

{
  "emails": ["[email protected]"],
  "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)

Notes

  • Atlimit least— onenumber of emailsrecords orto idsreturn should(default: be provided100)

  • Maximumoffset total:— 100number combinedof records to skip (emailsdefault: + ids)

  • If keyBy = "id" and ID is missing → email is used as fallback0)

⚠️ 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)keyBy).

{
  "[email protected]": {
    "id": "69ce524d741e8f2238329fff",
    "email": "[email protected]",
    "affiliateID": "1234567890",
    "status": "active",
    "createdDate": "2021-01-01T00:00:00.000Z",
    "ftd": "2021-01-01T00:00:00.000Z"
  }
}

❌ Errors

400 Bad Request

  • Too many emails and ids provided. The maximum allowed is 100.

  • 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.
step.

Used for source-level access control.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": ["[email protected]"],
    "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 '{
    "emails"filters": {
      "createdDate": ["[email protected]"1676172330450", "1776172330450"]
    }
  }'
Back to top