POSTliveIntelligence

Audience Intelligence

Generate customer-level buyer archetypes, campaign fit, timing notes, and message angles from birth data and campaign context.

POST /v1/audience/insightsQuickstart OpenAPI JSON

Credits

2 credits per customer

Minimum Plan

Basic+

Billing Lane

Light AI

SDK Helper

audienceInsights / audience_insights

Inputs

+customer birth data
+campaign context
+channel
+tone
+product category

Outputs

+buyer archetype
+campaign fit score
+send/no-send recommendation
+message angle
+chart quality

Tool Functions

Capabilities behind this endpoint

5 functions

customer.profile.score

Scores each customer against a campaign context.

campaign.fit.evaluate

Returns send/no-send guidance with reasoning.

message.angle.generate

Produces positioning language for the audience segment.

chart.quality.report

Reports whether the request used a full chart or limited birth data.

erlewine.context.attach

Adds authorized Michael Erlewine context when local RAG is enabled.

Campaign Fit request

{
  "customers": [
    {
      "id": "cust_123",
      "dob": "1990-07-23",
      "tob": "14:30",
      "pob": "New York, US"
    }
  ],
  "campaign_context": {
    "product_category": "relationship coaching membership",
    "tone": "warm direct",
    "channel": "email"
  }
}

Campaign Fit response

{
  "request_id": "req_...",
  "data": {
    "results": [
      {
        "customer_id": "cust_123",
        "personality": {
          "sun_sign": "Leo",
          "buyer_archetype": "premium loyalist"
        },
        "campaign_fit": {
          "score": 0.86,
          "send": true,
          "reasoning": "High receptivity window"
        }
      }
    ]
  },
  "usage": { "lane": "ai", "credits": 2, "billableUnits": 1 },
  "meta": { "chartQuality": [{ "customer_id": "cust_123", "quality": "full_chart" }] }
}

curl

curl https://theleokingai.com/api/v1/audience/insights \
  -X POST \
  -H "Accept: application/json" \
  -H "x-api-key: $LEOKING_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: audience-intelligence-subject-123-v1" \
  -d '{
  "customers": [
    {
      "id": "cust_123",
      "dob": "1990-07-23",
      "tob": "14:30",
      "pob": "New York, US"
    }
  ],
  "campaign_context": {
    "product_category": "relationship coaching membership",
    "tone": "warm direct",
    "channel": "email"
  }
}'

Node SDK

import { TheLeoKingApi } from "@theleoking/ai-api";

const api = new TheLeoKingApi({
  apiKey: process.env.LEOKING_API_KEY,
  baseUrl: "https://theleokingai.com/api"
});

const result = await api.audienceInsights(
  {
  "customers": [
    {
      "id": "cust_123",
      "dob": "1990-07-23",
      "tob": "14:30",
      "pob": "New York, US"
    }
  ],
  "campaign_context": {
    "product_category": "relationship coaching membership",
    "tone": "warm direct",
    "channel": "email"
  }
},
  "audience-intelligence-subject-123-v1"
);

console.log(result.request_id);
console.log(result.usage.credits);

Python SDK

import os
from theleoking_ai_api import TheLeoKingApi

api = TheLeoKingApi(
    api_key=os.environ["LEOKING_API_KEY"],
    base_url="https://theleokingai.com/api",
)

result = api.audience_insights(
    {
        "customers": [
            {
                "id": "cust_123",
                "dob": "1990-07-23",
                "tob": "14:30",
                "pob": "New York, US",
            },
        ],
        "campaign_context": {
            "product_category": "relationship coaching membership",
            "tone": "warm direct",
            "channel": "email",
        },
    },
    idempotency_key="audience-intelligence-subject-123-v1",
)

print(result["request_id"])
print(result["usage"]["credits"])

Error Behavior

HTTP	Code	Partner Action
400	`INVALID_REQUEST`	Fix the payload shape, enum value, required field, or request body before retrying.
401	`AUTH_REQUIRED`	Send x-api-key from a trusted server environment. Do not expose keys in browser code.
401	`AUTH_INVALID`	Check the key prefix, rotate compromised keys, and verify the target environment.
402	`CREDITS_EXHAUSTED`	Upgrade the plan, add credits, or switch to a lower-cost Core Compute route.
403	`AUTH_FORBIDDEN`	Use a key scoped for this endpoint or upgrade to the required plan.
404	`NOT_FOUND`	Verify the job id, environment, API key, and whether the job belongs to the same workspace.
409	`IDEMPOTENCY_CONFLICT`	Reuse idempotency keys only for the same logical operation and identical request payload.
429	`RATE_LIMITED`	Back off, retry later, reduce concurrency, or request enterprise limits.