For users who would like to integrate Saleswhale with a non-Salesforce CRM, or configure a custom workflow between Saleswhale and your existing systems, you can do so with our API.

In this guide, we will cover:

There are also other API endpoints and webhook available. You can refer to our API v2 documentation here.

The lead is created in Saleswhale, but is not enrolled into any campaigns. No email is sent to the lead at this point.

After a new lead is created in Saleswhale, you can find the lead under the Leads tab.

To create a new lead, please refer to the documentation here.

Create a lead with a lead owner

To create a lead with a lead owner, please first make sure that the lead owner is defined as a handoff rep in the app. We will only accept lead owners who are pre-populated in the app as a handoff rep. Otherwise, the lead owner will be discarded and the lead will be handed over on a round robin basis in the event of a qualification.

To populate your `lead_owner` object in your POST request, you will need to retrieve all sales reps, do a search & match on your end based on the rep's email address to retrieve the lead owner id. You can then submit this in with your POST request.

Create a lead with custom attributes

To create a lead with custom attributes, please first make sure that the custom attribute is created in the app.

To populate your `custom_attribute_value` object in your POST request, you will need to retrieve all custom attributes, do a search & match on your end based on the attribute name to retrieve the custom attribute id. You can then submit this in with your POST request.

The lead is enrolled to a campaign in Saleswhale, and a conversation will be started on the lead.

After a lead is enrolled, you can find the lead under the Leads tab or Campaign Details page.

To enroll a lead, please refer to the documentation here.

Submit an enrollment

To enroll a lead, you will need to:

Enrollment restrictions

A lead cannot be enrolled if it:

To retrieve a conversation, please refer to the documentation here.

Conversation statuses

A conversation can either be ongoing or completed. This is determined by the status on the conversation. This is reflected under `conversation.status` in your GET request response :

When a conversation is completed, it will have a 'terminal' conversation status. These statuses are representative of the final state of the conversation, with a couple of exceptions:

Multiple leads in a conversation

In a conversation where your lead refers the bot to their colleague, or CCs in other people, there will be multiple leads in a conversation.

All leads within a conversation will have the same conversation status, as the status belongs to the conversation and not the individual leads.

To know who are the leads involved,`leads` is an array in the response which returns all leads in the conversation in no particular order.

`is_main` refers to the main lead when the conversation is completed, which is assumed to be the last person who replied the bot. If marked as true, this lead is the 'To' recipient. If false, this lead is either a 'CC' or 'BCC' recipient.

`is_original` refers to the lead we first started the conversation on.

To delete a lead, please refer to the documentation here.

Please take note that our delete endpoint is for soft delete. Soft delete archives the lead in the app, and the lead profile is no longer accessible. The conversation will still be present. When you create the lead again, the previous copy of the lead will be restored.
​
By default, the API prevents you from deleting a lead that has an ongoing conversation. You can override this behaviour (delete the Lead and cancel his/her ongoing conversation) by including the `force` property in the JSON body.

Hard delete a lead

If you are testing the import/enrollment endpoints and need to start from a clean slate, you will need to hard delete the lead.

Hard delete permanently deletes the lead from our database. All conversation and lead details will be irreversibly lost, and stats attributed to it will be reverted.

Hard delete is currently not available over API or within the app. To do so, please contact your customer success representative or open a support ticket with support [at] saleswhale.com. Alternatively, you can test the endpoints on the same email multiple times like this: example+1@company.com, example+2@company.com

Multiple leads in a conversation

If you delete a lead in a conversation with multiple leads:

To cancel a conversation, please refer to the documentation here.

A lead is not allowed to have more than one ongoing conversation at once.

Once you cancel a conversation, the conversation status will be marked as `Cancelled` in the app and the lead is now available to enroll in a new conversation.

Currently, our API does not allow:

If you have any feedback on our API and how to improve it, we would love to hear from you. You can submit your product feedback at feedback [at] saleswhale.com.