How to use the Replavia leads API
Last updated
Plans: Free: not included · Pro: not included · Scale: included
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.
Open Integrations →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.
The API can only read leads. It cannot change or delete them.
Create an API key
- Open Lead Inbox in the menu, then the Integrations tab.
- On the API card, type a name for the key, like “Warehouse sync”.
- Click Create API key.
- 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_…
limit- What it does
- Leads per page. The default is 50 and the most is 200.
cursor- What it does
- Gets the next page. Use the
next_cursorvalue from the last reply.
status- What it does
- Only leads with this status: NEW, CONTACTED, CONVERTED, IGNORED or JUNK.
since- What it does
- Only leads that changed on or after this date and time.
| 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.
401
- Meaning
- The key is missing, wrong or revoked.
403
- Meaning
- Your account is no longer on the Scale plan.
429
- Meaning
- Too many requests. Wait a minute and try again.
400
- Meaning
- The
statusvalue is not one of the allowed ones.
| 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.
- For a one-off copy, Export CSV in Lead Inbox is easier. See How to export leads.