Overview of API
Sam Liu avatar
Written by Sam Liu
Updated over a week ago

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:

  • Create a lead

  • Enroll a lead

  • Retrieve a conversation

  • Delete a lead

  • Cancel a conversation

  • Restrictions of API v2

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

Create a lead

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.

Enroll a lead

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:

  • still has an ongoing conversation

  • has been enrolled in the same topic in the past

  • has been enrolled in the same campaign in the past

Retrieve a conversation

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 :

  • Ongoing conversation statuses : Pending lead response, Pending bot response

  • Completed conversation statuses : Bounced, Human Review, Not Interested, Qualified, Stopped Responding, Unresponsive, Cancelled

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:

  • If the Human Review Owner marks a human review task as 'Completed', the status can change from 'Human Review' to 'Qualified', 'Stopped Responding', 'Cancelled' or 'Not Interested'.

  • If a lead subsequently responds after the final email has already gone out, the status can change from 'Unresponsive' or 'Stopped Responding' to other statuses.

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.

Delete a lead

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:

  • Soft-deleting a lead/all leads will not delete the conversation

  • Hard deleting a lead will not delete the conversation, but hard deleting all leads will delete the conversation

Cancel a conversation

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.

Restrictions of API v2

Currently, our API does not allow:

  • Update a lead

  • Hard delete a lead

  • Return emails in a conversation object

  • Create multiple leads at once

  • Enroll multiple leads at once

  • Cancel multiple conversations at once

  • Delete multiple leads at once

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.

Did this answer your question?