Vendor Documentation

Quick Start

Get started with your vendor integration in minutes

Your Vendor Key

6ab36a94-5dfb-4336-a559-63da6a5a26d2

API Base URL

https://ydceruncqdpznxvqzlxb.supabase.co/functions/v1

Your vendor key is already configured in the code examples below. Simply copy and paste to get started!

API Endpoint

Single endpoint for availability checks, vendor validation, and call routing

POST https://ydceruncqdpznxvqzlxb.supabase.co/functions/v1/vendors-ping

Response Codes

200 Success
400 Bad Request
401 Invalid Vendor Key
500 Server Error

Request Parameters

REQUIRED vendorKey

Your unique vendor API key for authentication

string

OPTIONAL phoneNumber

Customer's phone number to check agent availability. We automatically parse the area code to determine the customer's state and check for available agents in that region.

string

Example: "+14801234567", "4801234567", "14801234567"

OPTIONAL stateCode

Two-letter US state code to directly specify the customer's state. When provided, this takes priority over the state derived from the phone number's area code. Useful when you already know the customer's state or when using non-geographic phone numbers.

string

Example: "AZ", "CA", "TX"

OPTIONAL Additional Metadata Fields

Any additional fields you include in the request body will be automatically captured and stored with the call record. This allows you to pass through tracking data like lead IDs, campaign codes, or any custom identifiers your system uses.

Common fields:

lead_id — Your unique identifier for this lead/prospect
ad_id — The ad or creative ID that generated this lead
ad_url — The landing page or ad URL the lead came from
campaign_id — Your marketing campaign or offer ID
source — Where the lead originated (e.g., google, facebook)
sub_id — Your sub-affiliate or click tracking identifier

You can include any custom fields—they will all be captured and available in call records.

System Status

APIOperational

99.9% uptime • ~45ms response time

Telephony SystemsOperational

97.8% uptime • Call routing active

Queue ProcessingOperational

99.1% uptime • Avg 2.3s processing time

Data CentersOperational

Multi-region • US East, West, Central

DatabaseOperational

100% uptime • < 10ms query time

Overall System All Systems Operational

Support

Business hours: Mon-Fri 9AM-6PM EST

Code Examples

Check agent availability and route calls to your assigned agents

How it works: Our system automatically extracts the area code from the customer's phone number and determines their state to check for available agents in that region. When an agent is available, you'll receive a transferTarget phone number. Perform a blind transfer of the customer's call to this number within ttlSeconds (60 seconds). Our system will route the call and connect the customer to an available agent.

vendorKey and phoneNumber are the minimum required fields. stateCode is recommended when you know the customer's state (overrides area code lookup). You can also pass your own tracking data (lead_id, ad_id, ad_url, source etc.) — these are optional but will be stored with the call record so both parties can reference them.

curl -X POST "https://ydceruncqdpznxvqzlxb.supabase.co/functions/v1/vendors-ping" \
  -H "Content-Type: application/json" \
  -d '{
    "vendorKey": "6ab36a94-5dfb-4336-a559-63da6a5a26d2",
    "phoneNumber": "+14801234567",
    "stateCode": "AZ",
    "lead_id": "L-12345",
    "ad_id": "SUMMER-2025",
    "ad_url": "https://example.com/offer",
    "source": "google"
  }'

const response = await fetch('https://ydceruncqdpznxvqzlxb.supabase.co/functions/v1/vendors-ping', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    // Required
    vendorKey: '6ab36a94-5dfb-4336-a559-63da6a5a26d2',
    phoneNumber: '+14801234567',

    // Recommended - overrides state derived from area code
    stateCode: 'AZ',

    // Optional metadata - captured with the call record
    lead_id: 'L-12345',
    ad_id: 'SUMMER-2025',
    ad_url: 'https://example.com/offer',
    source: 'google'
  })
});

const data = await response.json();

import requests

url = "https://ydceruncqdpznxvqzlxb.supabase.co/functions/v1/vendors-ping"
payload = {
    # Required
    "vendorKey": "6ab36a94-5dfb-4336-a559-63da6a5a26d2",
    "phoneNumber": "+14801234567",

    # Recommended - overrides state derived from area code
    "stateCode": "AZ",

    # Optional metadata - captured with the call record
    "lead_id": "L-12345",
    "ad_id": "SUMMER-2025",
    "ad_url": "https://example.com/offer",
    "source": "google"
}

response = requests.post(url, json=payload)
data = response.json()

Preferred Metadata Field Names

We automatically normalize common field name variations. For best results, use our preferred names below. Recognized aliases are listed for reference.

lead_idYour unique identifier for this lead/prospect

— also accepts: prospect_id, lead_ref, lid, leadid, lead_identifier

ad_idThe ad or creative ID that generated this lead

— also accepts: advert_id, advertisement_id, ad_identifier, adid

ad_urlThe landing page or ad URL the lead came from

— also accepts: landing_page, lp_url, page_url, adurl

campaign_idYour marketing campaign or offer ID

— also accepts: campaign, camp_id, campaign_code, utm_campaign

sourceWhere the lead originated (e.g., google, facebook, email)

— also accepts: utm_source, traffic_source, lead_source, src

sub_idYour sub-affiliate or click tracking identifier

— also accepts: subid, sub_affiliate, affiliate_sub, click_id

Any additional fields not listed above will still be captured as custom metadata.

Validate your vendor key and check your authorized states

curl -X POST "https://ydceruncqdpznxvqzlxb.supabase.co/functions/v1/vendors-ping" \
  -H "Content-Type: application/json" \
  -d '{
    "vendorKey": "6ab36a94-5dfb-4336-a559-63da6a5a26d2"
  }'

const response = await fetch('https://ydceruncqdpznxvqzlxb.supabase.co/functions/v1/vendors-ping', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    vendorKey: '6ab36a94-5dfb-4336-a559-63da6a5a26d2'
  })
});

const data = await response.json();

import requests

url = "https://ydceruncqdpznxvqzlxb.supabase.co/functions/v1/vendors-ping"
payload = {
    "vendorKey": "6ab36a94-5dfb-4336-a559-63da6a5a26d2"
}

response = requests.post(url, json=payload)
data = response.json()

Integration Flow

Step-by-step guide to routing calls through our system

Availability Check (Pre-call)

Before transferring a customer call, ping our API with the customer's phone number. We automatically parse the area code to determine their state and check agent availability for that region.

Receive Transfer Target

If agentAvailable: true, you'll receive a transferTarget phone number and a ttlSeconds value.

Blind Transfer

Perform a blind/cold transfer of the customer's live call to the transferTarget number within the TTL window. No need to create tasks or track agents—our system handles everything.

✓

Automatic Routing

Our system receives the transferred call, creates the task, assigns an available agent, and connects them to the customer—all automatically. You're done!

Response Examples

Different response scenarios you may encounter

Agent Available

{
  "status": 200,
  "data": {
    "agentAvailable": true,
    "transferTarget": "+18775703926",
    "ttlSeconds": 60,
    "agentCount": 3,
    "timestamp": "2025-09-19T17:45:23.123Z",
    "requestId": "12345678-1234-1234-1234-123456789abc"
  }
}

agentAvailable — Boolean indicating if an agent is available
transferTarget — The phone number to blind transfer the customer to
ttlSeconds — Time-to-live in seconds (how long this availability is valid)
agentCount — Number of available agents ready to field a call for this state
timestamp — UTC timestamp of the response
requestId — Unique identifier for tracking and support

No Agent Available

{
  "status": 200,
  "data": {
    "agentAvailable": false,
    "timestamp": "2025-09-19T17:45:23.123Z",
    "requestId": "12345678-1234-1234-1234-123456789abc"
  }
}

When no agents are available, hold the call or try again after a short delay.

Vendor Active (Specific States)

{
  "status": 200,
  "data": {
    "vendorActive": true,
    "authorizedStates": ["AZ", "CA"],
    "requestId": "12345678-1234-1234-1234-123456789abc"
  }
}

Vendor Active (All States)

{
  "status": 200,
  "data": {
    "vendorActive": true,
    "authorizedStates": ["All"],
    "requestId": "12345678-1234-1234-1234-123456789abc"
  }
}

Vendor Not Found

{
  "status": 401,
  "data": {
    "message": "Vendor key was not found or not formatted correctly.",
    "requestId": "12345678-1234-1234-1234-123456789abc"
  }
}

Invalid Phone Number

{
  "status": 400,
  "data": {
    "message": "Invalid phone number format. Please provide a valid US phone number.",
    "requestId": "12345678-1234-1234-1234-123456789abc"
  }
}

Server Error

{
  "status": 500,
  "data": {
    "message": "An unexpected condition was encountered by the server.",
    "requestId": "12345678-1234-1234-1234-123456789abc"
  }
}

Clear-Opt Connect Vendor Documentation

Agent Available

No Agent Available

Vendor Active (Specific States)

Vendor Active (All States)

Vendor Not Found

Invalid Phone Number

Server Error