Marketing Sources API: Submit Leads Directly to Mav

POST lead data directly to Mav via a unique Marketing Source URL — supports JSON and form-encoded payloads, with full field reference included.

The Marketing Sources API is Mav’s inbound lead submission interface. Each Marketing Source you create in the Mav dashboard generates a unique POST endpoint (called a postURL) that is tied to a specific playbook. When you submit a lead to that URL, Mav immediately enrolls the lead into the associated playbook and begins working them — no manual import, no dashboard interaction required.

This page covers everything you need to know to integrate your lead sources, marketing platforms, or CRM workflows with Mav’s inbound API.

---

Getting Your postURL

Every Marketing Source has its own unique postURL. To find yours:

1. Log into the Mav dashboard.
2. Navigate to Integrations → Marketing Sources.
3. Select the Marketing Source you want to use, or create a new one.
4. Copy the postURL shown on the source detail page.

The postURL encodes both your account ID and the source ID directly in the path, so the URL itself acts as your credential — no API key or header-based auth is required for this endpoint.

Your postURL is sensitive. Anyone who has the URL can submit leads to your playbook and consume your messaging credits. Do not expose it in client-side code, public repositories, or browser-accessible JavaScript.

---

Endpoint

POST https://hiremav.com/marketing_sources/{account_id}/{source_id}

Path Parameters

Parameter	Description
account_id	Your Mav account identifier (e.g., acc_2SbUe8xLqEqrL3). Found in your postURL.
source_id	The unique identifier for the Marketing Source (e.g., mks_kgaafDRBWshCzp). Found in your postURL.

Both values are embedded in the postURL you copied from the dashboard — you do not need to construct the URL manually.

---

Request Formats

The endpoint accepts two content types. Use whichever is most convenient for your integration platform.

JSON

curl -X POST "https://hiremav.com/marketing_sources/acc_2SbUe8xLqEqrL3/mks_kgaafDRBWshCzp" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "[e-mail]",
    "phone": "5551234567",
    "current_insurance_carrier": "State Farm",
    "current_insurance_coverage": "Full Coverage",
    "current_residence_address": "123 Main St",
    "current_residence_city": "Austin",
    "current_residence_state": "TX",
    "current_residence_zip": "78701",
    "date_of_birth": "1985-04-15",
    "gender": "Male",
    "marital_status": "Married",
    "credit_rating": "Good",
    "tcpa_opt_in_token": "jornaya-token-abc123",
    "tcpa_opt_in_url": "https://proof.jornaya.com/abc123"
  }'

curl -X POST "https://hiremav.com/marketing_sources/acc_2SbUe8xLqEqrL3/mks_kgaafDRBWshCzp" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "first_name=John" \
  --data-urlencode "last_name=Doe" \
  --data-urlencode "email=[e-mail]" \
  --data-urlencode "phone=5551234567" \
  --data-urlencode "current_insurance_carrier=State Farm" \
  --data-urlencode "current_insurance_coverage=Full Coverage" \
  --data-urlencode "current_residence_address=123 Main St" \
  --data-urlencode "current_residence_city=Austin" \
  --data-urlencode "current_residence_state=TX" \
  --data-urlencode "current_residence_zip=78701" \
  --data-urlencode "date_of_birth=1985-04-15" \
  --data-urlencode "gender=Male" \
  --data-urlencode "marital_status=Married" \
  --data-urlencode "credit_rating=Good" \
  --data-urlencode "tcpa_opt_in_token=jornaya-token-abc123" \
  --data-urlencode "tcpa_opt_in_url=https://proof.jornaya.com/abc123"

---

Request Fields

The fields below are required for a standard Mortgage Qualification playbook. The exact required fields depend on your specific playbook configuration — contact your Mav account team if you are unsure which fields your playbook needs.

Identity Fields

first_name · string · required

The lead’s given name.

last_name · string · required

The lead’s family name or surname.

email · string · required

The lead’s email address. Used for identification and follow-up.

phone · string · required

The lead’s phone number. Accepts formats with or without formatting characters (e.g., 5551234567 or 555-123-4567). Mav will normalize the number.

date_of_birth · string · required

The lead’s full date of birth in YYYY-MM-DD format. Used for quoting and identity verification.

gender · string · required

The lead’s identified gender (e.g., Male, Female).

marital_status · string · required

The lead’s marital status. Accepted values include Single, Married, Divorced, Widowed.

Residence Fields

current_residence_address · string · required

Full street address of the lead’s current residence (e.g., 123 Main St).

current_residence_city · string · required

City where the lead currently resides.

current_residence_state · string · required

Two-letter state abbreviation where the lead currently resides (e.g., TX).

current_residence_zip · string · required

ZIP code of the lead’s current residence (e.g., 78701).

Insurance Fields

current_insurance_carrier · string · required

The name of the insurance company currently providing the lead’s policy (e.g., State Farm, Geico).

current_insurance_coverage · string · required

The type or level of the lead’s existing insurance coverage (e.g., Full Coverage, Liability Only).

credit_rating · string · required

The lead’s self-reported credit tier. Accepted values: Excellent, Good, Fair, Poor.

TCPA Consent Fields

tcpa_opt_in_token · string · required

A TCPA consent token from a certified consent provider such as Jornaya or ActiveProspect. This token serves as proof that the lead provided verifiable consent to be contacted.

tcpa_opt_in_url · string · required

The URL to the TCPA proof-of-consent record (e.g., https://proof.jornaya.com/abc123). This is used for compliance documentation and audit purposes.

---

TCPA Compliance

Both tcpa_opt_in_token and tcpa_opt_in_url are required for all lead submissions. Submitting leads without valid TCPA consent documentation is a compliance violation and may result in your Marketing Source being suspended.

Mav uses these tokens to verify that the lead consented to automated messaging before any outreach begins. Ensure your lead generation forms are configured to capture and pass Jornaya or ActiveProspect tokens on every submission.

If you are generating leads through your own web forms, integrate with Jornaya LeadiD or ActiveProspect TrustedForm to capture consent tokens at the point of form submission.

---

What Happens After Submission

Once Mav receives a valid lead submission:

1. Lead is created — Mav creates a lead record with the submitted data and assigns a unique lead_id.
2. Lead is tagged to the source — The lead is associated with the Marketing Source, so you can track attribution and volume per source in the Mav dashboard.
3. Playbook starts — Mav begins the playbook sequence for that source. The started event fires and is delivered to any subscribed webhook URLs.
4. Activity flows back to you — As the lead progresses, Mav fires events and outcomes to your configured webhook endpoints, including the lead_originators data so you can match updates back to your records.

A successful submission returns an HTTP 200 response. If required fields are missing or the payload is malformed, the endpoint returns a 4xx error with a description of the problem.

---

Passing Your Own Lead ID

If you want to match Mav webhook activity back to a specific record in your system, include your internal lead identifier as a custom field when submitting the lead. Mav will echo it back in the lead_originators array on every webhook payload.

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "[e-mail]",
  "phone": "5551234567",
  "your_crm_id": "crm-lead-id-456",
  ...
}

When Mav sends a webhook for that lead, the lead_originators field will contain the source name and the key value you provided, letting you do a direct lookup in your CRM without any fuzzy matching.

---

Related Pages

• API Overview — How the inbound and outbound APIs work together.
• Outbound Webhooks — Receive real-time activity as Mav works your submitted leads.
• Event Activities — Every event that can fire after a lead is submitted.
• Outcome Activities — Every outcome that closes out a lead’s playbook journey.