Lobby Partner API Specification (v1)

The Lobby Partner API allows enterprise portals, marketing automation tools, and multi-location hospitality franchises to trigger hyper-local TikTok & Instagram creator discovery programmatically.

Base URL: https://lobby.insightarc.com/api/v1/public/partner

Quick Actions:

Architecture & Lifecycle

hourglass_empty Async Job Ingress

Campaigns run asynchronously with guaranteed webhook callbacks to handle rate limits and live search latencies smoothly.

psychology Semantic Decomposition

AI normalizer decomposes high-level briefs (e.g. "artisanal sourdough bakery in Austin") into 10 high-intent search vectors.

lock Frozen v1 Contract

Our API contracts remain strictly backwards-compatible regardless of internal scraper or browser connector upgrades.

Authentication

All requests require a secret Bearer token in the Authorization header. Partner tokens are provisioned by the Lobby team.

Authorization: Bearer <PARTNER_API_TOKEN>

POST /discovery

1. Initiate Campaign Discovery

Creates a new asynchronous creator discovery campaign and triggers AI topic decomposition and search execution.

Request Body (JSON)

{
  "partner_request_id": "REQ-2026-08-9921",
  "product_description": "Artisanal espresso bar and specialty single-origin coffee roastery",
  "target_location": {
    "city": "Austin",
    "state": "Texas",
    "country": "US"
  },
  "search_criteria": {
    "topics": ["austin coffee", "austin barista", "atx foodies"],
    "language": "en"
  },
  "raw_search_query": "Specialty coffee shops and baristas in Austin TX",
  "callback_url": "https://partner-system.com/webhooks/lobby-results"
}

Field	Type	Required	Description
partner_request_id	string	Yes	Unique idempotency key from partner system.
product_description	string	No	Brand, offering, or hotel description used by AI for topic expansion.
target_location	object	Yes	Geographical anchor (`city`, `state`, `country`).
search_criteria.topics	string[]	No	Optional seed topics/hashtags supplied by partner.
callback_url	string	Yes	Destination HTTPS endpoint to receive webhook payload upon completion.

Response (`202 Accepted`)

{
  "status": "accepted",
  "insightarc_job_id": "arc_job_42"
}

GET /jobs/{insightarc_job_id}

2. Check Job Status

Polls the execution lifecycle of an active discovery job.

Response (`200 OK`)

{
  "status": "SCRAPING",
  "insightarc_job_id": "arc_job_42",
  "campaign_id": 42
}

Lifecycle Status Enum Values:

• ANALYZING_CONTEXT: Gemini AI is analyzing the brief and decomposing search topics.
• VALIDATING_TOPICS: Hardware connector is validating real hashtag volume.
• SCRAPING: Live creator profiles and videos are actively being ingested.
• COMPLETED: Discovery finished and results pushed to webhook.

GET /campaigns/{campaign_id}/topics

3. Fetch Generated Topics for Campaign

Retrieves the decomposed, validated search topics generated for a specific campaign.

[
  {
    "id": 101,
    "topic": "austin coffee",
    "position": 1,
    "approval_status": "approved",
    "source": "ai",
    "is_valid": true,
    "validation_status": "valid"
  },
  {
    "id": 102,
    "topic": "austin barista life",
    "position": 2,
    "approval_status": "approved",
    "source": "ai",
    "is_valid": false,
    "validation_status": "invalid"
  }
]

WEBHOOK POST {callback_url}

4. Webhook Delivery Schema

When discovery completes, Lobby sends a JSON payload to your callback_url containing verified creator profiles, emails, metrics, and qualification details.

{
  "event": "discovery.completed",
  "partner_request_id": "REQ-2026-08-9921",
  "insightarc_job_id": "arc_job_42",
  "creators": [
    {
      "handle": "@atxcoffeelover",
      "display_name": "Austin Coffee Guide",
      "profile_url": "https://www.tiktok.com/@atxcoffeelover",
      "followers_count": 18400,
      "likes_count": 320000,
      "bio": "Exploring the best espresso in ATX ☕ collab: contact@atxcoffee.com",
      "detected_email": "contact@atxcoffee.com",
      "extra_contacts": {
        "instagram": "atxcoffeelover",
        "linktree": "https://linktr.ee/atxcoffee"
      },
      "qualification": {
        "is_local": true,
        "is_corporate": false,
        "matched_topics": ["austin coffee", "austin barista life"]
      }
    }
  ],
  "total_creators_found": 18,
  "completed_at": "2026-08-25T14:30:00Z"
}

HTTP Status Codes & Error Handling

Status Code	Meaning	Resolution
202 Accepted	Job accepted for background execution.	Capture `insightarc_job_id` and await webhook.
401 Unauthorized	Missing or invalid Bearer token.	Verify `PARTNER_API_TOKEN` with operations team.
422 Unprocessable	Validation error in request schema.	Check required fields (`target_location.city`, `callback_url`).
429 Too Many Requests	Rate limit reached.	Implement exponential backoff.