Table of Contents


Overview

Aloware’s Lead Intake API (and webhook) is a publicly available API endpoint that can receive a lead and prospect data from other applications, forms, and services and add them as Contacts to your account.

You can use Aloware Contacts as a data warehouse for your leads, segment them via tags or campaigns, or search for leads with specific attributes. Lead intake can also be configured for SMS automation, like sending an SMS to the lead when they submit a form.


Where is the API documentation?

You can view your API docs in your Aloware account, along with your account’s token (API Key).

  • Go to the Integrations tab, click Lead API

    📝 Note - The API key is unique to your user account on Aloware, meaning other Admin users have their own keys.


Is there an example I can use?

Yes. A cURL example is copied below. Please contact us if you need assistance with implementation.

curl --location --request POST 'https://app.alodev.org/api/v1/webhook/forms' \ 
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
"api_token": "31B1B33D",
"phone_number": "8181234567",
"company_name": "Aloware",
"name": "John Doe",
"first_name": "John",
"last_name": "Doe",
"lead_source": "Google Ads",
"email": "john.doe@gmail.com",
"date_of_birth": "MM/DD/YYYY",
"timezone": "America/Los_Angeles",
"city": "Los Angeles", "state": "CA",
"zipcode": "90045",
"country": "US",
"address": "1234 First Street",
"website": "https://www.aloware.com",
"notes": "This is a test note",
"csf1": "Custom data",
"csf2": "Custom data",
"force_update": true,
"force_update_sequence": false,
"distribute_to_ring_group": true,
"ring_group_id": "1234",
"check_available_users": true,
"add_to_powerdialer": true,
"powerdialer_position": "bottom",
"line_id": "1234",
"sequence_id": "4567",
"user_id": "1234",
"tag_id": "1234",
"disposition_status_id": "1234"
}'


What are the possible fields I can send over?

As of Oct 2020, these are the fields you can send to Aloware Lead API. Note that some fields are data pieces, and some instruct Aloware to perform certain actions (like enrolling a lead into automation or pushing a lead to someone's power dialer). Using this API you can also programmatically manage contact ownership by your users.

The code sample below represents some example JSON with standard fields to pass in the body of your request in order to create a new contact:

{ 
// Authentication Token "api_token": "31B1B33D", // Required // Lead Properties
"phone_number": "8181234567", // Required
"other_phone_numbers": [{"label":"mobile", "phone_number": "8181234567"}, ...], // Optional | Array of objects/arrays that includes the following keys; phone_number (required), label (optional)
"company_name": "", // Optional
"name": "John Doe", // Optional
"first_name": "John", // Optional
"last_name": "Doe", // Optional
"lead_source": "Google Ads", // Optional
"email": "john.doe@gmail.com", // Optional
"date_of_birth": "MM/DD/YYYY", // Optional
"timezone": "America/Los_Angeles", // Optional
"city": "Los Angeles", // Optional
"state": "CA", // Optional
"zipcode": "90045", // Optional
"country": "US", // Optional
"address": "1234 First Street", // Optional
"website": "https://www.aloware.com", // Optional
"notes": "This is a test note", // Optional
"csf1": "Custom data", // Optional | (Custom Field 1)
"csf2": "Custom data", // Optional | (Custom Field 2)
// Ownership
"user_id": "1234", // Optional | Set an owner for this lead. If left blank, the contact will not be owned by any user.
// Distribution
"distribute_to_ring_group": true, // Optional | Should we distribute the contact to a ring group? If true, we will randomly assign it to an agent/user within a ring group and override `user_id` in ownership.
"ring_group_id": "5", // Optional | Will be checked if `distribute_to_ring_group` is TRUE.
"check_available_users": true, // Optional | Will be checked if `distribute_to_ring_group` is TRUE. | Should we check if user is eligible or active? if value is true and no active user found, contact will not be distributed within a ring group.
// PowerDialer "add_to_powerdialer": true, // Optional | Should we add the contact to the PowerDialer of agent/user where it is distributed? If the lead is already in someone’s PowerDialer, it will be skipped.
"powerdialer_position": "top", // Optional | Options: top, bottom | Default: top | Will be checked if `add_to_powerdialer` is TRUE. | Combined with the option above, should this lead go to the top of the PowerDialer or bottom?
// Sequences "sequence_id": "4567", // Optional | Sequences
"force_update_sequence": false, // Optional | Should we disenroll this lead from other sequences, and push them to a new one?
// Action Flags "force_update": true, // Optional | Should we override existing data and update the contact information?
// Relationship Fields "line_id": "1234", // Optional | Line
"tag_id": "1234", // Optional | Tag
"disposition_status_id": "1234", // Optional | Disposition Status
}

Below is a description of the intake fields supported by our Intake Webhook:

  • [campaign_id] - Aloware campaign id (from campaign’s page) that this lead needs to be attached to. This field is required.

  • [phone_number] - The lead’s phone number, in any format +1 818-740-5020, +1 818-740-5020, +1 818-740-5020, etc). This field is required.

  • [company name] - Contact's company affiliated to, optional.

  • [name] [first_name] [last_name] - Contact identifiers, optional.

  • [lead source] - A custom source field to segment the contacts later, optional.

  • [source] - A custom source field to segment the contacts later. optional.

  • [email] - Contact identifier for CRM integrations, optional.

  • [date_of_birth] - Contact’s birthday, in US format (12/05/1975 or 12-05-1975) for birthday campaigns, optional.

  • [timezone] - Contact’s timezone for scheduling purposes, optional.

  • [city], [state], [zipcode], [country] - Contact’s geographical location for segmentation, optional. If blank these values will be determined from the phone number.

  • [address] - Contact's location, optional.

  • [website] - A custom field for the contact's business website, optional.

  • [notes] - Customer details on the Notes section of Aloware contacts. Use this field to capture your contact’s consent to electronic communications.

  • [csf1] [csf2] - Contact's custom data

  • Ownership - You can set a contact owner for a lead. If left blank, the contact will not be owned by any user, optional.

    • [user_id]

  • Distribute Contact ACTION - Determine if the contact should be added to a ring group. If it is, it will be distributed to a random user within the ring group. If `check_available_users` is true, the system will check for eligible users, if there are no eligible users, distribution will be skipped.

    • distribute_to_right_group (true or false)

    • ring_group_id

    • check_available_users (true or false)

  • Add to PowerDialer ACTION - Determine if the contact should be added to the contact owner’s PowerDialer. `powerdialer_position` is top or bottom. The default position is top.

    • add_to_powerdialer (true or false)

    • powerdialer_position (top or bottom)

  • Add to Sequences ACTION - Determine if the contact should be disenrolled from other sequences, and push them to a new one.

    • sequence_id

    • force_update_sequence (true or false)

  • Action Flags ACTION - Determine if Aloware should override contact's existing data and update the contact information.

    • force_update (true or false)

  • Relationship Fields ACTION - Determine the line, tags, and disposition of the contact.

    • line_id

    • tag_id

    • disposition_id


What are the Responses?

  • HTTP 200

    Aloware returns an HTTP 200 on contact update if force_update is true. Example success response:

    {
    "message":"Contact updated.}
    }
  • HTTP 201

    Aloware returns a response, HTTP 201 on a successful contact creation. Example success response:

    {
    "message":"Contact created."
    }
  • HTTP 202

    Aloware returns an HTTP 202 “Created” response on a successful call. Aloware returns the same status for duplicate contacts since we handle duplicate entry removal on our backend.

    {
    "message":"Contact created."
    }
  • HTTP 400

    Aloware returns HTTP 400 response on failure with a detailed response. Example failure response:

    { 
    "message": "The given data was invalid.", "errors":
    { "phone_number": [ "The phone number has already been taken." ]
    }
    }
  • HTTP 429

    You can send 1000 requests per minute on this particular endpoint. If you send more than the throttling limits, you will get this error with the exact time you need to wait before sending the next.


What should I do if I need to push custom data attributes, tags, or a large volume of data to Aloware?

If you need more API functions, please contact our support. We are happy to help.

Did this answer your question?