Importing leads


The Saleswhale Import API lets you add individual leads into the Saleswhale platform and initiate automated conversations on them.


Import Leads

This endpoint accepts a POST request with the details of the lead that you want to import.


HTTP Request



The POST request body should be formatted as JSON, refer to the following:

// POST to
// Remember to pass in your API key as a token parameter in the JSON body!

    "lead": {
        "email" : "",
        "job_title": "Captain",
        "account_name": "Saleswhale",
        "number": "+1 541 000 0011011",
          "custom_attribute_1": "custom_attribute_value"    
    "campaign_id": "i-am-a-campaign-id"



You can pass the following parameters along when importing a lead:

Note: Bracket notation (e.g. lead[email]) indicates that a property is one level deep inside a hash.

Parameter Type Required
lead[first_name] string Yes
lead[email] string Yes
lead[last_name] string No
lead[job_title] string No
lead[account_name]      string No
lead[number] string No
campaign_id string Yes
token string Yes
lead[<custom_attribute>] string No



You can give Saleswhale a webhook URL you want to be called when a lead has finished processing.

You can set up a webhook URL endpoint from your Account Settings; hover over your initials and select "Account Settings."




Note: If you return anything other than a HTTP 200 status to the webhook POST, we will try to deliver the webhook up to 4 times with an exponential backoff.


Request POST Body

Once an event is triggered, the following attributes are sent in the webhook POST request to the URL provided when the webhook was set up in your account settings. 

Attribute Type Description
event_name string Name of event that triggers the webhook request to your provided URL
event_time string Timestamp created when webhook is triggered
event_payload hash Result object, with the encoded Lead object including status, email, and other attributes defined by the end user


The incoming webhook POST request's body should be formatted as JSON, refer to the following:

      'event_name': 'lead_outcome',
      'event_time': '2017-05-19T12:11:03.321+08:00',
      'event_payload': {
      'lead' : {
      'first_name': 'Maeve',
      'last_name': 'Millay',
      'status': 'qualified',
      'email': '',
      'confirmed_number__c': '921314120',
      'scheduled_time__c': 'May the 4th, 3pm',
      'last_interacted_at': '2017-05-22T09:53:51.538Z',
      'handover_rep_email': '',
      'handover_rep_name': 'Dolores Ng',
      'handover_email_subject': 'RE: Interested in joining?',
      'handover_email_snippet': 'Yes, how do I sign up?'


Security Webhooks

To validate a webhook came from Saleswhale we suggest verifying the webhook payloads using the signature and timestamp parameters (which we pass with every webhook).

Params Description
signature A SHA256 HMAC hex digest computed with your API key, the raw body of the request, and the provided timestamp parameter int eh request.
event_time Timestamp created when the webhook request is sent to your provided URL.


Verifying a Saleswhale Signature

To verify a Saleswhale signature, compute a SHA256 HMAC hexdigest of your own using your Saleswhale API key together with the timestamp parameter and the webhook request body.

Refer to the following sample ruby code:

signature = OpenSSL::HMAC.hexdigest('sha256'), your_api_key, "#{timestamp}.#{body}" )

Make sure to add a period punctuation mark when concatenating the timestamp parameter with the raw body of the webhook request.

Compare your generated signature against the signature provided with our webhook POST request. The two signatures should be identical.

2 out of 2 found this helpful



Article is closed for comments.