Mav API Overview: Lead Inbound & Outbound Surfaces

Mav exposes two API surfaces — submit leads via Marketing Sources and receive real-time playbook activity updates via outbound webhooks.

Mav provides two complementary API surfaces that together give you full programmatic control over your lead pipeline. You push leads into Mav through the Inbound API (Marketing Sources), and Mav pushes real-time activity updates back to you through the Outbound API (webhooks). Whether you’re connecting a lead generation platform, syncing your CRM, or triggering downstream automations, these two surfaces cover the complete lifecycle of a lead in your playbook.

Two API Surfaces

Marketing Sources API

Submit leads directly to Mav via a unique POST endpoint tied to your playbook. Supports JSON and form-encoded payloads.

Outbound Webhooks

Subscribe to real-time event and outcome activity from Mav. Mav posts a JSON payload to your URL whenever something happens on a lead.

Event Activities

A reference of every event Mav can fire — from the first message sent through party line calls and copilot interventions.

Outcome Activities

A reference of every outcome Mav can fire — the terminal states that tell you how a lead’s playbook journey ended.

---

How the Two Surfaces Work Together

The inbound and outbound APIs are designed to create a closed loop between your systems and Mav:

1. You submit a lead — Your marketing platform, CRM, or custom code POSTs lead data to a Marketing Source postURL. Mav immediately enrolls the lead into the associated playbook.
2. Mav works the lead — Mav sends messages, handles responses, and runs the lead through your configured playbook sequences.
3. You receive activity updates — As the lead progresses, Mav fires webhook events and outcomes to your configured endpoint. You update your records, trigger follow-up workflows, or route the lead to a rep.

This flow means you never have to poll Mav for status — everything is push-based and real-time.

---

Quick-Start Flow

Follow these steps to get leads flowing in and results flowing back out.

Step 1 — Create a Marketing Source

In the Mav dashboard, navigate to Integrations → Marketing Sources and create a new source tied to the playbook you want to use. Mav generates a unique postURL for that source.

Step 2 — Send Your First Lead

POST lead data to your postURL. A standard submission requires identity, residence, insurance, and TCPA consent fields. See the Marketing Sources API reference for the complete required field list.

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

Step 3 — Subscribe to Webhooks

In your playbook settings, add one or more webhook URLs under the Activity Subscriptions section. Select the events and outcomes you want to receive — you can subscribe to as many or as few as your workflow requires.

Step 4 — Handle Incoming Payloads

Your endpoint receives a JSON payload each time a subscribed activity occurs. Use the lead_originators fields to match the activity back to the original lead in your system.

{
  "activity_type": "outcome",
  "activity_label": "qualified",
  "lead_originators": [
    { "origin": "your_crm", "key": "crm-lead-id-456" }
  ]
}

---

Authentication

Surface	Credential
Marketing Sources	The unique postURL itself acts as the credential. Keep it private.
Outbound Webhooks	No inbound auth required — Mav posts to your URL. Secure your endpoint with HTTPS and validate the payload structure.
Zapier Integration	Uses your Mav API Key, found in Settings → Integrations.

Your Marketing Source postURL contains your account and source identifiers. Treat it like a secret — anyone with the URL can submit leads to that playbook.

---

Next Steps

• Read the Marketing Sources API reference to see the full field list and code examples.
• Read the Outbound Webhooks reference to understand the payload structure and best practices.
• Browse Event Activities and Outcome Activities for a complete list of everything Mav can fire.