{
  "openapi": "3.1.0",
  "info": {
    "title": "Entrovox MediaAlpha Lead Intake API",
    "version": "1.0.0",
    "description": "HTTP POST intake endpoint for MediaAlpha insurance leads.\nAccepts flat native MediaAlpha JSON payloads and maps them into Entrovox leads,\npreserving all additional attributes in the lead's metadata.\n\n## Authentication\nEach API key (`sk_entrovox_...`) is bound to a single Entrovox organization and campaign,\nand a campaign is one line of business. An agency that buys auto and home has an auto key\nand a home key; post each vertical to its own key and URL. The campaign's line decides the\nvoice script; a post whose fields belong to the other vertical is refused (400, param\nlead_source_id).\nTwo delivery forms are supported:\n1. **Header Authentication (Preferred):** `Authorization: ApiKey sk_entrovox_...` (or `Bearer sk_entrovox_...`)\n2. **URL Path Authentication:** Campaign key embedded in the URL path (`POST /v1/leads/mediaalpha/{campaign_key}`)\n   for delivery platforms that cannot configure custom headers.\n"
  },
  "servers": [
    {
      "url": "https://api.entrovox.com/v1",
      "description": "Production API"
    }
  ],
  "paths": {
    "/leads/mediaalpha": {
      "post": {
        "summary": "Ingest MediaAlpha lead (Header authentication)",
        "description": "Ingest native MediaAlpha insurance lead JSON payload. Requires API key in Authorization header.\nMapped leads are enrolled into the campaign bound to the API key.\n",
        "operationId": "createMediaAlphaLead",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional UUID idempotency key.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MediaAlphaLeadPayload"
              },
              "examples": {
                "auto": {
                  "summary": "Auto lead (post to the auto campaign's key)",
                  "value": {
                    "contact_first_name": "Pamela",
                    "contact_last_name": "Silverman",
                    "phone": "3602179499",
                    "zip": "90210",
                    "unique_identifier": "AD7RL34G4CQNGKFP27AX6ANP27AX6ABEHI",
                    "token": "AD7RL34G4CQNGKFP27AX6ANP27AX6ABEHI",
                    "email": "person@quotelab.com",
                    "address": "120 Jenkins Rd",
                    "city": "Beverly Hills",
                    "driver_1_license_state": "GA",
                    "vehicle_1_year": 2024,
                    "vehicle_1_make": "HONDA",
                    "vehicle_1_model": "CIVIC SI",
                    "coverage_type": "Standard Protection"
                  }
                },
                "home": {
                  "summary": "Home lead (post to the home campaign's key)",
                  "value": {
                    "contact_first_name": "Pamela",
                    "contact_last_name": "Silverman",
                    "phone": "(360) 217-9499",
                    "zip": "90210",
                    "unique_identifier": "HOME-SAMPLE-0001",
                    "email": "person@quotelab.com",
                    "address": "120 Jenkins Rd",
                    "address_2": "Apt 12",
                    "city": "Beverly Hills",
                    "state": "CA",
                    "birth_date": "1970-05-19",
                    "trusted_form_certificate_id": "0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f0f",
                    "leadid_id": "00000000-0000-4000-8000-000000000000",
                    "tcpa_call_consent": "1",
                    "tcpa_sms_consent": "1",
                    "tcpa_email_consent": "1",
                    "tcpa_url": "http://www.quotelab.com/privacy-policy.html",
                    "properties_1_address": "1 Home St",
                    "properties_1_city": "Redmond",
                    "properties_1_state": "WA",
                    "properties_1_zip": "98052",
                    "properties_1_property_type": "Single Family Home",
                    "properties_1_year_built": 1991,
                    "properties_1_coverage_amount": "1000000"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Lead accepted and enrolled.",
            "headers": {
              "X-Idempotency-Replayed": {
                "schema": {
                  "type": "boolean"
                },
                "description": "Set to true when an existing request is replayed by Idempotency-Key."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaAlphaLeadResponse"
                },
                "examples": {
                  "auto": {
                    "summary": "Auto lead accepted",
                    "value": {
                      "data": {
                        "id": "7c2e1a90-2b1f-4d3a-9e0c-0b8c1d2e3f40",
                        "external_id": "AD7RL34G4CQNGKFP27AX6ANP27AX6ABEHI",
                        "first_name": "Pamela",
                        "last_name": "Silverman",
                        "phone": "+13602179499",
                        "email": "person@quotelab.com",
                        "state": "CA",
                        "zip_code": "90210",
                        "timezone": "America/Los_Angeles",
                        "trustedform_cert_url": null,
                        "jornaya_leadid": null,
                        "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_license_state": "GA",
                          "vehicle_1_make": "HONDA",
                          "vehicle_1_year": 2024,
                          "token": "AD7RL34G4CQNGKFP27AX6ANP27AX6ABEHI",
                          "coverage_type": "Standard Protection"
                        }
                      }
                    }
                  },
                  "home": {
                    "summary": "Home lead accepted (consent lifted)",
                    "value": {
                      "data": {
                        "id": "3f9d2c61-7a4e-4b0b-9c21-5e6f7a8b9c0d",
                        "external_id": "HOME-SAMPLE-0001",
                        "first_name": "Pamela",
                        "last_name": "Silverman",
                        "phone": "+13602179499",
                        "email": "person@quotelab.com",
                        "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": {
                          "address": "120 Jenkins Rd",
                          "city": "Beverly Hills",
                          "state": "CA",
                          "birth_date": "1970-05-19",
                          "properties_1_address": "1 Home St",
                          "properties_1_state": "WA",
                          "properties_1_zip": "98052",
                          "tcpa_call_consent": "1"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "200": {
            "description": "Duplicate lead replayed (same unique_identifier, phone, and campaign).",
            "headers": {
              "X-Duplicate": {
                "schema": {
                  "type": "string"
                },
                "description": "Value is external_id indicating dedup replay."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaAlphaLeadResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error or invalid consent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "code": "VALIDATION_ERROR",
                    "message": "phone must be a 10-digit US or Canadian number.",
                    "param": "phone"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Malformed or mismatched API key (TOKEN_INVALID); a post with no key at all is 401 AUTHENTICATION_REQUIRED.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "code": "TOKEN_INVALID",
                    "message": "The campaign key was not recognized or has been revoked."
                  }
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope or lead source not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "code": "LEAD_SOURCE_NOT_ALLOWED",
                    "message": "The specified lead source is not allowed for this key."
                  }
                }
              }
            }
          },
          "409": {
            "description": "Conflict (external_id conflict, lead phone conflict, or idempotency in progress).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "code": "EXTERNAL_ID_CONFLICT",
                    "message": "external_id is already used by a lead with a different phone, campaign, or is_test, so we did not create a new one. Send a new external_id for a different lead, or retry with the original values."
                  }
                }
              }
            }
          },
          "422": {
            "description": "Missing required fields.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": {
                    "code": "VALIDATION_ERROR",
                    "message": "Request validation failed.",
                    "param": "contact_first_name"
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (100 requests per minute per key).",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait before retrying."
              },
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Provider unavailable (e.g. temporary compliance service downtime).",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/leads/mediaalpha/{campaign_key}": {
      "post": {
        "summary": "Ingest MediaAlpha lead (URL-path authentication)",
        "description": "Ingest native MediaAlpha insurance lead JSON payload with campaign API key in the URL path.\nUsed when delivery platform cannot set custom HTTP Authorization headers.\n",
        "operationId": "createMediaAlphaLeadWithPathKey",
        "parameters": [
          {
            "name": "campaign_key",
            "in": "path",
            "required": true,
            "description": "Campaign API key (e.g. sk_entrovox_...).",
            "schema": {
              "type": "string",
              "pattern": "^(?:sk_entrovox_|sk_surance_)[0-9a-f]{40}$"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional UUID idempotency key.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MediaAlphaLeadPayload"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Lead accepted and enrolled.",
            "headers": {
              "X-Idempotency-Replayed": {
                "schema": {
                  "type": "boolean"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaAlphaLeadResponse"
                }
              }
            }
          },
          "200": {
            "description": "Duplicate lead replayed.",
            "headers": {
              "X-Duplicate": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MediaAlphaLeadResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error or invalid consent.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Malformed or mismatched API key (TOKEN_INVALID); a post with no key at all is 401 AUTHENTICATION_REQUIRED.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient scope or lead source not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Conflict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Missing required fields.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Provider unavailable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Format: `Authorization: ApiKey sk_entrovox_...`"
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Format: `Authorization: Bearer sk_entrovox_...`"
      }
    },
    "schemas": {
      "MediaAlphaLeadPayload": {
        "type": "object",
        "required": [
          "contact_first_name",
          "contact_last_name",
          "phone",
          "zip"
        ],
        "anyOf": [
          {
            "required": [
              "unique_identifier"
            ]
          },
          {
            "required": [
              "token"
            ]
          }
        ],
        "properties": {
          "contact_first_name": {
            "type": "string",
            "description": "Prospect first name.",
            "example": "Pamela"
          },
          "contact_last_name": {
            "type": "string",
            "description": "Prospect last name.",
            "example": "Silverman"
          },
          "phone": {
            "type": "string",
            "description": "10-digit US/Canadian phone number.",
            "example": "3602179499"
          },
          "zip": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              }
            ],
            "description": "5-digit US residence ZIP code.",
            "example": "90210"
          },
          "unique_identifier": {
            "type": "string",
            "description": "Primary MediaAlpha lead id. Required if `token` is absent. Must be a non-empty string: `null` is treated as absent and the post is 422 (no fallback to a Jornaya or TrustedForm id).",
            "example": "AD7RL34G4CQNGKFP27AX6ANP27AX6ABEHI"
          },
          "token": {
            "type": "string",
            "description": "Secondary MediaAlpha token/id. Required if `unique_identifier` is absent.",
            "example": "AD7RL34G4CQNGKFP27AX6ANP27AX6ABEHI"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Prospect email address.",
            "example": "person@quotelab.com"
          },
          "trustedform_cert_url": {
            "type": "string",
            "description": "TrustedForm certificate URL or 40-character hex ID. Also accepted, in precedence order, under `trusted_form_cert_url`, `trustedform_url`, `trusted_form_url`, `trustedform`, `trusted_form`, `xxTrustedFormCertUrl`, `xxTrustedFormToken`, `trustedform_token`, `tf_cert_url`, `trusted_form_certificate_id` (the home sample's name). First non-empty name wins; a second non-empty name must carry the same certificate or the post is 400 (param is the later name)."
          },
          "jornaya_leadid": {
            "type": "string",
            "description": "Jornaya LeadID token. Also accepted, in precedence order, under `jornaya_lead_id`, `leadid_token`, `universal_leadid`, `jornaya_token`, `leadid`, `leadid_id` (the home sample's name). Stored, not format-checked, max 256 characters. A second non-empty Jornaya name must carry the same id or the post is 400 (param is the later name)."
          },
          "lead_generated_at": {
            "type": "string",
            "format": "date-time",
            "description": "ISO-8601 lead generation timestamp."
          },
          "lead_source_id": {
            "type": "string",
            "format": "uuid",
            "description": "Optional lead source ID. Must match the key's bound campaign if provided."
          },
          "tcpa_call_consent": {
            "description": "MediaAlpha's call-consent flag. \"0\", 0 (any numeric zero, including 0.0), false or \"false\" is an explicit no and the post is 400 CONSENT_INVALID (param tcpa_call_consent) with no lead. Any other value, or no field, is accepted and stored in metadata."
          }
        },
        "additionalProperties": true
      },
      "MediaAlphaLeadResponse": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "type": "object",
            "description": "The lead object. Fields not listed here follow the partner lead object.",
            "additionalProperties": true,
            "required": [
              "id",
              "external_id",
              "first_name",
              "last_name",
              "phone",
              "state",
              "zip_code",
              "current_disposition",
              "status_url"
            ],
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "description": "Entrovox lead UUID."
              },
              "external_id": {
                "type": "string",
                "description": "MediaAlpha identifier (unique_identifier or token)."
              },
              "first_name": {
                "type": "string"
              },
              "last_name": {
                "type": "string"
              },
              "phone": {
                "type": "string",
                "description": "E.164 phone number.",
                "example": "+13602179499"
              },
              "email": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "state": {
                "type": "string",
                "description": "2-letter state code resolved from ZIP code.",
                "example": "CA"
              },
              "zip_code": {
                "type": "string",
                "example": "90210"
              },
              "timezone": {
                "type": [
                  "string",
                  "null"
                ],
                "example": "America/Los_Angeles"
              },
              "current_disposition": {
                "type": "string",
                "example": "pending"
              },
              "status_url": {
                "type": "string",
                "format": "uri"
              },
              "replayed": {
                "type": "boolean",
                "description": "True if this response is a duplicate replay."
              },
              "trustedform_cert_url": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uri",
                "description": "TrustedForm certificate URL lifted from any accepted TrustedForm name, else null."
              },
              "jornaya_leadid": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Jornaya LeadID lifted from any accepted Jornaya name, else null."
              },
              "metadata": {
                "type": "object",
                "description": "Preserved native fields from the MediaAlpha payload."
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "example": "VALIDATION_ERROR"
              },
              "message": {
                "type": "string",
                "example": "Problem, cause, and fix in one sentence."
              },
              "param": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The specific field name that failed validation."
              },
              "details": {
                "type": [
                  "object",
                  "null"
                ]
              },
              "doc_url": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "request_id": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        }
      }
    }
  }
}