Skip to main content

Buckets Leads Status API

The Buckets Leads Status API allows authorized systems to retrieve lead statuses by emaildata for a given bucket and affiliate, using emails and/or client IDs, with optional validationfiltering byand sourceId.flexible response structure.

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

Swagger documentation

(CRM origin)/api/public/docs/#/Buckets/post_buckets__bucketId___affiliateID__leads

Base Pathpath

/api/public

Authentication

Authentication

Method: Method

Token-based authentication usingvia theAuthorization Authorization header.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

ThisRequired ispermission:
Buckets: theView minimum required permission.Own

  • Tokens with broader permissions are accepted

  • Tokens without this permission are rejected

Unauthorized Response

If authentication fails:

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

Common Constraintsconstraints

    • Method:

    POST

    • Format:

    JSON

    idscombined)

    • type:

    Constraint Value

  • Max lookup size: 100 (emails per+ request

    		•  100
    Request formatJSON
    HTTP methodPOST
    Auth typeAuthorization token

    Client type

    		 Server-to-server

    EndpointEndpoint: 1 — Get Lead StatusesLeads by Bucketbucket & Affiliateaffiliate

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

    Description

    Returns a mapping of email → lead statusdata for theclients providedidentified listby ofemails emails.and/or client IDs.

    Validation

    Includes includes:

    validation:

    • Bucket existence

    • Bucket ownership by affiliate

    • Request size limits

    Path Parameters

    parameters

    • bucketId

    —

    affiliateID

    —
    Name TypeRequiredDescription
    bucketIdstring✅Uniquebucket identifier

    of the
  • bucket
    • affiliateIDstring✅Affiliateaffiliate identifier

    associated with the
    bucket

    Request Headers

    headers

    • Content-Type:

    • Authorization:

    HeaderRequiredValue
    Content-Type✅application/json
    Authorization✅<API_TOKEN>

    Request Body

    body 
    {
  "emails": ["[email protected]"],
  "[email protected]"ids": ["69ce524d741e8f2238329fff"],
  "keyBy": "email",
  "filters": {
    "createdDate": ["1676172330450", "1776172330450"]
  }
}

    Fields

    • emails

    —arrayof

    • At

    leastoridscombined(emails+
    Field Type Required emails (optional)

  • ids — array of client IDs (optional)

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

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

    • Notes
    one of emails string[] ✅ Maxshould be provided

  • Maximum total: 100 items

    		•
    ids)

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

    • Successful Response

    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",
    "[email protected]"createdDate": "inactive"2021-01-01T00:00:00.000Z",
    "ftd": "2021-01-01T00:00:00.000Z"
  }
}

    Returns

    a JSON object mapping email addresses to their current status.

    Error Responses

    Errors

    400 Bad Request

    • ConditionMessage

    Too many emails

    		 Tooand many emailsids provided. The maximum allowed is 100.
    Bucket not found

    Bucket with corresponding affiliateID does notdoesn't exist
    Ownership mismatch

    Provided bucketId does not belong to the provided affiliateID

    401 Unauthorized

    Returned when:

    • TokenInvalid isor missing token

    • Token is invalid

    • Token lacksMissing required permissions

    Endpoint
    2

    Endpoint: — Get Lead StatusesLeads by Bucket,bucket, Affiliateaffiliate & Source

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

    Description

    Same as Endpointprevious 1, butendpoint, with an additional source validation step ensuring the provided sourceId belongs to the specified bucket.

    step.
    Used for source-level access control.control.

    Path Parameters

    parameters

    • bucketId

    —

    • —

    • —
    Name TypeRequiredDescription
    bucketIdstring✅Bucketbucket identifier

    affiliateID

    		 string ✅Affiliateaffiliate identifier

    sourceId

    		 string ✅Sourcesource identifier

    associated with the
    bucket

    Request Body

    body 
    {
    Same "emails":as ["[email protected]",previous "[email protected]"]endpoint.
    
}

    Successful Response

    response

    200Same OKstructure as previous endpoint.

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

    Errors

    400 Bad Request

    All errorsprevious from Endpoint 1,errors, plus:

    • ConditionMessage
    Invalid source

    Provided sourceId does not belong to bucket

    401

    Unauthorized

    Same as previous endpoint.

    Example Requests

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