NAV
shell

Introduction

Welcome to the Usealan API! You can use our API to access various API endpoints, which can get information about leads, appointments, messages and campaigns. Everything related to your business.

You can view code examples in the dark area to the right.

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here" \
  -H "Authorization: Bearer abcdefgh12345678"

Make sure to replace abcdefgh12345678 with your API key.

Usealan uses API keys to allow access to the API. You can view your API key in your admin portal.

Usealan expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer abcdefgh12345678

Users

End Users

curl "https://api.usealan.com/v1/end_users" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer abcdefgh12345678"

The above command returns JSON structured like this:

{
  "data": {
    "end_users": [
      {
        "id": "1001",
        "user_name": "john1",
        "user_code": "abcd1234",
        "first_name": "John",
        "last_name": "Doe",
        "full_name": "John Doe",
        "displayname": "John Doe",
        "email": "john@mail.com",
        "created_at": "2022-01-01 16:30:00"
      },
      {
        "id": "1002",
        "user_name": "james1",
        "user_code": "defg5678",
        "first_name": "James",
        "last_name": "Doe",
        "full_name": "James Doe",
        "displayname": "James Biz",
        "email": "james@mail.com",
        "created_at": "2022-02-02 13:00:00"
      }
    ]  
  },
  "code": 200,
  "message": "Successful operation."
}

Gets list of end users associated to current user.

HTTP Request

GET https://api.usealan.com/v1/end_users?q=<criteria>

Query Parameters

Parameter Description
q (Optional) Search parameter to attempt to match end users by name, user_name or email.

Leads

Leads List

curl "https://api.usealan.com/v1/leads" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer abcdefgh12345678"

The above command returns JSON structured like this:

{
  "data": {
    "leads": [
      {
        "id": "12345",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@mail.com",
        "phone": "1122334455",
        "source": "click_funnel",
        "status": "unchecked",
        "campaign": "Sales Consultation",
        "created_at": "2023-08-20 19:12:16",
        "schedule_date_time": "2023-08-30 19:00:00",
        "sms_initiated": "2023-08-21 04:01:45",
        "last_message_sent": "2023-09-03 11:22:22",
        "last_message_reply": "2023-09-02 08:01:45"
      },
      {
        "id": "12345",
        "first_name": "James",
        "last_name": "Doe",
        "email": "james.doe@mail.com",
        "phone": "6677889900",
        "source": "click_funnel",
        "status": "unchecked",
        "campaign": "Sales Consultation",
        "created_at": "2023-08-21 19:12:16",
        "schedule_date_time": "2023-09-01 19:00:00",
        "sms_initiated": "2023-08-22 04:01:45",
        "last_message_sent": "2023-09-04 11:22:22",
        "last_message_reply": "2023-09-02 10:01:45"
      }
    ],
    "page": 1,
    "per_page": 50,
    "total": 2,
    "pages": 0,
    "start_date": "2023-08-20 00:00:00",
    "end_date": "2023-09-20 23:59:59"
  },
  "code": 200,
  "message": "Successful operation."
}

Gets list of leads for a specific user ordered from first. If no date range is specified last month will be used as default.

HTTP Request

GET https://api.usealan.com/v1/leads/<user_id>?start_date=<date>&end_date=<date>&q=<criteria>

Query Parameters

Parameter Description
user_id ID of the end user.
start_date (Optional) YYYY-MM-DD Start date for query.
end_date (Optional) YYYY-MM-DD End date for query. It can't be less than the start date.
q (Optional) Search parameter to attempt to match leads by name, email or phone number.
size (Optional) Integer. Quantity of results returned. Default is 500. Maximum is 5000
page (Optional) Integer. The page parameter is used to specify the page number when retrieving paginated data. Default is 1.

Appointments

Appointments List

curl "https://api.usealan.com/v1/appointments/<user_id>?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer abcdefgh12345678"

The above command returns JSON structured like this:

{
  "data": [
    {
      "appointment_id": "140124",
      "appointment_status": "unchecked",
      "lead_name": "Mariam Mustafa",
      "lead_phone_number": "4148404738",
      "campaign": "The challenge",
      "appointment_date": "2020-07-06",
      "appointment_start_time": "12:00:00",
      "appointment_end_time": "12:30:00",
      "appointment_created": "2020-07-01 12:12:41",
      "appointment_timezone": "America/New_York",
      "end_user_note": "",
      "down_payment": 0,
      "total_contract_value": 0
    },
    {
      "appointment_id": "139223",
      "appointment_status": "unchecked",
      "lead_name": "mark koss",
      "lead_phone_number": "2626139824",
      "campaign": "The challenge",
      "appointment_date": "2020-07-06",
      "appointment_start_time": "19:00:00",
      "appointment_end_time": "19:30:00",
      "appointment_created": "2020-07-02 11:10:33",
      "appointment_timezone": "America/New_York",
      "end_user_note": "",
      "down_payment": 0,
      "total_contract_value": 0
    }
  ],
  "code": 200,
  "message": "Successful operation."
}

Gets list of appointments for a specific user ordered from last. If no date range is specified a limit of 500 appointments will be applied. The "multiparty" data in the results is optional depending on the CPs configuration.

HTTP Request

GET https://api.usealan.com/v1/appointments/<user_id>?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD

Query Parameters

Parameter Description
user_id ID of the end user.
start_date (Optional) YYYY-MM-DD Start date for query.
end_date (Optional) YYYY-MM-DD End date for query. It can't be less than the start date.
size (Optional) Integer. Quantity of results returned. Default is 500. Maximum is 5000
page (Optional) Integer. The page parameter is used to specify the page number when retrieving paginated data. Default is 1.

Mark Showed

curl "https://api.usealan.com/v1/mark_show/<appointment_id>" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer abcdefgh12345678"

The above command returns JSON structured like this:

{
  "data": null,
  "code": 200,
  "message": "Appointment <appointment_id> successfully marked as showed."
}

Marks appointment as 'Showed'.

HTTP Request

POST https://api.usealan.com/v1/mark_show/<appointment_id>

Query Parameters

Parameter Description
appointment_id ID of the appoinment to mark as 'Showed'.

Mark No Showed

curl "https://api.usealan.com/v1/mark_no_show/<appointment_id>" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer abcdefgh12345678"

The above command returns JSON structured like this:

{
  "data": null,
  "code": 200,
  "message": "Appointment <appointment_id> successfully marked as no showed."
}

Marks appointment as ‘No Showed’.

HTTP Request

POST https://api.usealan.com/v1/mark_no_show/<appointment_id>

Query Parameters

Parameter Description
appointment_id ID of the appoinment to mark as 'No Showed'.

Mark Sold

curl "https://api.usealan.com/v1/mark_sold/<appointment_id>" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer abcdefgh12345678"
  -d '{
    "down_payment": 70,
    "annual_contract_value": 5000
  }'

The above command returns JSON structured like this:

{
  "data": null,
  "code": 200,
  "message": "Appointment <appointment_id> successfully marked as sold."
}

Marks appointment as ‘Sold’.

HTTP Request

POST https://api.usealan.com/v1/mark_sold/<appointment_id>

Query Parameters

Parameter Description
appointment_id ID of the appoinment to mark as 'Sold'.
down_payment Down payment value, double greater or equal than 0.
annual_contract_value Annual contract value, double greater or equal than 0.

Invoices

Invoices List

curl "https://api.usealan.com/v1/invoices/<user_id>?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer abcdefgh12345678"

The above command returns JSON structured like this:

{
    "data": [
        {
            "order_id": "123456",
            "invoice_number": "ALN-123456",
            "date": "2024-04-08 01:26:44",
            "status": "failed",
            "invoice_type": "Confirm",
            "billing_type": "model_billing",
            "subtotal": "29.98",
            "tax": "0",
            "total": "29.98",
            "items": [
                {
                    "lead_name": "Holly Klinkhammer",
                    "campaign": "Sales Consultation",
                    "charge_type": "SHOWED",
                    "reason": "Marked",
                    "confirm_price": "14.99"
                },
                {
                    "lead_name": "Joel Durfee",
                    "campaign": "Sales Consultation",
                    "charge_type": "SHOWED",
                    "reason": "Marked",
                    "confirm_price": "14.99"
                }
            ],
            "business_details": [
                {
                    "id": "1234",
                    "name": "End User Name",
                    "email": "test@example.com"
                }
            ]
        }
    ],
    "code": 200,
    "message": "Successful operation."
}

Gets list of invoices for a specific user. If no date range is specified, lifetime invoices will be returned.

HTTP Request

GET https://api.usealan.com/v1/invoices/<user_id>?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD

Query Parameters

Parameter Description
user_id ID of the end user.
start_date (Optional) YYYY-MM-DD Start date for query.
end_date (Optional) YYYY-MM-DD End date for query. It can't be less than the start date.

Stats

Main Stats

curl "https://api.usealan.com/v1/stats/<user_id>?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD" \
  -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer abcdefgh12345678"

The above command returns JSON structured like this:

{
  "data": {
    "business_details": {
      "id": "1001",
      "name": "John Doe",
      "email": "john@mail.com"
    },
    "leads": 239,
    "schedules": 75,
    "shows": 35,
    "solds": 25,
    "total_amount": 345,
    "amount_down": 73,
    "start_date": "2022-12-01 00:00:00",
    "end_date": "2022-12-31 23:59:59"
  },
  "code": 200,
  "message": "Successful operation."
}

Gets general stats for a specific user. If no date range is specified, lifetime stats will be returned.

HTTP Request

GEThttps://api.usealan.com/v1/stats/<user_id>?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD

Query Parameters

Parameter Description
user_id ID of the end user.
start_date (Optional) YYYY-MM-DD Start date for query.
end_date (Optional) YYYY-MM-DD End date for query. It can't be less than the start date.

Errors

The Usealan API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The resource requested can't be accessed.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access a resource with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The resource requested has been removed from our servers.
418 I'm a teapot.
429 Too Many Requests -- You're requesting too many resources! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
shell