Lead API

Create or update contacts from any source.

The Lead API (also called the Form Capture API) creates a contact in Aloware, or updates one that already exists. Use it to push leads from your own forms, apps or systems straight into Aloware's lead management.

Where to find it: Integrations > Lead API in Aloware
Method: POST
Auth: your account API token, sent in the body as api_token
Format: JSON in, JSON out
Required: api_token and phone_number; everything else is optional

Endpoint

One endpoint handles both creating and updating:

POST /api/v1/webhook/forms

Fields

Required

api_token	Your Aloware account API token.
phone_number	The phone number of the contact.

Full URL

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

Request body

Send JSON. The example below lists the standard fields, each marked required or optional. Swap the sample values for your own data.

{
    "api_token": "[API_TOKEN]", // 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.io", // 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
    "is_dnc": false // Optional | Should we mark the contact as DNC (Do    
     Not Contact)
}

Headers

Send these with every request:

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

Responses

201: created

A new contact was made, and you get a success message.

{
  "message": "Contact created."
}

200: updated

An existing contact was updated. You only get this when "force_update" is true.

Pay attention to force_update. If it isn't "true", Aloware leaves any field that already has a value on the existing contact as it is.

{
  "message": "Contact updated."
}

422: invalid request

A parameter was missing or invalid. The body names the problem, for example:

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

cURL example

Create or update a contact from the command line:

curl --location --request POST 'https://app.aloware.io/api/v1/webhook/forms' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "api_token": "[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.io",
    "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"
    "is_dnc": false
}'

Postman

To test in Postman, import our sample collection: Lead API collection for Postman.

What else you can do with a lead

Beyond the contact's details, the same request can handle ownership, distribution, the PowerDialer, sequences and related records. You can give the lead an owner, send it to an inbox, put it in the PowerDialer, enroll it in a sequence, and attach tags and a disposition status.

To set the owner by email instead of by ID, send user_email with the user's email address. Send either user_id or user_email, not both.

Need another endpoint?

For other API functions or any questions, email support@aloware.com and tell us what you need.

Need a hand?

Our support team can help you set this up.

Contact support