SmartEngage API Reference

The SmartEngage API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URLs:

https://api.smartengage.com/

Authentication

The SmartEngage API uses API keys to authenticate requests. You can view and manage your API keys in the SmartEngage Dashboard.

Authentication to the API is performed via bearer auth (e.g., for a cross-origin request), use -H "Authorization: Bearer se_k73DUceVnvRCusWxDN2qQQ1a"

curl -X POST https://api.smartengage.com/avatars/list \
  -H 'Authorization: Bearer {api-key}'

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Avatars

Your Brand Avatar is Your Business! A person can also be a brand. The important thing here is that you have a Facebook Fan Page for your Brand which will be used to help keep things organized inside of SmartEngage.

The API allows you to create, delete, and update your avatars. You can retrieve individual avatars as well as a list of all your avatars.

List All Avatars

Returns a list of your avatars. The avatars are returned sorted by creation date, with the most recent avatars appearing first.

GET /avatars/list

curl -X GET https://api.smartengage.com/avatars/list \
  -H 'Authorization: Bearer {api-key}'

Example Response

 [
   {
       "brand_name": "BacklinksIndexer",
       "avatar_id": "3",
       "brand_image": "https://cdn.smartengage.com/uploads/avatars/76082f2b90607b7731cd619f96aa6111.png",
       "user_role": "2",
       "facebook_page_id": "1xxxxxxxxxxxx57"
   },
   {
       "brand_name": "The Bachelor Bracket",
       "avatar_id": "2",
       "brand_image": "https://cdn.smartengage.com/uploads/avatars/e72d12d1c4a864add0116a0bb891c6d3.png",
       "user_role": "2",
       "facebook_page_id": "3xxxxxxxxxxxx04"
   },
   {
       "brand_name": "SmartEngage",
       "avatar_id": "1",
       "brand_image": "https://cdn.smartengage.com/uploads/avatars/30124196_426878104401893_6352101114313179136_n.png",
       "user_role": "2",
       "facebook_page_id": "2xxxxxxxxxxxx53"
   }
]

Tags

These start with a hashtag # and are assigned by you or during some sort of automation or Lead Magnet acquisition. Subscribers can have multiple tags assigned to them in order to help you stay organized.

Create Tag

Return newly inserted data of your tag.

POST /tags/create

curl -X POST https://api.smartengage.com/tags/create \
  -H 'Authorization: Bearer {api-key}' \
  -d tag_name=new_tag_name \
  -d avatar_id=1

Parameters

Parameter	Required	Description
avatar_id	true	The avatars id
tag_name	true	Tag name

Example Response

{
    "tag_id": "1",
    "avatar_id": "1",
    "tag_type_id": "1",
    "date_added": "2018-01-20 08:05:18",
    "tag_name": "new_tag_name",
    "tag_status": "1",
    "status": 1
}

List All Tags

Returns a list of your tags. The tags are returned sorted by creation date, with the most recent avatars appearing first.

GET /tags/list/?avatar_id=XX

curl -X GET https://api.smartengage.com/tags/list/?avatar_id=1 \
  -H 'Authorization: Bearer {api-key}'

Parameters

Parameter	Required	Description
avatar_id	true	The avatars id

Example Response

 [
   {
       "tag_id": "1",
       "tag_name": "push_test"
   },
   {
       "tag_id": "2",
       "tag_name": "fb_test"
   }
]

Add Tag to Subscriber

POST /tags/add

curl -X POST \
  https://api.smartengage.com/tags/add \
  -H 'Authorization: Bearer {api-key}' \
  -d avatar_id=123 \
  -d subscriber_id=1 \
  -d 'tag=123' \

Parameters

Parameter	Required	Description
avatar_id	true	The avatars id
subscriber_id	true	The subscribers id
tag	true	Tag for subscribers

Example responses

{
    "id": "1",
    "full_name": "John Doe",
    "email": "admin@example.com",
    "ip": null,
    "gender": null,
    "language": null,
    "place": null,
    "facebook_id": "212312312353",
    "push_id": "https://fcm.googleapis.com/fcm/send/dAh9lRTaKVo:X...XXX",
    "tags": [
        "tags1",
        "tags2"
    ],
    "custom_fields": [
        {
            "custom_field_id": "111",
            "custom_field_name": "location",
            "custom_value": "US"
        }
    ],
    "sequences": [
        {
            "sequence_id": "1",
            "sequence_name": "Seq 1",
            "status": "Completed"
        },
        {
            "sequence_id": "2",
            "sequence_name": "Seq 2",
            "status": "Active"
        } 
    ]
}

Remove Tag from Subscriber

POST /tags/delete

curl -X POST \
  https://api.smartengage.com/tags/delete \
  -H 'Authorization: Bearer {api-key}' \
  -d avatar_id=123 \
  -d subscriber_id=1 \
  -d 'tag=123' \

Parameters

Parameter	Required	Description
avatar_id	true	The avatars id
subscriber_id	true	The subscribers id
tag	true	Tag for subscribers

Example responses

{
    "id": "1",
    "full_name": "John Doe",
    "email": "admin@example.com",
    "ip": null,
    "gender": null,
    "language": null,
    "place": null,
    "facebook_id": "212312312353",
    "push_id": "https://fcm.googleapis.com/fcm/send/dAh9lRTaKVo:X...XXX",
    "tags": [
        "tags1",
        "tags2"
    ],
    "custom_fields": [
        {
            "custom_field_id": "111",
            "custom_field_name": "location",
            "custom_value": "US"
        }
    ],
    "sequences": [
        {
            "sequence_id": "1",
            "sequence_name": "Seq 1",
            "status": "Completed"
        },
        {
            "sequence_id": "2",
            "sequence_name": "Seq 2",
            "status": "Active"
        } 
    ]
}

Custom Fields

Custom Fields allow you to store valuable information about your subscribers. For example, within our Facebook Messenger chatbot you ask the subscriber's type of business, receive a reply, and store it as a custom field for "Business Type".

Create Custom Field

Return newly inserted data of your Custom Field.

POST /customfields/create

curl -X POST https://api.smartengage.com/customfields/create \
  -H 'Authorization: Bearer {api-key}' \
  -d custom_field_name=new_custom_field_name \
  -d custom_field_title=title_example \
  -d custom_field_type=text \
  -d custom_field_desc=description_example \
  -d avatar_id=1

Parameters

Parameter	Required	Description
avatar_id	true	The avatars id
custom_field_name	true	Custom Field name
custom_field_title	false	Custom Field title
custom_field_type	true	Custom type allowed input are : "text", "number", "date", "datetime", "boolean"
custom_field_desc	false	Custom Field Description

Example Response

{
    "custom_field_id": "1",
    "avatar_id": "1",
    "custom_field_name": "custom_field_via_api",
    "custom_field_title": "title_example",
    "date_added": "2018-01-20 08:05:18",
    "type": "text",
    "description": "description",
    "status": 1
}

List All Custom Fields

Returns a list of your Custom Fields. The fields are returned sorted by creation date, with the most recent avatars appearing first.

GET /customfields/list/?avatar_id=XX

curl -X GET https://api.smartengage.com/customfields/list/?avatar_id=1 \
  -H 'Authorization: Bearer {api-key}'

Parameters

Parameter	Required	Description
avatar_id	true	The avatars id

Example Response

 [
   {
       "custom_field_id": "1",
       "custom_field_name": "Number"
   },
   {
       "custom_field_id": "2",
       "custom_field_name": "Location"
   }
]

Set Custom Field Value

POST /customfields/update

curl -X POST \
  https://api.smartengage.com/customfields/update \
  -H 'Authorization: Bearer {api-key}' \
  -d avatar_id=123 \
  -d subscriber_id=1 \
  -d 'field=123' \
  -d 'value=CA' \

Parameters

Parameter	Required	Description
avatar_id	true	The avatars id
subscriber_id	true	The subscribers id
field	true	Custom field id for subscriber
value	true	Custom field value for subscriber

Example responses

{
    "id": "1",
    "full_name": "John Doe",
    "email": "admin@example.com",
    "ip": null,
    "gender": null,
    "language": null,
    "place": null,
    "facebook_id": "212312312353",
    "push_id": "https://fcm.googleapis.com/fcm/send/dAh9lRTaKVo:X...XXX",
    "tags": [
        "tags1",
        "tags2"
    ],
    "custom_fields": [
        {
            "custom_field_id": "111",
            "custom_field_name": "location",
            "custom_value": "US"
        }
    ],
    "sequences": [
        {
            "sequence_id": "1",
            "sequence_name": "Seq 1",
            "status": "Completed"
        },
        {
            "sequence_id": "2",
            "sequence_name": "Seq 2",
            "status": "Active"
        } 
    ]
}

Sequences

Automation sequences is a powerful way to run your business on autopilot

List All Sequences

Returns a list of your sequences. The sequences are returned sorted by creation date, with the most recent avatars appearing first.

GET /sequences/list/?avatar_id=XX

curl -X GET https://api.smartengage.com/sequences/list/?avatar_id=1 \
  -H 'Authorization: Bearer {api-key}'

Parameters

Parameter	Required	Description
avatar_id	true	The avatars id

Example Response

 [
   {
       "sequence_id": "1",
       "sequence_name": "Seq 1"
   },
   {
       "sequence_id": "2",
       "sequence_name": "Seq 1"
   },
]

Subscribe to Sequence

POST /sequences/add

curl -X POST \
  https://api.smartengage.com/sequences/add \
  -H 'Authorization: Bearer {api-key}' \
  -d avatar_id=123 \
  -d subscriber_id=1 \
  -d 'sequence=1' \

Parameters

Parameter	Required	Description
avatar_id	true	The avatars id
subscriber_id	true	The subscribers id
sequence	true	Sequence for subscribers

Example responses

{
    "id": "1",
    "full_name": "John Doe",
    "email": "admin@example.com",
    "ip": null,
    "gender": null,
    "language": null,
    "place": null,
    "facebook_id": "212312312353",
    "push_id": "https://fcm.googleapis.com/fcm/send/dAh9lRTaKVo:X...XXX",
    "tags": [
        "tags1",
        "tags2"
    ],
    "custom_fields": [
        {
            "custom_field_id": "111",
            "custom_field_name": "location",
            "custom_value": "US"
        }
    ],
    "sequences": [
        {
            "sequence_id": "1",
            "sequence_name": "Seq 1",
            "status": "Completed"
        },
        {
            "sequence_id": "2",
            "sequence_name": "Seq 2",
            "status": "Active"
        } 
    ]
}

Unsubscribe From Sequence

POST /sequences/remove

curl -X POST \
  https://api.smartengage.com/sequences/remove \
  -H 'Authorization: Bearer {api-key}' \
  -d avatar_id=123 \
  -d subscriber_id=1 \
  -d 'sequence=1' \

Parameters

Parameter	Required	Description
avatar_id	true	The avatars id
subscriber_id	true	The subscribers id
sequence	true	Sequence for subscribers

Example responses

{
    "id": "1",
    "full_name": "John Doe",
    "email": "admin@example.com",
    "ip": null,
    "gender": null,
    "language": null,
    "place": null,
    "facebook_id": "212312312353",
    "push_id": "https://fcm.googleapis.com/fcm/send/dAh9lRTaKVo:X...XXX",
    "tags": [
        "tags1",
        "tags2"
    ],
    "custom_fields": [
        {
            "custom_field_id": "111",
            "custom_field_name": "location",
            "custom_value": "US"
        }
    ],
    "sequences": [
        {
            "sequence_id": "1",
            "sequence_name": "Seq 1",
            "status": "Completed"
        },
        {
            "sequence_id": "2",
            "sequence_name": "Seq 2",
            "status": "Active"
        } 
    ]
}

Subscribers

The API allows you to create, delete, and update your subscribers. You can retrieve individual subscribers as well as a list of all your subscribers.

Create a subscriber

Creates a new subscriber.

POST /subscribers/add

curl -X POST \
  https://api.smartengage.com/subscribers/add \
  -H 'Authorization: Bearer {api-key}' \
  -d avatar_id=123 \
  -d first_name=John \
  -d last_name=Doe \
  -d full_name=John Doe \
  -d email=admin@example.com \
  -d facebook_id="212312312353" \
  -d push_id="https://fcm.googleapis.com/fcm/send/dAh9lRTaKVo:X...XXX" \
  -d 'tags[]=123' \
  -d 'tags[]=124' \
  -d 'custom_field[]=111' \
  -d 'field_value[]=Field Value'

Parameters

Parameter	Required	Description
avatar_id	true	The avatars id
first_name	false	The subscribers full name
last_name	false	The subscribers full name
fullname	false	The subscribers full name
email*	true	Subscribers email address. It’s displayed alongside the subscriber in your dashboard and can be useful for searching and tracking.
facebook_id*	true	Identifier got from facebook
push_id*	true	Push notification id got from the web
tags	false	Tags for subscribers
custom_field	false	Subscriber's custom fields
field_value	false	Subscriber's custom fields values with respective to custom_field

Example responses

{
    "id": "1",
    "full_name": "John Doe",
    "email": "admin@example.com",
    "ip": null,
    "gender": null,
    "language": null,
    "place": null,
    "facebook_id": "212312312353",
    "push_id": "https://fcm.googleapis.com/fcm/send/dAh9lRTaKVo:X...XXX",
    "tags": [
        "tags1",
        "tags2"
    ],
    "custom_fields": [
        {
            "custom_field_id": "111",
            "custom_field_name": "location",
            "custom_value": "US"
        }
    ],
    "sequences": [
        {
            "sequence_id": "1",
            "sequence_name": "Seq 1",
            "status": "Completed"
        },
        {
            "sequence_id": "2",
            "sequence_name": "Seq 2",
            "status": "Active"
        } 
    ]
}

Update a Subscriber

Updates the specified Subscriber by setting the values of the parameters passed. Any parameters not provided will be left unchanged. For example, if you pass the email parameter, that becomes the subscribers’s email. This request accepts mostly the same arguments as the customer creation call.

POST /subscribers/update

curl -X POST \
  https://api.smartengage.com/subscribers/update \
  -H 'Authorization: Bearer {api-key}' \
  -d avatar_id=123 \
  -d subscriber_id=1 \
  -d first_name=John \
  -d last_name=Doe \
  -d full_name=John Doe \
  -d email=admins@example.com \
  -d facebook_id="212312312353" \

Parameters

Parameter	Required	Description
avatar_id	true	The avatars id
subscriber_id	true	The subscribers full name
first_name	false	The subscribers full name
last_name	false	The subscribers full name
fullname	false	The subscribers full name
email	false	Subscribers email address. It’s displayed alongside the subscriber in your dashboard and can be useful for searching and tracking.
facebook_id	false	Identifier got from facebook
push_id	false	Push notification id got from the web
tags	false	Tags for subscribers
custom_field	false	Subscriber's custom fields
field_value	false	Subscriber's custom fields values with respective to custom_field

Example responses

{
    "id": "1",
    "full_name": "John Doe",
    "email": "admin@example.com",
    "ip": null,
    "gender": null,
    "language": null,
    "place": null,
    "facebook_id": "212312312353",
    "push_id": "https://fcm.googleapis.com/fcm/send/dAh9lRTaKVo:X...XXX",
    "tags": [
        "tags1",
        "tags2"
    ],
    "custom_fields": [
        {
            "custom_field_id": "111",
            "custom_field_name": "location",
            "custom_value": "US"
        }
    ],
   "sequences": [
        {
            "sequence_id": "1",
            "sequence_name": "Seq 1",
            "status": "Completed"
        },
        {
            "sequence_id": "2",
            "sequence_name": "Seq 2",
            "status": "Active"
        } 
    ]
}