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

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.