API docs by Redocly

COA Partner API Overview (1.0.0)

Download OpenAPI specification:

ClearOne Advantage (Lead Experience Pod): [email protected]

Overview

This API provides endpoints for lead management, bidding calculations, and partner integrations.

Authentication

All the endpoints require Bearer token authentication. Include the token in the Authorization header: Authorization: Bearer <your-token>

Error Handling

All endpoints return consistent error responses with appropriate HTTP status codes.

API Keys

Create and manage API keys

Create API key

Creates a new API key. The key is returned only once and cannot be retrieved later.

  • Irretrievable: If the key is lost, it cannot be recovered. Make sure to store it securely.
  • Authentication: Not required for creation.

After the key is created, send an email to MarketingDB@clearoneadvantage.com with the userId so we can provision access.

Important: Do NOT include the API key in the email. Only provide the userId and relevant metadata.

Sample email: Subject: COA Partner API – New API Key (userId: partner-123) Body:

  • Environment: dev | stg | prd
  • User ID: partner-123
  • Label: Partner key
  • Notes: Optional context (team, use-case)
Request Body schema: application/json
required
label
string <= 100 characters
userId
required
string non-empty
object

Responses

Request samples

Content type
application/json
{
  • "label": "Partner key",
  • "userId": "partner-123",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "apiKey": "pka_..._a1b2c3",
  • "owner": {
    },
  • "createdAt": "2025-01-01T00:00:00.000Z"
}

COA Partner Lead Submission API

External partners POST lead data to COA to receive real-time bid decisions. The endpoint validates payloads and returns a unique lead ID, bid amount, and redirect URL.

Ping COA

Authentication Required: Yes

Authorizations:
BearerAuth
Request Body schema: application/json
required
partnerId
string <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA...

Partner ID

partnerName
string

Partner name (e.g., NerdWallet, Credible)

partnerLeadId
string

ID associated with partner system

partnerQualityId
string

Partner quality identifier

partnerMetadata
object

Freeform object for any extra data

firstName
required
string non-empty

Lead first name

lastName
required
string non-empty

Lead last name

email
required
string <email> ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z...

Lead email address

phone
required
string^\+1[2-9]\d{2}[2-9]\d{2}\d{4}$

Lead phone number in E.164 format (US numbers only)

isPhoneVerified
boolean
Default: false

Whether phone number is verified

isEmailVerified
boolean
Default: false

Whether email is verified

street
required
string non-empty

Street address

street2
string non-empty

Street address line 2

city
required
string non-empty

City

state
required
string >= 2 characters

US state abbreviation

zipCode
required
string >= 5 characters

ZIP code

dateOfBirth
required
string >= 8 characters

Date of birth (YYYY-MM-DD format)

ssn
required
string [ 4 .. 9 ] characters

Social Security Number (PII - encrypted at rest)

employmentStatus
string
Enum: "EMPLOYED" "UNEMPLOYED" "RETIRED" "DISABLED" "SELF_EMPLOYED" "STUDENT"

Employment status (eg. EMPLOYED, UNEMPLOYED etc

housingStatus
string
Enum: "RENT" "OWN" "MORTGAGE" "LIVING_WITH_FAMILY"

Housing status (eg. RENT, OWN, MORTGAGE, LIVING_WITH_FAMILY)

annualIncome
number

Annual income in dollars

militaryOrVeteran
boolean

Military or veteran status

debtReliefOptIn
boolean

Debt relief opt-in status

debtAmount
required
number

Total debt amount in dollars

personalLoanPurpose
string

Purpose of personal loan

personalLoanRequestAmount
number

Requested loan amount in dollars

selfCreditRating
string
Enum: "EXCELLENT" "GOOD" "FAIR" "POOR" "UNKNOWN"

Self-reported credit rating (eg. EXCELLENT, GOOD, FAIR, POOR, UNKNOWN)

subid1
string

Sub ID 1 for tracking

subid2
string

Sub ID 2 for tracking

spinwheelToken
string

Spinwheel verification token

trustedFormToken
string

TrustedForm verification token

trustedFormUrl
string <uri>

TrustedForm verification URL

jornayaToken
string

Jornaya verification token

entryPointIntent
string

Entry point intent (e.g., DEBT_RELIEF)

Responses

Request samples

Content type
application/json
Example

Example lead submission from NerdWallet partner

{
  • "partnerId": "550e8400-e29b-41d4-a716-446655440000",
  • "partnerName": "nerdwallet",
  • "partnerLeadId": "nw_lead_12345",
  • "partnerQualityId": "nw_1234",
  • "partnerMetadata": {},
  • "firstName": "John",
  • "lastName": "Doe",
  • "email": "[email protected]",
  • "phone": "+15551234567",
  • "isPhoneVerified": true,
  • "isEmailVerified": false,
  • "street": "123 Main St",
  • "street2": "Apt 4B",
  • "city": "San Francisco",
  • "state": "CA",
  • "zipCode": "94105",
  • "dateOfBirth": "1985-06-15",
  • "ssn": "123456789",
  • "employmentStatus": "EMPLOYED",
  • "housingStatus": "OWN",
  • "annualIncome": 75000,
  • "militaryOrVeteran": false,
  • "debtReliefOptIn": true,
  • "debtAmount": 25000,
  • "personalLoanPurpose": "Debt consolidation",
  • "personalLoanRequestAmount": 30000,
  • "selfCreditRating": "GOOD",
  • "subid1": "nw_organic",
  • "subid2": "debt_relief",
  • "spinwheelToken": "spin_abc123",
  • "trustedFormToken": "tf_token_xyz789",
  • "trustedFormUrl": "https://trustedform.com/cert/xyz789",
  • "jornayaToken": "jor_token_def456",
  • "entryPointIntent": "DEBT_RELIEF"
}

Response samples

Content type
application/json
Example

Response for a new lead submission

{}