Lead Posting Integration.

Mav accepts inbound insurance leads via a single HTTPS POST. Authentication is by possession of a unique per-source URL — no API key, no token exchange, no SDK to install. Send what you have. Mav handles the rest.

01Overview

Each Mav customer (an insurance agency) creates a unique Marketing Source record for your integration. That record generates a posting URL containing the agency's account ID and the source ID embedded in the path. The agency hands you that URL — you POST leads to it.

Because the URL itself is the credential, treat it as a shared secret. Anyone with the URL can post leads on that source. Rotate by asking the agency to create a new Marketing Source.

02Endpoint

POST https://hiremav.com/marketing_sources/{customer_uuid}/{source_uuid}

Headers:

Content-Type: application/json

Path variable	Meaning
{customer_uuid}	The agency's Mav account ID.
{source_uuid}	The marketing source ID identifying your integration.

The full URL is the credential. No API key, bearer token, or signature is required or accepted. Store it the way you would store a secret — environment variable, secrets manager, never in client-side code or committed to source control.

03Setup flow

The agency creates a Marketing Source in Mav and selects your integration from the directory, or sets up a custom source.
Mav generates a unique posting URL of the form https://hiremav.com/marketing_sources/{customer_uuid}/{source_uuid}.
The agency sends that URL to you, typically via support ticket or onboarding email.
You post leads to the URL using the JSON schema documented below.

04Required fields

All requests must include these four fields, regardless of insurance line. Missing any of them returns 422 with {"errors": ["Missing required fields: <field>"]}.

Field	Type	Notes
first_name	string	—
last_name	string	—
email	string	—
phone	string	Any common US format accepted (e.g. `5551234567`, `555-123-4567`, `(555) 123-4567`). Internally normalized to E.164. Must be a valid, SMS-capable US mobile number.

05TCPA & compliance

Strongly recommended on every request. Mav stores these for audit purposes and uses them to defend consent in the event of a dispute.

Compliance & consent evidence

tcpa_opt_in_tokentcpa_opt_in_url tcpa_languagetcpa_consent trusted_form_urlleadid_token ip_addressuser_agent device_type

tcpa_opt_in_token & tcpa_opt_in_url — Jornaya / ActiveProspect lead token and consent proof URL (auto). tcpa_language — verbatim TCPA disclosure text shown to the consumer. tcpa_consent & trusted_form_url & leadid_token — boolean consent flag, TrustedForm cert URL, and LeadiD token (home). device_type accepts mobile / desktop / tablet.

You are asserting consent. By posting to this endpoint, you assert the consumer has given valid SMS consent. Mav auto-sets sms_consent=true on every lead created via this endpoint.

06Auto insurance fields

Send what you have. Unknown fields are silently ignored. Partial data is fine — Mav will collect missing detail in the SMS conversation.

Contact & location

addresscitystatezip current_residence_addresscurrent_residence_city current_residence_statecurrent_residence_zip date_of_birthgendermarital_statuscredit_rating

Current policy

current_insurance_carrier current_insurance_coverage current_insurance_since

Vehicles (up to 3) — either prefix accepted

Ordinal form:

1st_vehicle_make1st_vehicle_model 1st_vehicle_year1st_vehicle_vin 2nd_vehicle_*3rd_vehicle_*

Or numbered form:

vehicle_1_makevehicle_1_model vehicle_1_yearvehicle_1_vin vehicle_2_*vehicle_3_*

Per-vehicle detail (vehicle 1 & 2)

vehicle_N_sub_modelvehicle_N_ownership vehicle_N_primary_usevehicle_N_annual_mileage vehicle_N_average_one_way_mileage vehicle_N_average_days_per_week_used vehicle_N_security_systemvehicle_N_parking vehicle_N_desired_collision_coverage vehicle_N_desired_comprehensive_coverage vehicle_2_coverage_type

Driver 1

driver_1_agedriver_1_birthdatedriver_1_gender driver_1_marital_statusdriver_1_credit_rating driver_1_license_statusdriver_1_licensed_state driver_1_age_when_first_licensed driver_1_suspended_or_revoked_in_the_past_5_years driver_1_filing_requireddriver_1_education driver_1_occupationdriver_1_current_residence driver_1_years_at_current_residence driver_1_months_at_current_residence driver_1_tickets_accidents_claims_past_3_years driver_1_insured_past_30_days driver_1_policy_expiration_date driver_1_insured_sincedriver_1_insurance_company driver_1_current_insurance_company_years driver_1_current_insurance_company_months driver_1_continuously_insured_years driver_1_continuously_insured_months driver_1_bankruptcy_in_past_5_years driver_1_additional_drivers driver_1_additional_vehicles driver_1_reposessions_in_the_past_5_years driver_1_dui_dwi_in_the_past_5_years driver_1_date_of_dui_dwidriver_1_dui_state

Driver 1 incidents (up to 3, N ∈ {1, 2, 3})

driver_1_incident_type_N driver_1_approximate_date_N driver_1_damages_Ndriver_1_at_fault_N driver_1_insurance_paid_amount_N

Driver 2

driver_2_first_namedriver_2_last_name driver_2_addressdriver_2_city driver_2_statedriver_2_zip driver_2_daytime_phonedriver_2_email driver_2_birthdatedriver_2_age driver_2_genderdriver_2_marital_status driver_2_credit_ratingdriver_2_license_status driver_2_licensed_state driver_2_age_when_first_licensed driver_2_suspended_or_revoked_in_the_past_5_years driver_2_filing_requireddriver_2_education

Call routing

did — direct inward dial number to associate with the lead for party line routing.

07Home insurance fields

Same envelope, different schema. Send everything you have.

Contact & location

addresscitystatezip primary_phoneorigin_phone dobgender

Property

property_typeyear_built construction_typeheating_type roof_typestories bedroomsbathrooms square_footagehome_value garagehome_securitysmoke_alarm

Current policy & coverage

currently_insuredcurrent_insurance_company insured_sincepolicy_expiration coverage_typeliability deductibleclaimscredit

Source & call routing

srclanding_pagedid

08Phone number rules

Format flexible on input; normalized to E.164 internally.
Must be a valid US number.
Must be mobile / SMS-capable. Landlines are rejected (422 — Phone number is not SMS enabled.).
Numbers on the agency's internal block list, DNC, or Blacklist Alliance (if enabled) are rejected (422).

09Response codes

Status	Body	Meaning
201	`{"messages": ["Lead has been added."]}`	New lead created and queued for outreach.
200	`{"messages": ["Lead already exists; Play created"]}`	Existing lead matched by phone number; new outreach play scheduled.
400	`{"error": "Invalid JSON"}`	Malformed request body.
404	`{"error": "Unknown Request"}` / `{"error": "Unknown Marketing Request"}`	Account or source UUID in URL is invalid.
422	`{"errors": ["..."]}`	Validation failed — see message for reason.

Common 422 messages

Missing required fields: <fields>
Phone number is invalid.
Phone number is not SMS enabled.
This phone number is blocked.
Lead requires sms_consent=true for Mav to text.

10Deduplication

Mav deduplicates by phone number scoped to the agency's account. If a lead with the same normalized phone already exists, Mav will not create a duplicate — it returns 200 with Lead already exists; Play created and schedules a new outreach attempt against the existing lead record.

✓

Resending is safe. You do not need to track or filter for prior submissions on your side. Mav handles it.

11Example request

A complete auto-insurance lead with TCPA evidence attached.

curlcurl -X POST \
  "https://hiremav.com/marketing_sources/{customer_uuid}/{source_uuid}" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "5551234567",
    "address": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "date_of_birth": "1985-06-15",
    "gender": "male",
    "marital_status": "married",
    "current_insurance_carrier": "Geico",
    "current_insurance_since": "2022-01-01",
    "1st_vehicle_make": "Ford",
    "1st_vehicle_model": "F-150",
    "1st_vehicle_year": "2022",
    "1st_vehicle_vin": "1FTFW1E57PKE12345",
    "driver_1_license_status": "valid",
    "driver_1_licensed_state": "TX",
    "tcpa_opt_in_token": "ABCD-1234-EFGH-5678",
    "tcpa_opt_in_url": "https://leadid.com/proof/ABCD-1234-EFGH-5678",
    "tcpa_language": "By clicking submit, I agree to receive calls and texts...",
    "ip_address": "203.0.113.42",
    "user_agent": "Mozilla/5.0 ...",
    "device_type": "desktop"
  }'

Successful response

HTTP 201{
  "messages": ["Lead has been added."]
}

12Volume & retries

No published rate limit. Standard ramping is recommended for the first 24 hours of a new integration.
For 5xx responses, retry with exponential backoff (e.g. 30s, 2m, 10m).
Do not retry on 4xx — the lead will not become valid by resending.
Every request is logged on Mav's side and retained for 90 days for support and troubleshooting.

Ramp gradually. Hammering the endpoint with full production volume on day one can trip carrier-level deliverability throttles even though Mav itself will accept the leads. Start at <10% and step up.

13Support

Topic	Contact
Integration questions	sales@hiremav.com
Operational issues	support@hiremav.com