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": "[email protected]", // 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": "[email protected]",
"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 [email protected]. We will be happy to assist you with your specific requirements.