Lead Intake Webhook and API

Aloware’s Lead Intake API (and webhook) is a publicly available API endpoint that can receive 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 along with your account’s token (API Key) by going to the Integrations menu and clicking on the “Lead API” tab. 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.aloware.com/api/v1/webhook/forms' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "api_token": "YOUR_API_TOKEN",
    "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",
    "automation_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 automations, or pushing a lead to someone's power dialer). Using this API you can also programmatically manage contact ownership by your users.

{
    // Authentication Token
    "api_token": "CC42FF74", // Required
    // Lead Properties
    "phone_number": "8181234567", // Required
    "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?
    // Automation
    "automation_id": "4567", // Optional | Automation
    "force_update_automation": false, // Optional | Should we disenroll this lead from other automations, 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.
  • [first_name] [last_name] Contact identifiers, 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.
  • [notes] Customer details on the Notes section of Aloware contacts. Use this field to capture your contact’s consent to electronic communications.
  • [source] A custom source field to segment the contacts later. optional.

Distribute Contact ACTION

  • distribute_to_right_group (true or false)
  • ring_group_id
  • check_available_users (true or false)

Description: 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 user, distribution will be skipped.


Add to PowerDialer ACTION

  • add_to_powerdialer (true or false)
  • powerdialer_position (top or bottom)

Description: Determine if the contact should be added to the contact owner’s PowerDialer. `powerdialer_position` is top or bottom. The default position is top. 

What are the responses?

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.

   # Returns an HTTP 202 response on success, Example success response: {     "message": "Contact created." }  # Returns an HTTP 400 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."         ]     } }

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.

Still need help? Contact Us Contact Us