NAV Navigation
Curl

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

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

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

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

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

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"
        } 
    ]
}