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, with optional filtering 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 constraints

  • Method: POST

  • Format: JSON

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

  • Client type: Server-to-server

Endpoint: Leads by bucket & affiliate

POST /buckets/{bucketId}/{affiliateID}/leads

Description

Returns lead data for clients identified by emails and/or client 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"]
  }
}

Fields

  • emails — array of emails (optional)

  • ids — array of client IDs (optional)

  • keyBy — "email" (default) or "id"

  • filters.createdDate — optional date range (epoch ms strings)

Notes

  • At least one of emails or ids should be provided

  • Maximum total: 100 combined (emails + ids)

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

Successful response

200 OK

Response is an object keyed by email or id (based on 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.
Used for source-level access control.

Path parameters

  • bucketId — bucket identifier

  • affiliateID — affiliate identifier

  • sourceId — source identifier

Request body

Same as previous endpoint.

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"]
  }'

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": ["[email protected]"]
  }'
Back to top