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
| Form | Request |
|---|---|
| Header (preferred) | POST https://api.entrovox.com/v1/leads/mediaalpha |
| URL only | POST 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,tokenand similar). That returns400. - 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
apicampaign. A differentlead_source_idin the body is403 LEAD_SOURCE_NOT_ALLOWED, so omitlead_source_id. - A read-only key cannot post:
403 INSUFFICIENT_SCOPE.
Field mapping
| Your field | Our field | Required |
|---|---|---|
contact_first_name | first_name | Yes |
contact_last_name | last_name | Yes |
phone | phone, as E.164 +1 plus 10 digits | Yes |
unique_identifier, else token | external_id | Yes: one of the two, as a non-empty string. null counts as absent |
email | email | No |
zip | zip_code. Residence state and timezone come from the ZIP only | Yes |
| TrustedForm names below | trustedform_cert_url | No |
| Jornaya names below | jornaya_leadid | No |
| Lead-time names below | lead_generated_at | No |
| Every other field | metadata, same name, same JSON type | No |
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.
Consent (optional)
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"
}'import os, requests
r = requests.post(
"https://api.entrovox.com/v1/leads/mediaalpha",
headers={"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}"},
json={
"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",
},
timeout=15,
)
r.raise_for_status()
lead = r.json()["data"]
print(r.status_code, lead["status_url"])const res = await fetch("https://api.entrovox.com/v1/leads/mediaalpha", {
method: "POST",
headers: {
Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
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",
}),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const { data: lead } = await res.json();
console.log(res.status, lead.status_url);{
"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"
}'import os, requests
r = requests.post(
"https://api.entrovox.com/v1/leads/mediaalpha",
headers={"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}"},
json={
"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",
},
timeout=15,
)
r.raise_for_status()
lead = r.json()["data"]
print(r.status_code, lead["status_url"])const res = await fetch("https://api.entrovox.com/v1/leads/mediaalpha", {
method: "POST",
headers: {
Authorization: `ApiKey ${process.env.ENTROVOX_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
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",
}),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const { data: lead } = await res.json();
console.log(res.status, lead.status_url);{
"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
{
"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.
| HTTP | Code | When |
|---|---|---|
| 422 | VALIDATION_ERROR | Missing contact_first_name, contact_last_name, phone, or both ids. "unique_identifier": null with no token counts as missing |
| 400 | VALIDATION_ERROR | A blank name, a bad phone, bad JSON types, or a reserved metadata key |
| 400 | CONSENT_INVALID | A TrustedForm value is not a certificate URL or a 40-hex id. param is the field you sent |
| 400 | CONSENT_INVALID | tcpa_call_consent is an explicit no. param is tcpa_call_consent |
| 400 | VALIDATION_ERROR | The post's fields belong to the other vertical. param is lead_source_id |
| 400 | VALIDATION_ERROR | Two TrustedForm names with different certificates, or two Jornaya names with different ids. param is the later name |
| 401 | AUTHENTICATION_REQUIRED | No campaign key at all, neither header nor path segment |
| 401 | TOKEN_INVALID | A malformed or mismatched campaign key |
| 403 | LEAD_SOURCE_NOT_ALLOWED | The body's lead_source_id is not this key's campaign |
| 403 | INSUFFICIENT_SCOPE | The key cannot create leads |
| 409 | EXTERNAL_ID_CONFLICT | The 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 |
| 409 | LEAD_PHONE_CONFLICT | That 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 |
| 409 | IDEMPOTENCY_IN_PROGRESS | The same Idempotency-Key is still running: retry the same body |
| 429 | RATE_LIMIT_EXCEEDED | Over the key's limit. Retry-After is set |
| 503 | PROVIDER_UNAVAILABLE | We could not finish a compliance check or the campaign lookup. Retry-After is set |
Idempotency and retries
unique_identifier, ortokenwhen that is the id, is the durable lead id.- The same id, phone and campaign returns
200with the headerX-Duplicate: external_idanddata.replayed=true. It is one lead. - Send the optional
Idempotency-Keyheader as a UUID. The same key and the same body returns the original response. A create stays201, withX-Idempotency-Replayed: true. - Do not retry a
4xx, except409 IDEMPOTENCY_IN_PROGRESS(resend the same body with the same key) and429 RATE_LIMIT_EXCEEDED(wait forRetry-After, then resend with the sameIdempotency-Key). - Retry a
5xxor503with the same body and the sameIdempotency-Key, and honorRetry-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
- 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.
- Post the auto sample to the auto key. Expect
201,phone+13602179499,external_idequal tounique_identifier, andstateCA. - Post the same body again. Expect
200,X-Duplicate: external_idand no second lead. - Post the home sample to the home key, with a non-null
unique_identifierand a phone you control that differs from step 2. Both samples carry360-217-9499: the same phone on an active sibling campaign is409 LEAD_PHONE_CONFLICT, and before activation the second post is201and leaves two leads on one phone, which we delete before activating. Expect201,trustedform_cert_urlandjornaya_leadidset, andstateCA. - Drop
contact_first_name. Expect422and"param": "contact_first_name". - Send
"phone": "123". Expect400and"param": "phone". - 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_identifieris populated on every production post, auto and home. A null id is422and 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? zipis the contact's residence ZIP. We will not treatdriver_1_license_state, a postedstateorproperties_1_zipas 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.