Aloware Lead API Documentation

Use Aloware's Lead API to create or update contacts with essential details. It offers customization and gives clear success or error responses. Contact Aloware for more features or help.

The Aloware Lead API, or Form Capture API, allows you to create new contacts or update existing contacts within Aloware.

This API enables you to seamlessly integrate Aloware's lead management functionality into your applications or systems.

This document provides details on how to use the API and its available endpoints which you can find in Integrations > Lead API.


Endpoint

The API endpoint for creating a new contact or updating an existing contact is:

POST /api/v1/webhook/forms

Query Parameters

The following query parameters are required to perform the contact lookup:

api_token

Your Aloware account API token.

phone_number

The phone number of the contact.

Example POST URL

https://app.aloware.com/api/v1/webhook/forms

Request Body

The request body should be in JSON format and include the required fields to create or update a contact. The following example demonstrates a JSON payload with standard fields: 

{
"api_token": "740A6C4E", // Required
"phone_number": "8181234567", // Required
"other_phone_numbers": [{"label":"mobile", "phone_number": "8181234567"}, ...], // 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)
"user_id": "1234", // Optional
"distribute_to_ring_group": true, // Optional
"ring_group_id": "5", // Optional
"check_available_users": true, // Optional
"check_available_users_with_fallback": true, // Optional
"add_to_powerdialer": true, // Optional
"powerdialer_position": "top", // Optional
"sequence_id": "4567", // Optional
"force_update_sequence": false, // Optional
"force_update": true, // Optional
"line_id": "1234", // Optional
"tag_id": "1234", // Optional
"disposition_status_id": "1234" // Optional
}

Please replace the example values with the actual data you want to create or update.


Headers

Include the following headers in your API request:

Accept: application/json
Content-Type: application/json

Response and Error Handling

The API will return the following responses based on the success or failure of the contact creation or update:

  • HTTP 201 - If the contact is successfully created, an HTTP 201 response will be returned with a success message.

{
"message": "Contact created."
}
  • HTTP 200 - If the contact is successfully updated and the "force_update" field is set to true, an HTTP 200 response will be returned with a success message.

The "force_update" field is a crucial parameter in the Aloware Lead API. It's essential to understand that unless it is set to "true," existing contacts will not be updated if the corresponding contact field is already filled.

{
"message": "Contact updated."
}
  • HTTP 400 - If the request fails due to invalid or missing parameters, an HTTP 400 response will be returned. The response body will provide a detailed error message indicating the cause of the failure. Example failure response:

{
"message": "The given data was invalid.",
"errors": {
"message": [
"The message field is required."
]
}
}


cURL Example - Create or update a contact

Here is an example cURL command to create or update a contact using the Aloware Lead API:

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": "740A6C4E",
"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"
}'

Postman Example

If you prefer using Postman, you can import the example collection provided at this link: Aloware Lead API Postman Collection.


Additional Information

The Lead API provides additional options for ownership, distribution, PowerDialer integration, sequences, and relationship fields. You can set an owner for the lead, distribute it to a ring group, add it to PowerDialer, enroll it in sequences, and assign tags and disposition statuses.


Additional API Functions

If you require more API functions or have any questions, please feel free to contact our support team at support@aloware.com. We will be happy to assist you with your specific requirements.