External Lead Integration API

Programmatically integrate with the Whiteclad Noble platform for lead injection and campaign management.

Overview

This documentation is intended for vendors, partners, and developers to programmatically integrate with the Whiteclad Noble platform. It allows for lead injection, campaign discovery, and usage monitoring.

Base URL

All API requests should be made to:

https://api-serve.cllr.ai/api/v1/client

Note: Replace with your specific instance domain if using a dedicated deployment.

1. Authentication

The API uses a Dual-Header Authentication system. You must include specific headers provided by your administrator in every request to authorize your client.

Authentication Headers

Header	Value Format	Required	Description
`x-client-id`	`wc_client_...`	Yes	Your unique API Client ID.
`x-client-secret`	`wc_secret_...`	Yes	Your private API Client Secret.

Standard Headers

Header	Value	Required
`Content-Type`	`application/json`	Yes

Security Note

Keep your x-client-secret secure. Do not expose it in client-side code (browsers/mobile apps). If compromised, contact support immediately to rotate your keys.

2. Endpoints

2.1 Create Campaign Leads

Inject leads directly into a specific campaign. Leads are created with a pending status and are queued for the AI dialer immediately.

Endpoint: POST /leads
Rate Limit: Default 60 requests/minute.
Batch Size: Max 1000 leads per request.

Request Body Parameters:

Field	Type	Required	Description
`campaignId`	String	Yes	The 24-character hexadecimal Campaign ID (e.g., `65f2a1...`).
`leads`	Array	Yes	An array of lead objects.
`leads[].phone`	String	Yes	Phone number in E.164 format (e.g., `+14155551234`).
`leads[].firstName`	String	No	Subscriber's first name.
`leads[].lastName`	String	No	Subscriber's last name.
`leads[].email`	String	No	Subscriber's email address.
`leads[].priority`	String	No	`low`, `medium`, `high`, `urgent`. Default: `medium`.
`leads[].leadSource`	String	No	Source identifiers (e.g., `facebook-ads`, `web-form`).
`leads[].notes`	String	No	Context notes for the AI agent to be aware of.
`leads[].tags`	Array	No	Array of strings (Max 20 tags).
`leads[].timeZone`	String	No	IANA timezone string (e.g., `Asia/Kolkata`).
`leads[].customFields`	Object	No	Key-value pairs for custom data/context.

Example Request:

curl --location 'https://api-serve.cllr.ai/api/v1/client/leads' \
--header 'Content-Type: application/json' \
--header 'x-client-id: wc_client_xxxxxxxxxxxxxxxx' \
--header 'x-client-secret: wc_secret_xxxxxxxxxxxxxxxx' \
--data-raw '{
    "campaignId": "65f2a1b2c3d4e5f6a7b8c9d0",
    "leads": [
        {
            "phone": "+14155551234",
            "firstName": "John",
            "lastName": "Doe",
            "priority": "high",
            "customFields": {
                "interest": "Premium Plan",
                "budget": "$5000"
            }
        }
    ]
}'

Success Response (201 Created):

{
  "success": true,
  "data": {
    "successful": 1,
    "failed": 0,
    "duplicates": 0,
    "creditsDeducted": 0.01,
    "results": {
      "successful": [
        {
          "phone": "+14155551234",
          "leadId": "65f3...",
          "campaignLeadId": "65f3..."
        }
      ],
      "failed": [],
      "duplicates": []
    }
  }
}

2.2 List Active Campaigns

Retrieve a list of campaigns accessible to your client account. Useful for fetching campaignIds dynamically.

Endpoint: GET /campaigns

Query Parameters:

page (Number): Page number (Default: 1).
limit (Number): Items per page (Default: 20, Max: 100).
status (String): Filter by status (active, paused, completed).
search (String): Search by campaign name.

2.3 Get Campaign Details

Get specific details about a campaign, including current lead statistics.

Endpoint: GET /campaigns/:campaignId

2.4 Check API Status & Credits

Check your organization's current connection status, credit balance, and usage history.

Endpoint: GET /status

Response:

{
  "success": true,
  "data": {
    "clientId": "wc_client_...",
    "organization": { "id": "org_...", "name": "Acme Corp" },
    "usage": {
      "totalLeadsCreated": 1540,
      "lastUsedAt": "2024-03-20T10:00:00Z"
    },
    "credits": {
      "balance": 540.50
    }
  }
}

2.5 Check Rate Limits

Monitor your current consumption of the API rate-limit quota.

Endpoint: GET /rate-limits

3. Error Codes & Troubleshooting

HTTP Code	Error Type	Description & Solution
400	ValidationError	The request body is malformed or missing required fields.
401	AuthenticationError	Invalid or missing API credentials. Check headers.
402	PaymentRequiredError	Insufficient credit balance. Please recharge your account.
403	AuthorizationError	Forbidden access. Often caused by unauthorized IP or missing scopes.
404	NotFoundError	The requested `campaignId` does not exist.
429	RateLimitError	Too many requests. Please slow down (Standard: 60/min).
500	InternalServerError	An unexpected server error occurred.

External Lead Integration API

On this page