If you would like to integrate with a non-Salesforce CRM, or configure a custom workflow between Conversational Email and your existing systems, you can do so with our API.
For the latest version of our API documents, refer to the API documentation.
This guides covers:
Creating a lead
Enrolling a lead
Retrieving a conversation
Deleting a lead
Canceling a conversation
Restrictions of API v2
There are also other API endpoints and webhooks available. Refer to the API v2 documentation.
Create a lead
The lead is created in Conversational Email, but is not enrolled into any campaigns. No email is sent to the lead at this point.
After a new lead is created in Conversational Email, you can find the lead under the Leads tab.
To create a new lead, refer to Create a lead.
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 by searching & matching 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 by searching & matching 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 6sense Conversational Email, and a conversation will be started with the lead.
After a lead is enrolled, you can find the lead under the Leads tab or Campaign Details page.
To enroll a lead, refer to Create a lead.
Submit an enrollment
To enroll a lead, you will need to:
Make sure the lead is first created in the app. After it is created, you will retrieve the `lead` id from the response of your lead creation API call.
Make sure the campaign you wish to enroll to is first created in the app. You will need to retrieve all campaigns, do a search & match on your end based on the campaign name to retrieve the campaign id. You can then submit this in with your POST request.
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, refer to Show a conversation.
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 AI email agent 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 AI email agent 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.
`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 to the AI email agent. 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 original lead contacted.
Delete a lead
To delete a lead, refer to Delete a lead.
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 behavior (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 submit a support ticket using our support page. Alternatively, you can test the endpoints on the same email multiple times like this: [email protected],[email protected]
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 one lead will not delete the conversation, but hard deleting all leads will delete the conversation
Cancel a conversation
To cancel a conversation, refer to Cancel a conversation.
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, the API v2 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