# Mav API documentation

Base URL: `https://hiremav.com/api/v3`

## Overview

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. **List conversions** once, at setup, and keep the `id` of each one you’ll record.
2. **Find the contact** by phone number when someone quotes or buys on your side.
3. **Record the conversion** against that contact.

## Authentication

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.

```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

`GET https://hiremav.com/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

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

#### Response: 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": {}
  }
}
```

#### Response: 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

`GET https://hiremav.com/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

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

#### Response: 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

`POST https://hiremav.com/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

```sh
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
    }
  }'
```

#### Response: 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

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

```js
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

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. Example: `{"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.`). Example: `{"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. Example: `{"errors":["Contact not found."]}`
- **422 Unprocessable Content**: The conversion couldn’t be saved, like a negative `custom_value`. Example: `{"errors":["Custom value must be greater than or equal to 0"]}`

## Good to know

- **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.