Buckets Leads Status API

The Buckets Leads Status API allows authorized systems to retrieve lead statuses by email for a given bucket and affiliate, with optional validation by sourceId.

These endpoints are read-only in intent and are implemented as POST requests to support bulk email validation.

---

Base Path

/api/public

---

Authentication

Authentication Method

Token-based authentication using the Authorization header.

Header Format

Authorization: <API_TOKEN>

• No Bearer prefix

• Token value must be passed as-is

---

API Token Source

API tokens are generated in CRM via:

/security/identification-tokens

---

Required Permissions

The role attached to the API token must include:

• Buckets: View Own

This is the minimum required permission.

• Tokens with broader permissions are accepted

• Tokens without this permission are rejected

---

Unauthorized Response

If authentication fails:

{
  "message": "Access with the provided credentials is incorrect. CODE: X-0005",
  "statusCode": 401
}

---

Common Constraints

Constraint	Value
Max emails per request	100
Request format	JSON
HTTP method	POST
Auth type	Authorization token
Client type	Server-to-server

---

Endpoint 1 — Get Lead Statuses by Bucket & Affiliate

Endpoint

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

---

Description

Returns a mapping of email → lead status for the provided list of emails.

Validation includes:

• Bucket existence

• Bucket ownership by affiliate

• Request size limits

---

Path Parameters

Name	Type	Required	Description
bucketId	string	✅	Unique identifier of the bucket
affiliateID	string	✅	Affiliate identifier associated with the bucket

---

Request Headers

Header	Required	Value
Content-Type	✅	application/json
Authorization	✅	<API_TOKEN>

---

Request Body

{
  "emails": ["[email protected]", "[email protected]"]
}

Fields

Field	Type	Required	Notes
emails	string[]	✅	Max 100 items

---

Successful Response

200 OK

{
  "[email protected]": "active",
  "[email protected]": "inactive"
}

Returns a JSON object mapping email addresses to their current status.

---

Error Responses

400 Bad Request

Condition	Message
Too many emails	Too many emails provided. The maximum allowed is 100.
Bucket not found	Bucket with corresponding affiliateID does not exist
Ownership mismatch	Provided bucketId does not belong to the provided affiliateID

---

401 Unauthorized

Returned when:

• Token is missing

• Token is invalid

• Token lacks required permissions

---

Endpoint 2 — Get Lead Statuses by Bucket, Affiliate & Source

Endpoint

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

---

Description

Same as Endpoint 1, but with an additional validation step ensuring the provided sourceId belongs to the specified bucket.

Used for source-level access control.

---

Path Parameters

Name	Type	Required	Description
bucketId	string	✅	Bucket identifier
affiliateID	string	✅	Affiliate identifier
sourceId	string	✅	Source identifier associated with the bucket

---

Request Body

{
  "emails": ["[email protected]", "[email protected]"]
}

---

Successful Response

200 OK

{
  "[email protected]": "active",
  "[email protected]": "inactive"
}

---

Error Responses

400 Bad Request

All errors from Endpoint 1, plus:

Condition	Message
Invalid source	Provided sourceId does not belong to bucket

---

Example Requests

Without sourceId

curl -X POST "/api/public/buckets/<bucketId>/<affiliateID>/leads" \
  -H "Content-Type: application/json" \
  -H "Authorization: <API_TOKEN>" \
  -d '{"emails":["[email protected]","[email protected]"]}'

---

With sourceId

curl -X POST "/api/public/buckets/<bucketId>/<affiliateID>/leads/<sourceId>" \
  -H "Content-Type: application/json" \
  -H "Authorization: <API_TOKEN>" \
  -d '{"emails":["[email protected]","[email protected]"]}'