Book a demo

API Documentation

Base URL https://hiremav.com/api/v3
View as Markdown

Overview

View as Markdown

Mav works your leads. Your own systems know which of them go on to quote and buy. The Mav API closes that loop, so Mav’s records match yours and it stops following up with people who have already converted.

It’s REST over HTTPS with JSON in and out. Every endpoint lives under https://hiremav.com/api/v3.

  1. 1 List conversions once, at setup, and keep the id of each one you’ll record.
  2. 2 Find the contact by phone number when someone quotes or buys on your side.
  3. 3 Record the conversion against that contact.

Authentication

View as Markdown

Send your account’s API key as a bearer token on every request. Your Mav team can give you your key. Keep it on your server, never in a browser or app: it can read your contacts.

The examples read it from a MAV_API_KEY environment variable.

Headers

HTTP 
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

A missing or wrong key gets 403 Forbidden.

Contacts

The people Mav works for you. Find one by phone number to get the id the other calls need.

Find a contact

View as Markdown

GET /api/v3/contacts/find

Looks up a contact by phone number. Send it in any common US format; Mav normalizes it to E.164 (+13125550142) before matching. A phone number matches at most one contact in your account.

Parameters

phone

string, query · required

The contact’s phone number, like +13125550142 or (312) 555-0142. URL-encode it: a bare + in a query string reads as a space.

Request

cURL 
curl -G https://hiremav.com/api/v3/contacts/find \
  -H "Authorization: Bearer $MAV_API_KEY" \
  --data-urlencode "phone=+13125550142"

200 OK

JSON 
{
  "contact": {
    "id": "nct_7Hq2xKpR9vLm3N",
    "first_name": "Jordan",
    "last_name": "Rivera",
    "email": "jordan.rivera@example.com",
    "phone": "+13125550142",
    "opted_out": false,
    "created_at": "2026-10-06T16:42:18Z",
    "additional_info": {
      "current_carrier": "Example Mutual",
      "vehicles": "2"
    },
    "referral": {}
  }
}

404 Not Found

JSON 
{
  "errors": [
    "Contact not found."
  ]
}

Agents

Coming soon.

Conversions

The outcomes you count: Quoted, Sold and any custom conversions you add. Record one when a contact reaches it.

List conversions

View as Markdown

GET /api/v3/conversions

Returns every conversion your account tracks. Each account starts with Quoted and Sold, and any custom conversions you’ve added are listed too. Conversion IDs never change, so look them up once and keep them in your integration’s settings.

Request

cURL 
curl https://hiremav.com/api/v3/conversions \
  -H "Authorization: Bearer $MAV_API_KEY"

200 OK

JSON 
{
  "conversions": [
    {
      "id": "cnv_4TzW8bQe2YcJ6s",
      "title": "Quoted",
      "value": 0,
      "created_at": "2026-06-02T14:11:09Z"
    },
    {
      "id": "cnv_9pLx3VnR7aKd2M",
      "title": "Sold",
      "value": 0,
      "created_at": "2026-06-02T14:11:09Z"
    }
  ]
}

Record a conversion

View as Markdown

POST /api/v3/conversions/{conversion_id}/events

Records that the contact reached this conversion. Mav adds it to the contact’s timeline and marks them in the app. By default it also ends Mav’s open conversations with the contact, so Mav stops following up with someone who has already converted.

Parameters

conversion_id

string, path · required

The conversion’s id, from List conversions.
conversion_contact.contact_id

string · required

The contact’s id, from Find a contact.
conversion_contact.converted_at

ISO 8601 timestamp

When the conversion happened. Defaults to when Mav receives the request.
conversion_contact.custom_value

integer, cents

What it was worth, in cents: 184000 is $1,840.00. Zero or more. Defaults to the conversion’s own value.

Request

cURL 
curl -X POST https://hiremav.com/api/v3/conversions/cnv_9pLx3VnR7aKd2M/events \
  -H "Authorization: Bearer $MAV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversion_contact": {
      "contact_id": "nct_7Hq2xKpR9vLm3N",
      "converted_at": "2026-10-08T17:30:00Z",
      "custom_value": 184000
    }
  }'

201 Created

JSON 
{
  "conversion_contact": {
    "id": "6705b2c1e4f0a2c3d4e5f601",
    "contact_id": "nct_7Hq2xKpR9vLm3N",
    "converted_at": "2026-10-08T17:30:00Z",
    "value": 184000,
    "conversion_id": "cnv_9pLx3VnR7aKd2M"
  }
}

Safe to retry. Recording the same conversion for the same contact again returns the original record with 200 OK, unchanged, so nothing is ever counted twice.

Full example

View as Markdown

The whole flow in Node.js 18 or later: look up Sold once, then record a sale whenever a policy binds on your side.

Record a sale

JavaScript 
const MAV = "https://hiremav.com/api/v3";
const headers = {
  Authorization: `Bearer ${process.env.MAV_API_KEY}`,
  "Content-Type": "application/json",
};

// Once, at setup: find the conversion you want to record.
const { conversions } = await fetch(`${MAV}/conversions`, { headers }).then((r) => r.json());
const sold = conversions.find((c) => c.title === "Sold");

// Each time a policy binds in your system:
async function recordSale(phone, premiumInCents) {
  const found = await fetch(`${MAV}/contacts/find?phone=${encodeURIComponent(phone)}`, { headers });
  if (found.status === 404) return; // Not a contact Mav has worked.

  const { contact } = await found.json();

  await fetch(`${MAV}/conversions/${sold.id}/events`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      conversion_contact: {
        contact_id: contact.id,
        converted_at: new Date().toISOString(),
        custom_value: premiumInCents,
      },
    }),
  });
}

Errors

View as Markdown

Mav answers with a standard HTTP status and, in most cases, an errors list saying what went wrong.

  • 400 Bad Request

    A required parameter is missing, or the body isn’t valid JSON.

    {"errors":["param is missing or the value is empty or invalid: phone"]}

  • 403 Forbidden

    The API key is missing or wrong, or your account isn’t on the current Mav app yet (Account is not enabled for Next.).

    {"errors":["API key is not authorized."]}

  • 404 Not Found

    The contact or conversion isn’t in your account. Lookups by ID answer with a message instead of an errors list.

    {"errors":["Contact not found."]}

  • 422 Unprocessable Content

    The conversion couldn’t be saved, like a negative custom_value.

    {"errors":["Custom value must be greater than or equal to 0"]}

Good to know

View as Markdown
  • Money is in cents. value and custom_value are whole numbers of cents: 184000 is $1,840.00.
  • Timestamps are ISO 8601, like 2026-10-08T17:30:00Z, both ways.
  • IDs are strings. Contact IDs start with nct_ and conversion IDs with cnv_. Store them as given.
  • A key sees one account. Contacts and conversions from any other account answer 404.
  • Retries are safe. Recording a conversion twice returns the first record instead of making a second.

Need your API key or a hand with an integration? Talk to us.

Plug Mav into your stack.

See how Mav works every lead and hands the wins back to your systems.