# Outbound webhooks and the API

Push events from Mav to your systems with a lead box, and read or write contacts and conversions through the API.

## Lead boxes: Mav tells your systems

A lead box sends an event to you every time something happens to a contact. Add one under **Settings › Lead Boxes**, or from an agent's **Outbound Notifications** section.

- **Agents**: all agents, including ones added later, or specific ones.
- **Events**: tick the ones you want, or leave all unticked to get every event. Events include Started, Interested, Reengagement Sent, Opted Out, Undeliverable, Qualified, Quoted, Sold, Custom Conversion, Link Clicked and the phone call events (scheduled, started, connected, transferred, completed, missed).
- **Delivery**: a **Webhook** (POST, as JSON or a form, with an optional Bearer token) or an **Email** to one address.

Click **Send test** to post one sample event for a fictional contact right away. The payload carries `activity.properties.test: true` and nothing is saved.

### Delivery rules

Mav waits 3 seconds to connect and 3 more for your answer, so reply `200` first and do the work after. Any `2xx` counts. Redirects are not followed. A failed delivery is retried up to 18 times over about four days. If the last retry fails, the lead box is turned off and your account's admins and managers get an email. See [A webhook was turned off](/knowledge/troubleshooting/a-webhook-was-turned-off).

A retry can deliver the same event twice. Dedupe on the contact id, the event label and its timestamp.

## The API: your systems tell Mav

The API at `https://hiremav.com/api/v3` lets your rater, agency management system or CRM look up contacts and record conversions. Ask your Mav team for an API key and send it as `Authorization: Bearer YOUR_API_KEY`.

| Call | What it does |
|---|---|
| `GET /contacts/find?phone=` | Find a contact by phone, in any US format. |
| `GET /contacts/{id}` | One contact, with the properties your vendor sent. |
| `GET /conversions` | Your conversions: Quoted, Sold and any custom ones. |
| `POST /conversions/{id}/events` | Record a conversion for a contact, with an optional value in cents. |

Money is in cents, timestamps are ISO 8601, and ids are strings that never change. A key sees one account only. Recording a conversion twice returns the first record, so retries are safe.

The full reference, with a request and response for every call, the webhook payload and every error, is at [hiremav.com/api](/api). Every section there is also served as Markdown for your own tools.