# How to use the Replavia leads API

> On the Scale plan, create an API key under Lead Inbox, then Integrations, and call GET /api/v1/leads with it. The API returns your captured leads, up to 200 a page, and is read-only.

- Topic: Integrations
- Plans: Free: not included · Pro: not included · Scale: included
- In the app: Open Integrations — https://app.replavia.com/contacts/integrations
- Last checked: 2026-10-29
- Web page: https://replavia.com/help/leads-api

## When to use it

The leads API lets your own software read your leads. It suits a data warehouse, a nightly copy or a custom dashboard.

If you want each lead the moment it arrives, a webhook is simpler. See [How to send leads to Zapier, Make or your own server](https://replavia.com/help/zapier-make-and-webhooks).

The API can only read leads. It cannot change or delete them.

## Create an API key

1. Open **Lead Inbox** in the menu, then the **Integrations** tab.
2. On the **API** card, type a name for the key, like “Warehouse sync”.
3. Click **Create API key**.
4. Copy the key at once. It is shown only one time. Replavia keeps only a scrambled copy, so it cannot show it again.

Keys start with `mdf_live_`. You can have up to five active keys. Treat each one like a password: anyone who has it can read all your leads.

## Make a request

Send the key in the `Authorization` header:

`GET https://app.replavia.com/api/v1/leads`

`Authorization: Bearer mdf_live_…`

| Option | What it does |
|---|---|
| `limit` | Leads per page. The default is 50 and the most is 200. |
| `cursor` | Gets the next page. Use the `next_cursor` value from the last reply. |
| `status` | Only leads with this status: NEW, CONTACTED, CONVERTED, IGNORED or JUNK. |
| `since` | Only leads that changed on or after this date and time. |

Leads come newest first. When `has_more` is true, call again with `cursor` set to `next_cursor`.

## What each lead holds

Each lead has its `id`, `username`, `email`, `phone`, `source`, `account`, `status`, `subscribed`, `note`, `tags`, `capturedAt` and `updatedAt`.

The `id` is Replavia’s own lead id. The person’s Instagram user id is never included. Leads that were deleted, or whose data was erased, are not returned.

## Limits and errors

You can make 120 requests a minute with each key.

| Reply | Meaning |
|---|---|
| 401 | The key is missing, wrong or revoked. |
| 403 | Your account is no longer on the Scale plan. |
| 429 | Too many requests. Wait a minute and try again. |
| 400 | The `status` value is not one of the allowed ones. |

## Revoke a key

Click **Revoke** next to the key. It stops working at once. After that, **Remove** takes it off the list.

## Good to know

- The API is on the **Scale** plan. A key stops working if you leave Scale.
- Full details and examples are at [replavia.com/integrations](https://replavia.com/integrations).
- For a one-off copy, **Export CSV** in **Lead Inbox** is easier. See [How to export leads](https://replavia.com/help/export-and-sync-leads).