> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salesfinity.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Call new leads within minutes
> Send email replies, form fills and bookings to Salesfinity as hot leads, so the rep dialing that list calls them next.
Someone replies "call me", fills in your demo form or books a meeting. The sooner a rep calls, the
likelier that person picks up and still remembers why. **Speed to lead** in Salesfinity means your
automation adds that person to a list with a **tag**, such as `"Hot lead"`, and the rep dialing that
list calls them next, without stopping the call they're on.
## How it works
```mermaid theme={"system"}
flowchart LR
A["A lead raises their hand
reply · form · booking"] --> B["Your automation
Zapier, Make or your code"]
B -->|"Add a contact, with a tag"| C["Top of the list
and of its dialing queue"]
C --> D{"Is the list's owner
dialing this list?"}
D -->|Yes| E["Their next call, right
after the current one"]
D -->|No| F["A notification with
Call now and Open list"]
```
1. Something happens in a tool you already use: a reply in your email tool, a new lead from a
Facebook lead form, a booking, a form on your website.
2. Your automation sends that person to Salesfinity with
[Add a contact to a list](https://docs.salesfinity.ai/api-reference/endpoint/add-contact.md#call-a-contact-next) and a `tag`.
3. The person goes to the top of the list. If the list's owner is dialing that list, they're the
next call. If not, the owner gets a notification and the person is first when they press Start.
Recipes for each source, from email replies to lead ads and CRM leads, are in
[Workflows](https://docs.salesfinity.ai/workflows/overview.md).
## Set it up
**1. Pick the list hot leads go to**
Hot leads go into a list the rep dials, such as **Inbound leads**. The list's owner is the rep
who calls them and gets the notifications.
* Create it in the dialer by uploading a CSV (one row is enough), or with
[Create a contact list](https://docs.salesfinity.ai/api-reference/endpoint/create-list.md) and the rep's `user_id`.
* Note the list's ID: it's the `_id` from
[List contact lists](https://docs.salesfinity.ai/api-reference/endpoint/get-contact-lists-csv.md), not its `contact_list_id`.
> [!TIP]
>
> Several reps on inbound? Give each rep their own list, and have your automation send each lead
> to the right one, for example by territory or in turns.
**2. Get an API key**
In Salesfinity, open
[Settings → Connections](https://web.salesfinity.co/dashboard/settings?tab=connections), then the
**API & Webhooks** tab, and click **Create New API Key**. Keep it secret: it works for your whole
team. See [Developers](https://docs.salesfinity.ai/developers.md) for more.
**3. Send each hot lead with a tag**
For every new hot lead, your automation sends one request. Put what happened in `notes`, so the
rep knows why they're calling, and pick a tag per source so reps can tell them apart:
`"Hot lead"`, `"Replied"`, `"Facebook lead"`, `"Booked a call"`. A tag is 24 characters at most.
Send phone numbers in international format, such as `+17205550148`.
```bash cURL theme={"system"}
curl https://client-api.salesfinity.co/v1/contact-lists/YOUR_LIST_ID \
--request POST \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"first_name": "Dana",
"last_name": "Ortiz",
"email": "dana.ortiz@fernway.com",
"company": "Fernway Logistics",
"title": "VP Operations",
"phone_numbers": [{ "type": "mobile", "number": "+17205550148" }],
"notes": "Replied: \"Sure, call me this afternoon\"",
"tag": "Hot lead"
}'
```
```text Zapier theme={"system"}
1. Trigger: the event in your tool, such as an interested reply in your
email tool, a new lead in Facebook Lead Ads, a new booking in your
scheduling tool, or a new form submission.
2. Optional: Formatter → Numbers → Format Phone Number, to E.164
(+17205550148).
3. Action: Webhooks by Zapier → Custom Request
Method: POST
URL: https://client-api.salesfinity.co/v1/contact-lists/YOUR_LIST_ID
Headers: x-api-key YOUR_API_KEY
Content-Type application/json
Data: the JSON from the cURL tab, with the trigger's fields
mapped into it, and your tag.
```
```text Make theme={"system"}
1. Trigger: the module for your tool's event (a reply, a lead form,
a booking, a form submission).
2. Action: HTTP → Make a request
URL: https://client-api.salesfinity.co/v1/contact-lists/YOUR_LIST_ID
Method: POST
Headers: x-api-key = YOUR_API_KEY
Body content type: application/JSON
Body input method: JSON string
Body: the JSON from the cURL tab, with the trigger's
fields mapped into it, and your tag.
```
A successful request answers `201` with `{ "success": true }`.
**4. Dial the list**
The rep opens the **Dialer**, picks the list and starts dialing. That's all: every hot lead your
automation sends while they dial becomes their next call.
## What the rep sees
**While dialing that list**
* A notification: *Hot lead added: Dana Ortiz · Hot lead · Your next call, right after this one.*
* **Next up: Dana Ortiz** at the top of the dialer, and the tag on Dana's row at the top of the queue.
* When the current call is logged, Dana is dialed next, **on her own line**, so another person
picking up can't cut her off. Then the dialer goes back to its usual number of lines.
* On the call, the tag and the time it was added sit at the top of Dana's details, like
"Referred by" does for a referral, and your `notes` say why the rep is calling.
**While not dialing that list**
* A notification with **Call now**, which calls Dana right away, and **Open list**, which opens the
dialer on the list with Dana on top. It also shows up in the bell.
* When the rep presses Start, tagged contacts nobody has called yet are dialed first.
## Send only people who asked to talk
A tag means "call this person next", so keep it for people who raised their hand:
* **Email replies:** send interested replies, such as replies your email tool marks as interested or
a "call me". Leave out out-of-office replies, "not interested" and "remove me".
* **Forms and bookings:** make sure your form tells people you'll call them.
* **Everything else:** add it without a tag. It goes to the end of the list and reaches the dialing
queue at the next [reimport](https://docs.salesfinity.ai/api-reference/endpoint/reimport-contacts.md).
## Good to know
* **A conversation is never cut short.** A hot lead is called after the current call is logged. If
lines are only ringing, it goes right after them.
* **No duplicates.** If the list already holds the person (same email, or same phone number and
first name), that contact moves to the top and takes the tag. A shared office number alone doesn't
count. The same lead sent twice within a minute is called and announced once.
* **The usual dialing rules still apply.** A number marked do not call or as a wrong number is
skipped, and so is anyone outside the rep's working hours when the rep has that limit on. The
person then waits at the top of the list.
* **Many hot leads at once.** At the start of a session, up to 5 tagged in the last day go out on
their own line; the rest are dialed first, in the usual batches.
* **Tags stay.** A reimport keeps them, and
[Get a contact list](https://docs.salesfinity.ai/api-reference/endpoint/get-contact-list-by-id.md) returns `tag` and
`tagged_at`.
## Test it
1. Start dialing the list, with your phone ready.
2. Send yourself as a hot lead: run the cURL example with your own name and mobile number, and
`"tag": "Test"`.
3. Check that the notification shows, that **Next up** shows your name, and that once the current
call is logged, your phone rings.
## Troubleshooting
| What you see | Why | What to do |
| - | - | - |
| `400` | `tag` is over 24 characters, a field is misspelled, or the list ID is not an ID. `message` says which. | Shorten the tag or fix the field. |
| `404 Contact list not found` | The ID is not one of your team's lists, or it's the `contact_list_id`. | Use the list's `_id` from [List contact lists](https://docs.salesfinity.ai/api-reference/endpoint/get-contact-lists-csv.md). |
| Added, but no notification | The list's owner is no longer on your team, or the same lead was sent twice within a minute. | Move the list to an active rep, or check your automation for repeats. |
| A notification, but not called next | The rep is dialing another list, or the number is marked do not call or wrong, or it's outside the rep's working hours. | Send hot leads to the list the rep dials. The notification says why when the number can't be called. |
| Nothing at the top of the list | The request had no `tag`. | Add `tag` to the request. |
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.