Skip to content

Send leads

MediaAlpha native post

Post your native insurance JSON unchanged. We map it to an Entrovox lead, so you do not remap fields.

On this page

Post your native insurance JSON. We map it. An AI voice agent calls the lead and warm-transfers a qualified buyer to the customer's licensed agents.

One API key is one customer campaign: one agency and one line of business. A second agency gets a second key. A second vertical for the same agency, such as auto and home, gets a second key and its own URL. For the generic partner contract, start at the quickstart.

OpenAPI specification

Download the complete OpenAPI 3.1 specification for the MediaAlpha lead intake adapter, and import it into Postman, Insomnia or your API gateway to explore and test the endpoint.

Endpoint

FormRequest
Header (preferred)POST https://api.entrovox.com/v1/leads/mediaalpha
URL onlyPOST https://api.entrovox.com/v1/leads/mediaalpha/<campaign key>

Send Content-Type: application/json. The body is your flat lead object.

Auth

  • Preferred: Authorization: ApiKey sk_entrovox_….
  • URL form: the same key is the last path segment. Use it when your delivery config can set a URL and cannot set a header.
  • Never put the key in the query string (api_key, key, token and similar). That returns 400.
  • If you send both a header and a path key, they must be the same key. A mismatch is 401 TOKEN_INVALID.
  • The key is bound to one Entrovox organization and one api campaign. A different lead_source_id in the body is 403 LEAD_SOURCE_NOT_ALLOWED, so omit lead_source_id.
  • A read-only key cannot post: 403 INSUFFICIENT_SCOPE.

Field mapping

Your fieldOur fieldRequired
contact_first_namefirst_nameYes
contact_last_namelast_nameYes
phonephone, as E.164 +1 plus 10 digitsYes
unique_identifier, else tokenexternal_idYes: one of the two, as a non-empty string. null counts as absent
emailemailNo
zipzip_code. Residence state and timezone come from the ZIP onlyYes
TrustedForm names belowtrustedform_cert_urlNo
Jornaya names belowjornaya_leadidNo
Lead-time names belowlead_generated_atNo
Every other fieldmetadata, same name, same JSON typeNo

unique_identifier wins when both it and token are present, even if they differ. token is still stored in metadata. A post with "unique_identifier": null and no token is 422 and is not enrolled. We do not fall back to a Jornaya or TrustedForm id, because unique_identifier is the id you use to look the lead up and reconcile returns.

Phone

Send 10 digits, like 3602179499. A leading 1, +1, spaces, dashes and parentheses are accepted. The area code and exchange cannot start with 0 or 1. We store +13602179499.

ZIP, state, timezone

We do not read driver_1_license_state or a posted state as the residence. Those values stay in metadata. State comes from zip. When that ZIP is one timezone, we store it: 90210 becomes CA and America/Los_Angeles, 79901 (El Paso) becomes TX and America/Denver, and 32501 (Pensacola) becomes FL and America/Chicago.

A ZIP we can place in a state but not in one zone is still enrolled. We store the state and do not pick a zone, so calling hours have to be legal in every zone that state uses. A missing ZIP, or a ZIP we cannot place in a US state, is 400 and is not enrolled. We do not guess the state from the phone area code, and we do not use the agency timezone for that lead.

Send zip as text so leading zeroes survive, like "02134". A JSON number is accepted and padded to 5 digits: 2134 becomes 02134.

Lines of business

One key is one campaign. The campaign's configured line of business (auto, home, medicare, life, health) decides which script the AI voice agent runs and what we store as the lead's owned_line_of_business and target_line_of_business. We do not use the payload to pick the campaign, but we do refuse a post whose fields contradict it. vehicle_*, driver_* or incident_* fields on a home key, or properties_* fields on an auto key, are 400 VALIDATION_ERROR with param lead_source_id and no lead. A post with both kinds of fields, or neither, is accepted. Campaigns on other lines are not checked.

Send each vertical to its own key and URL: auto to the auto campaign's key, home to the home campaign's key. A cross-sell campaign rejects the post with CROSS_SELL_PAIR_INVALID.

One phone, one live lead per agency. A phone whose existing lead is still in a live sequence (pending or connected) in one of the agency's active campaigns is 409 LEAD_PHONE_CONFLICT, whether or not that lead is paused. The second post is not enrolled, unless the agency has allowed duplicate phones. A lead whose sequence already finished does not block: the second post is 201 and a new lead. A consumer who requests both an auto and a home quote while the first lead is live is therefore enrolled once, under whichever post arrived first. Treat that 409 as a duplicate for returns reconciliation, not as a quality reject.

A lead without consent fields is still accepted. The agency certifies consent on the campaign before it is activated.

TrustedForm. The first non-empty value wins. A second non-empty value must be the same certificate or we return 400. A 40-character hex id is expanded to https://cert.trustedform.com/<id>. We read these names:

trustedform_cert_url, trusted_form_cert_url, trustedform_url, trusted_form_url, trustedform, trusted_form, xxTrustedFormCertUrl, xxTrustedFormToken, trustedform_token, tf_cert_url, and trusted_form_certificate_id (the home sample's name, a 40-character hex id).

Jornaya LeadID. The same first-non-empty rule. Stored, not format-checked, at most 256 characters. A second non-empty Jornaya name must carry the same id or we return 400, with param set to the later name. We read these names:

jornaya_leadid, jornaya_lead_id, leadid_token, universal_leadid, jornaya_token, leadid, and leadid_id (the home sample's name).

The field we consumed is removed from metadata. Any other consent-looking name stays in metadata and is not treated as consent.

TCPA flags. tcpa_call_consent is read. "0", 0 (any numeric zero, including 0.0), false or "false" means the consumer did not consent to calls, and the post is 400 CONSENT_INVALID with param tcpa_call_consent and no lead. Resell it. Any other value, or no field, is accepted and stored. tcpa_sms_consent, tcpa_email_consent, tcpa_text and tcpa_url are stored in metadata as sent and are not read.

Lead time (optional)

We use the first non-empty of lead_generated_at, lead_timestamp, date_created, submitted_at and submission_time, as ISO-8601. If it is missing or not a date we accept, we use the time we received the post. Consent timestamps are not lead time.

Other fields

Vehicle, driver, property and coverage fields stay in metadata. That includes empty strings, numbers that arrive as strings, real numbers (vehicle_1_year, properties_1_year_built) and a tab-separated string (vehicle_1_year_make_model_base).

The property address in a home post (properties_1_address, properties_1_city, properties_1_state, properties_1_zip) is stored and is not the residence. state, timezone and calling hours come from zip, because we call the person, not the property.

Limits: 64 KB, nesting depth 32, no NUL (U+0000). _entrovox_source_status_at_arrival is reserved and returns 400.

Auto example

Post to the auto campaign's key. The sample below is trimmed to the fields that matter. Send every field you have: whatever we do not map lands in metadata.

curl -X POST https://api.entrovox.com/v1/leads/mediaalpha \
  -H "Authorization: ApiKey $ENTROVOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "unique_identifier": "AD7RL34G4CQNGKFP27AX6ANP27AX6ABEHI",
    "contact_first_name": "Pamela",
    "contact_last_name": "Silverman",
    "phone": "3602179499",
    "email": "[email protected]",
    "zip": "90210",
    "address": "120 Jenkins Rd",
    "city": "Beverly Hills",
    "vehicle_1_year": 2024,
    "vehicle_1_make": "HONDA",
    "vehicle_1_model": "CIVIC SI",
    "vehicle_1_vin": "19XFE1E50RE000000",
    "driver_1_birth_date": "1976-07-17",
    "driver_1_license_state": "GA",
    "currently_insured": "1",
    "current_company": "Progressive"
  }'
201Created
{
  "data": {
    "id": "7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40",
    "external_id": "AD7RL34G4CQNGKFP27AX6ANP27AX6ABEHI",
    "first_name": "Pamela",
    "last_name": "Silverman",
    "phone": "+13602179499",
    "email": "[email protected]",
    "state": "CA",
    "zip_code": "90210",
    "timezone": "America/Los_Angeles",
    "current_disposition": "pending",
    "status_url": "https://api.entrovox.com/v1/leads/7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40",
    "metadata": {
      "address": "120 Jenkins Rd",
      "city": "Beverly Hills",
      "driver_1_birth_date": "1976-07-17",
      "driver_1_license_state": "GA",
      "vehicle_1_make": "HONDA",
      "vehicle_1_year": 2024,
      "currently_insured": "1",
      "current_company": "Progressive"
    }
  }
}

Every other field you post is in metadata too. contact_first_name, contact_last_name, phone, email, zip and unique_identifier are not repeated there. driver_1_license_state stays GA in metadata, while the residence state on the lead is CA. Fields not shown on the lead follow the lead object in the API reference.

Home example

Post to the home campaign's key. The consent fields use the names MediaAlpha's home sample ships: trusted_form_certificate_id and leadid_id.

curl -X POST https://api.entrovox.com/v1/leads/mediaalpha \
  -H "Authorization: ApiKey $ENTROVOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "unique_identifier": "HOME-SAMPLE-0001",
    "contact_first_name": "Pamela",
    "contact_last_name": "Silverman",
    "phone": "(360) 217-9499",
    "email": "[email protected]",
    "zip": "90210",
    "trusted_form_certificate_id": "0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f",
    "leadid_id": "00000000-0000-4000-8000-000000000000",
    "tcpa_call_consent": "1",
    "properties_1_address": "1 Home St",
    "properties_1_city": "Redmond",
    "properties_1_state": "WA",
    "properties_1_zip": "98052",
    "properties_1_year_built": 1991,
    "properties_1_property_type": "Single Family Home"
  }'
201Created
{
  "data": {
    "id": "3f9d2c61-7a4e-4b0b-9c21-5e6f7a8b9c0d",
    "external_id": "HOME-SAMPLE-0001",
    "first_name": "Pamela",
    "last_name": "Silverman",
    "phone": "+13602179499",
    "email": "[email protected]",
    "state": "CA",
    "zip_code": "90210",
    "timezone": "America/Los_Angeles",
    "trustedform_cert_url": "https://cert.trustedform.com/0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f",
    "jornaya_leadid": "00000000-0000-4000-8000-000000000000",
    "current_disposition": "pending",
    "status_url": "https://api.entrovox.com/v1/leads/3f9d2c61-7a4e-4b0b-9c21-5e6f7a8b9c0d",
    "metadata": {
      "properties_1_address": "1 Home St",
      "properties_1_city": "Redmond",
      "properties_1_state": "WA",
      "properties_1_zip": "98052",
      "properties_1_year_built": 1991,
      "properties_1_property_type": "Single Family Home",
      "tcpa_call_consent": "1"
    }
  }
}

(360) 217-9499 is stored as +13602179499. trusted_form_certificate_id became trustedform_cert_url and leadid_id became jornaya_leadid. Neither is repeated in metadata. The property is in Redmond, WA, and the lead's state and calling window come from the contact ZIP 90210.

Errors

JSON
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "phone must be a 10-digit US or Canadian number, so we did not create a lead. Send it like 3602179499 (a leading 1 is ok) and retry.",
    "param": "phone"
  }
}

param is your field name.

HTTPCodeWhen
422VALIDATION_ERRORMissing contact_first_name, contact_last_name, phone, or both ids. "unique_identifier": null with no token counts as missing
400VALIDATION_ERRORA blank name, a bad phone, bad JSON types, or a reserved metadata key
400CONSENT_INVALIDA TrustedForm value is not a certificate URL or a 40-hex id. param is the field you sent
400CONSENT_INVALIDtcpa_call_consent is an explicit no. param is tcpa_call_consent
400VALIDATION_ERRORThe post's fields belong to the other vertical. param is lead_source_id
400VALIDATION_ERRORTwo TrustedForm names with different certificates, or two Jornaya names with different ids. param is the later name
401AUTHENTICATION_REQUIREDNo campaign key at all, neither header nor path segment
401TOKEN_INVALIDA malformed or mismatched campaign key
403LEAD_SOURCE_NOT_ALLOWEDThe body's lead_source_id is not this key's campaign
403INSUFFICIENT_SCOPEThe key cannot create leads
409EXTERNAL_ID_CONFLICTThe same unique_identifier is already stored on this campaign with a different phone. The same id posted to the agency's other campaign is a separate lead
409LEAD_PHONE_CONFLICTThat phone is already enrolled under another id. details is empty when the existing lead belongs to a sibling campaign this key cannot read. A duplicate, not a quality reject
409IDEMPOTENCY_IN_PROGRESSThe same Idempotency-Key is still running: retry the same body
429RATE_LIMIT_EXCEEDEDOver the key's limit. Retry-After is set
503PROVIDER_UNAVAILABLEWe could not finish a compliance check or the campaign lookup. Retry-After is set

Idempotency and retries

  • unique_identifier, or token when that is the id, is the durable lead id.
  • The same id, phone and campaign returns 200 with the header X-Duplicate: external_id and data.replayed=true. It is one lead.
  • Send the optional Idempotency-Key header as a UUID. The same key and the same body returns the original response. A create stays 201, with X-Idempotency-Replayed: true.
  • Do not retry a 4xx, except 409 IDEMPOTENCY_IN_PROGRESS (resend the same body with the same key) and 429 RATE_LIMIT_EXCEEDED (wait for Retry-After, then resend with the same Idempotency-Key).
  • Retry a 5xx or 503 with the same body and the same Idempotency-Key, and honor Retry-After.

See Safe retries and idempotency for the general rules.

Rate limit

100 requests per minute per key. The MediaAlpha route has no bucket of its own: it falls in the shared default bucket, which is separate from the POST /leads, POST /leads/batch and POST /leads/ping buckets. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. The URL form counts as that key, not as an anonymous IP. A query-string key is 400 and still counts toward the anonymous per-IP limit.

Test procedure

  1. We send one key per customer campaign, one per vertical, each with the header URL and the path URL. Run steps 2 to 6 before we activate the campaigns, or only with phones you control, because a post to an active campaign dials.
  2. Post the auto sample to the auto key. Expect 201, phone +13602179499, external_id equal to unique_identifier, and state CA.
  3. Post the same body again. Expect 200, X-Duplicate: external_id and no second lead.
  4. Post the home sample to the home key, with a non-null unique_identifier and a phone you control that differs from step 2. Both samples carry 360-217-9499: the same phone on an active sibling campaign is 409 LEAD_PHONE_CONFLICT, and before activation the second post is 201 and leaves two leads on one phone, which we delete before activating. Expect 201, trustedform_cert_url and jornaya_leadid set, and state CA.
  5. Drop contact_first_name. Expect 422 and "param": "contact_first_name".
  6. Send "phone": "123". Expect 400 and "param": "phone".
  7. A live post dials. For a connectivity test, use a phone you control and tell us before you send it.

Please confirm

Confirm these with us before go-live:

  • unique_identifier is populated on every production post, auto and home. A null id is 422 and the lead is not enrolled.
  • Each vertical posts to its own key and URL. The auto campaign's key receives only auto leads and the home campaign's key receives only home leads. Tell us which of your campaign ids maps to which URL.
  • Will you send a lead timestamp, and under which name? Without one we use the time we received the post.
  • Can your delivery config set Authorization, or only a URL?
  • zip is the contact's residence ZIP. We will not treat driver_1_license_state, a posted state or properties_1_zip as the residence.
  • Production posts are this flat JSON object. Numbers may be strings, and one vehicle string may contain tabs.

Next steps

Follow each lead from its status URL, and run the go-live checklist.

Updated Nov 7, 2026