Get started

API Endpoint https://api.beeliked.com/v1/

BeeLiked is a digital marketing platform that offers businesses a range of interactive and gamified promotion types to engage their online audiences.

The BeeLiked API helps you to query for your audience data, promotions and entries.

The API also allows the generation of unique entry links for promotions that have the Entry Links plugin enabled.

Authentication

# Here is a curl example
curl \
-X POST https://api.beeliked.com/v1/authorize \
-F 'client_id=1234567890-1234567890-12345678' \
-F 'client_secret=0987654321-0987654321-0987654321'
             

We’re using an OAuth2 based implementation, so you can get your Bearer Access Token through our authorize endpoint:
POST https://api.beeliked.com/v1/authorize

# Result Example{
    "access_token": "1234567890123456789012345678",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "098765432109876543210987654321",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "0987654321-0987654321-0987654321"
}
                

QUERY PARAMETERS

Field	Type	Description
client_id	String	Your API client key.
client_secret	String	Your API client secret

You can generate your API Keys in your BeeLiked Account settings while logged in as an administrator user.

Audience Members

# Here is a curl example
curl \
-X GET https://api.beeliked.com/v1/audience/members \
-H 'Accept: application/json'  \
-H "Authorization: Bearer <Your Generated Token>"

This endpoint enables you to retrieve a list of all participants in your promotions (Audience).
The list only includes base attributes. To retrieve the full list of attributes, check Audience Member Details
GET https://api.beeliked.com/v1/audience/members

# Result Example{
    "data": [
        {
            "id": 1,
            "is_test": false,
            "uid": "johndoe@acme.com",
            "verified_at": null,
            "created_at": "2020-10-07 21:46:42",
            "updated_at": "2020-10-07 21:46:43",
            "base_attributes": {
                "first_name": "John",
                "last_name": "Doe",
                "email": "johndoe@acme.com",
                "terms": true,
                "newsletter": true
            }
        },
    ],
    "currentPage": 1,
    "firstPageUrl": "https://api.beeliked.com/v1/audience/members?sort_order=desc&limit=50&page=1",
    "from": 1,
    "lastPage": 1,
    "lastPageUrl": "https://api.beeliked.com/v1/audience/members?sort_order=desc&limit=50&page=1",
    "nextPageUrl": null,
    "path": "",
    "limit": 50,
    "prevPageUrl": null,
    "to": 1,
    "total": 1
}

QUERY PARAMETERS

Field	Type	Description
page	Integer (optional)	Page number
limit	Integer (optional)	Results per page
test_mode	Boolean (optional)	Show only test mode or not

MEMBER OBJECT (PAGINATED)

Attribute	Type	Description
id	Integer	Identifier
is_test	Boolean (optional)	Whether is was created as a test
uid	String (optional)	Unique identifier. Eg.: Member email
created_at	DateTime string	Date and time of creation
updated_at	DateTime string	Date and time of last update
base_attributes	Json (optional)	Json representation of base data attributes: first_name, last_name, email, terms and newsletter

Check the Pagination section to check the full structure of paginated responses.

Audience Member Details

# Here is a curl example
curl \
-X GET https://api.beeliked.com/v1/audience/members/1234 \
-H 'Accept: application/json'  \
-H "Authorization: Bearer <Your Generated Token>"

This endpoint enables you to retrieve one participant from your promotions (Audience).
GET https://api.beeliked.com/v1/audience/members/:member_id

# Result Example{
    "id": 1,
    "is_test": false,
    "uid": "johndoe@acme.com",
	"uid_field": "email",
    "entries_count": 0,
    "referred_count": 0,
    "referred_entry_count": 0,
    "verified_at": null,
    "created_at": "2020-10-07 21:46:42",
    "updated_at": "2020-10-07 21:46:43",
    "attributes": {
        "first-name": "John",
        "last-name": "Doe",
        "email": "johndoe@acme.com",
        "newsletter": "1",
        "terms-and-conditions": "1"
    }
}

QUERY PARAMETERS

Field	Type	Description
member	Integer	Member identifier

MEMBER OBJECT

Attribute	Type	Description
id	Integer	Identifier
is_test	Boolean (optional)	Whether is was created as a test
uid	String (optional)	Unique identifier. Eg.: Member email
uid_field	String	Field used as UID. Eg.: email
entries_count	Integer (optional)	Total entries created by the member
referred_count	Integer (optional)	Total members referred by the member
referred_entry_count	Integer (optional)	Total entries by members referred by the member
verified_at	DateTime string (optional)	Date time of verification (Eg.: Date of email validation)
created_at	DateTime string	Date and time of creation
updated_at	DateTime string	Date and time of last update
attributes	Json (optional)	Json representation of all data attributes

Audience Member Details by UID

# Here is a curl example
curl \
-X GET https://api.beeliked.com/v1/audience/members-by-uid?uid=johndoe@acme.com&field=email \
-H 'Accept: application/json'  \
-H "Authorization: Bearer <Your Generated Token>"

This endpoint enables you to retrieve one participant from your promotions (Audience) by providing it's UID and UID Field.
GET https://api.beeliked.com/v1/audience/members-by-uid?uid=:uid&field=:field

# Result Example{
    "id": 1,
    "is_test": false,
    "uid": "johndoe@acme.com",
	"uid_field": "email",
    "entries_count": 0,
    "referred_count": 0,
    "referred_entry_count": 0,
    "verified_at": null,
    "created_at": "2020-10-07 21:46:42",
    "updated_at": "2020-10-07 21:46:43",
    "attributes": {
        "first-name": "John",
        "last-name": "Doe",
        "email": "johndoe@acme.com",
        "newsletter": "1",
        "terms-and-conditions": "1"
    }
}

QUERY PARAMETERS

Field	Type	Description
member	Integer	Member identifier

MEMBER OBJECT

Attribute	Type	Description
id	Integer	Identifier
is_test	Boolean (optional)	Whether is was created as a test
uid	String (optional)	Unique identifier. Eg.: Member email
uid_field	String	Field used as UID. Eg.: email
entries_count	Integer (optional)	Total entries created by the member
referred_count	Integer (optional)	Total members referred by the member
referred_entry_count	Integer (optional)	Total entries by members referred by the member
verified_at	DateTime string (optional)	Date time of verification (Eg.: Date of email validation)
created_at	DateTime string	Date and time of creation
updated_at	DateTime string	Date and time of last update
attributes	Json (optional)	Json representation of all data attributes

Promotions

# Here is a curl example
curl \
-X GET https://api.beeliked.com/v1/promotions \
-H 'Accept: application/json'  \
-H "Authorization: Bearer <Your Generated Token>"

This endpoint enables you to retrieve a list of all your promotions.
GET https://api.beeliked.com/v1/promotions

# Result Example{
    "data": [
        {
            "id": 1,
            "name": "My Pool Party Spin Campaign",
            "starts_at": "2020-02-07T14:25:34Z",
            "ends_at": null,
            "microsite_url": "https://beeliked-ready-made-2-0.pollen8.co/pool-party-2-1",
            "status": "live",
            "created_at": "2020-02-07T12:43:03Z",
            "updated_at": "2020-02-07T14:25:34Z",
        }
    ],
    "currentPage": 1,
    "firstPageUrl": "https://api.beeliked.com/v1/promotions?page=1&limit=50",
    "from": 1,
    "lastPage": 1,
    "lastPageUrl": "https://api.beeliked.com/v1/promotions?page=1&limit=50",
    "nextPageUrl": "https://api.beeliked.com/v1/promotions?page=1&limit=50",
    "limit": 50,
    "prevPageUrl": null,
    "to": 1,
    "total": 1
}

QUERY PARAMETERS

Field	Type	Description
page	Integer (optional)	Page number
limit	Integer (optional)	Results per page

PROMOTION OBJECT (PAGINATED)

Attribute	Type	Description
id	Integer	Identifier
name	String	Name
status	String	Status (draft, live or ended)
starts_at	DateTime string (optional)	Date and time when it starts
ends_at	DateTime string (optional)	Date and time when when it endes
microsite_url	String	Public microsite URL
created_at	DateTime string	Date and time of creation
updated_at	DateTime string	Date and time of last update

Check the Pagination section to check the full structure of paginated responses.

Promotion Details

# Here is a curl example
curl \
-X GET https://api.beeliked.com/v1/promotions/123 \
-H 'Accept: application/json'  \
-H "Authorization: Bearer <Your Generated Token>"

This endpoint enables you to retrieve one of your promotions.
GET https://api.beeliked.com/v1/promotions/:promotion_id

# Result Example{
    "id": 1,
    "name": "My Pool Party Spin Campaign",
    "starts_at": "2020-02-07T14:25:34Z",
    "ends_at": null,
    "microsite_url": "https://beeliked-ready-made-2-0.pollen8.co/pool-party-2-1",
    "status": "live",
    "created_at": "2020-02-07T12:43:03Z",
    "updated_at": "2020-02-07T14:25:34Z",
    "form": {
        "name": "Default form",
        "created_at": "2020-10-03 10:37:15",
        "updated_at": "2020-10-03 10:37:15",
        "fields": [
            {
                "id": 7,
                "name": "First name",
                "is_identifier_field": true,
                "is_uid_field": false,
                "is_optin": false,
                "type": "text",
                "slug": "first-name",
                "created_at": "2020-10-03 10:37:15",
                "updated_at": "2020-10-03 10:37:15"
            }
        ]
    }
}

QUERY PARAMETERS

Field	Type	Description
page	Integer (optional)	Page number
limit	Integer (optional)	Results per page

PROMOTION OBJECT

Attribute	Type	Description
id	Integer	Identifier
name	String	Name
status	String	Status (draft, live or ended)
starts_at	DateTime string (optional)	Date and time when it starts
ends_at	DateTime string (optional)	Date and time when when it endes
microsite_url	String	Public microsite URL
created_at	DateTime string	Date and time of creation
updated_at	DateTime string	Date and time of last update
form	Form Object (optional)	Form object representation

FORM OBJECT

Attribute	Type	Description
name	String	Name
created_at	DateTime string	Date and time of creation
updated_at	DateTime string	Date and time of last update
fields	Array of Field Objects (optional)	Collection of Fields objects

FIELD OBJECT

Attribute	Type	Description
id	Integer	Identifier
name	String	Name
is_identifier_field	Boolean (optional)	Whether the field can identify an user
is_uid_field	Boolean (optional)	Wheter the field is an unique identifier
is_optin	Boolean (optional)	Wherter the field is used as opt in (Eg.: Newsletter optin)
type	String (optional)	Type (Eg.: text, checkbox, select, etc
slug	String	Unique string identifier
created_at	DateTime string	Date and time of creation
updated_at	DateTime string	Date and time of last update

Promotion Entries

# Here is a curl example
curl \
-X GET https://api.beeliked.com/v1/promotions/1234/entries \
-H 'Accept: application/json'  \
-H "Authorization: Bearer <Your Generated Token>"

This endpoint enables you to retrieve a list of all entries for one of your promotions.
GET https://api.beeliked.com/v1/promotions/:promotion_id/entries

# Result Example{
    "data": [
        {
            "id": 1,
            "promotion_id": 1,
            "member_id": 1,
            "member_deleted_at": null,
            "referrer_id": null,
            "completed_at": null,
            "created_at": "2020-10-04 16:29:13",
            "updated_at": "2021-01-14 23:06:16",
            "attributes": {
                "outcome_id": 5,
				"outcome_label": "Winner"				
            },
            "member": {
                "uid": "3e0p",
                "uid_field_id": 20,
                "attributes": {
                    "first_name": "John",
                    "last_name": "Doe",
                    "email": "johndoe@acme.com",
                    "terms": true
                }
            }
        },
    ],
    "currentPage": 1,
    "firstPageUrl": "https://api.beeliked.com/v1/promotions/1/entries?limit=50&page=1",
    "from": 1,
    "lastPage": 1,
    "lastPageUrl": "https://api.beeliked.com/v1/promotions/1/entries?limit=50&page=1",
    "nextPageUrl": null,
    "limit": 50,
    "prevPageUrl": "https://api.beeliked.com/v1/promotions/1/entries?limit=50&page=1",
    "to": 1,
    "total": 1
}

QUERY PARAMETERS

Field	Type	Description
page	Integer (optional)	Page number
limit	Integer (optional)	Results per page

RESPONSE OBJECT (PAGINATED)

Attribute	Type	Description
id	Integer	Identifier
promotion_id	Integer	Promotion identifier
member_id	Integer (optional)	Member identifier
member_deleted_at	DateTime string (optional)	Date when the member was deleted.
referrer_id	Boolean (optional)	Identifier of the member who referred
completed_at	DateTime string (optional)	Date when the entry was completed
created_at	DateTime string	Date and time of creation
updated_at	DateTime string	Date and time of last update
attributes	Json (optional)	Entry data representation. Eg.: outcome_id, outcome_label, segment_id, segment_title, etc
attributes	Json (optional)	Member data representation. Eg.: uid, uid_field_id, attributes

Check the Pagination section to check the full structure of paginated responses.

Promotion Entry Details

# Here is a curl example
curl \
-X GET https://api.beeliked.com/v1/promotions/1234/entries/54321 \
-H 'Accept: application/json'  \
-H "Authorization: Bearer <Your Generated Token>"

This endpoint enables you to retrieve an entry of one of your promotions.
GET https://api.beeliked.com/v1/promotions/:promotion_id/entries/:entry_id

# Result Example{
    "id": 1,
    "promotion_id": 1,
    "member_id": 1,
    "member_deleted_at": null,
    "referrer_id": null,
    "member_data": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@acme",
        "terms": true
	},
    "completed_at": null,
    "created_at": "2020-10-04 16:29:13",
    "updated_at": "2021-01-14 23:06:16",
    "attributes": {
        "outcome_id": 1,
		"outcome_label": "Winner"
    }
}

ENTRY OBJECT

Attribute	Type	Description
id	Integer	Identifier
promotion_id	Integer	Promotion identifier
member_id	Integer (optional)	Member identifier
member_deleted_at	DateTime string (optional)	Date when the member was deleted.
referrer_id	Integer (optional)	Identifier of the member who referred
member_data	Array (optional)	The provided member data when the entry was created.
completed_at	DateTime string (optional)	Date when the entry was completed
created_at	DateTime string	Date and time of creation
updated_at	DateTime string	Date and time of last update
attributes	Json (optional)	Entry data representation. Eg.: outcome_id, outcome_label, segment_id, segment_title, etc

Addons - Entry Links

# Here is a curl example
curl \
-X GET https://api.beeliked.com/v1/addons/entry-links \
-H 'Accept: application/json'  \
-H "Authorization: Bearer <Your Generated Token>"

This endpoint enables you to retrieve a list of all entry links.
GET https://api.beeliked.com/v1/addons/entry-links

# Result Example{
    "data": [
        {
			"uid": "johndoe@acme.com",
			"uid_field": "email",
			"code": "1A2B3C4D",
			"data": {
				"first-name": "John",
				"last-name": "Doe"
			},
			"promotion_id": 123,
			"entry_link": "https://beeliked.pollen8.co/my-campaign?inv=1A2B3C4D",
			"created_at": "2021-07-13T15:04:29.000000Z"
		}
    ],
    "currentPage": 1,
    "firstPageUrl": "https://api.beeliked.com/v1/addons/entry-links?limit=50&page=1",
    "from": 1,
    "lastPage": 1,
    "lastPageUrl": "https://api.beeliked.com/v1/addons/entry-links?limit=50&page=1",
    "nextPageUrl": null,
    "limit": 50,
    "prevPageUrl": "https://api.beeliked.com/v1/addons/entry-links?limit=50&page=1",
    "to": 1,
    "total": 1
}

QUERY PARAMETERS

Field	Type	Description
promotion_id	Integer (optional)	Promotion ID to filter by
page	Integer (optional)	Page number
limit	Integer (optional)	Results per page

RESPONSE OBJECT (PAGINATED)

Field	Type	Description
entry_link	String	Generated Entry Link URL with one time use invite code
code	String	Generated unique invite code
uid	String	User identifier (generated when not provided)
uid_field	String	Field used as uid
promotion_id	Integer	Promotion identifier
data	Array (optional)	The provided field values when the entry link was created.
created_at	DateTime string	Date and time of creation

Check the Pagination section to check the full structure of paginated responses.

Addons - Entry Link Details

# Here is a curl example
curl \
-X GET https://api.beeliked.com/v1/addons/entry-links/1A2B3C4D \
-H 'Accept: application/json'  \
-H "Authorization: Bearer <Your Generated Token>"

This endpoint enables you to retrieve an entry link by code
GET https://api.beeliked.com/v1/addons/entry-links/:code

# Result Example{
    "uid": "johndoe@acme.com",
    "uid_field": "email",
    "code": "1A2B3C4D",
    "data": {
        "first-name": "John",
		"last-name": "Doe"
    },
    "promotion_id": 123,
    "entry_link": "https://beeliked.pollen8.co/my-campaign?inv=1A2B3C4D",
    "created_at": "2021-07-13T15:04:29.000000Z"
}

ENTRY LINK OBJECT

Field	Type	Description
entry_link	String	Generated Entry Link URL with one time use invite code
code	String	Generated unique invite code
uid	String	User identifier (generated when not provided)
uid_field	String	Field used as uid
promotion_id	Integer	Promotion identifier
data	Array (optional)	The provided field values when the entry link was created.
created_at	DateTime string	Date and time of creation

Addons - Entry Link Create

# Here is a curl example
curl \
-X POST https://api.beeliked.com/v1/addons/entry-links \
-H 'Accept: application/json'  \
-H "Authorization: Bearer <Your Generated Token>"
-d '{ "promotion_id": 1234, "uid": "johndoe@acme.com", "uid_field": "email", "field_values": { "first-name": "John", "last-name": "Doe" }}'
		

This endpoint generates an Entry Link URL you can present your users for a single entry to one your promotions.
Use Entry Link if you wish to control when and who can enter one of your promotions as each link can be used once and can even be personalized to include user data.
This endpoint requires the Entry Link add on to be activated and enabled for the specified promotion. Once enabled, EntryLink restricts entry to the promotion to only those with a valid single use Entry Link
Please contact BeeLiked Support for assistance with this add on feature.
POST https://api.beeliked.com/v1/addons/entry-links

# Result Example{
    "uid": "johndoe@acme.com",
    "uid_field": "email",
    "code": "1A2B3C4D",
    "data": {
        "first-name": "John",
		"last-name": "Doe"
    },
    "promotion_id": 123,
    "entry_link": "https://beeliked.pollen8.co/my-campaign?inv=1A2B3C4D",
    "created_at": "2021-07-13T15:04:29.000000Z"
}
		

POST PARAMETERS

Field	Type	Description
promotion_id	Integer|Required	Promotion identifier
uid	String (optional, generated when not provided)	Unique identifier of the audience member
uid_field	String (required when uid is provided)	Field used as uid
field_values	Array|Object (optional)	Object containing the form field slugs as keys and data as values

ENTRY LINK OBJECT

Field	Type	Description
entry_link	String	Generated Entry Link URL with one time use invite code
code	String	Generated unique invite code
uid	String	User identifier (generated when not provided)
uid_field	String	Field used as uid
promotion_id	Integer	Promotion identifier
data	Array (optional)	The provided field values when the entry link was created.
created_at	DateTime string	Date and time of creation

Pagination

# Result Example{
    "data": [...],
    "currentPage": 1,
    "lastPage": 10,
    "limit": 50,    
    "total": 480,
    "from": 1,
	"to": 50,
    "firstPageUrl": "https://api.beeliked.com/v1/...?limit=50&page=1",
	"nextPageUrl": "https://api.beeliked.com/v1/...?limit=50&page=2",
    "prevPageUrl": null,
    "lastPageUrl": "https://api.beeliked.com/v1/...?limit=50&page=10"
}

The BeeLiked API uses the following pagination structure for list results:

PAGINATION OBJECT

Attribute	Type	Description
data	array of objects	The collection of objects of the requested type
currentPage	Integer (optional)	Current page number
lastPage	Integer (optional)	Last page number
limit	Integer (optional)	Number of results for page
total	Integer (optional)	The total number of matching objects
from	Integer (optional)	First record number
to	Integer (optional)	Last record number
firstPageUrl	String (optional)	First page URL
prevPageUrl	String (optional)	Previous page
nextPageUrl	String (optional)	Next page URL or null
lastPageUrl	String (optional)	Last page URL or null

Errors

The BeeLiked API uses the following error codes:

Error Code	Meaning
400	Some parameters are missing. This error appears if you don't pass a mandatory parameter.
400	Invalid secret_key. This error appears during the authentication.
403	Forbidden token. This error appears if you use an invalid or expired token.
404	Not found. This error appears if an object was not found.