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=your_api_key' \
-F 'client_secret=your_secret' \
We’re using an OAuth2 based implementation, so you can get your Bearer Access Token
through our authorize endpoint:
https://api.beeliked.com/v1/authorize
# Result Example
{ "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSl...", "expires_in": 300, "refresh_expires_in": 1800, "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAio1...", "token_type": "bearer", "not-before-policy": 0, "session_state": "ced7d2e2-2946-..." }
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/:id \
-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", "entry_count": null, "referred_count": null, "referred_entry_count": null, "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 |
entry_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 POST 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 POST https://api.beeliked.com/v1/promotions/:promotion_id \
-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 POST https://api.beeliked.com/v1/promotions/:promotion_id/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, "member": { "id": 1, "uid": "johndoe@acme", "base_attributes": { "first_name": "John", "last_name": "Doe", "email": "johndoe@acme", "terms": true }, "verified_at": null, "created_at": "2020-10-05 16:29:12", "updated_at": "2020-10-05 16:29:13" }, "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 }
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 |
member | Member Object (optional) | Json representation of the member who created the entry |
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 POST https://api.beeliked.com/v1/promotions/:promotion_id/entries/:entry_id \
-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": null, "member": { "id": 1, "uid": "johndoe@acme", "base_attributes": { "first_name": "John", "last_name": "Doe", "email": "johndoe@acme", "terms": true }, "verified_at": null, "created_at": "2020-10-05 16:29:12", "updated_at": "2020-10-05 16:29:13" }, "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. |
member | Member Object (optional) | Json representation of the member who created the entry |
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 Link
# Here is a curl example
curl \
-X POST https://api.beeliked.com/v1/addons/entryLink \
-H 'Accept: application/json' \
-H "Authorization: Bearer <Your Generated Token>"
-F 'promotion_id=PROMOTION_ID'
This endpoint generates an EntryLink URL you can present your users for a single entry to one your promotions.
Use EntryLink 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 EntryLink 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 EntryLink
Please contact BeeLiked Support for assistance with this add on feature.
POST https://api.beeliked.com/v1/addons/entryLink
# Result Example
{ entry_url: "https://beeliked-ready-made-2-0.pollen8.co/pool-party-2-1?signon?c=6eeab5263ce5a28082081e963168b484%2FMTK1HXsE7SiVzRSrw..." }
QUERY PARAMETERS
Field | Type | Description |
---|---|---|
promotion_id | Integer|Required | Promotion identifier |
uid | String (optional) | Unique identifier of the audience member |
field_values | Array|Object (optional) | Object containing the form field slugs as keys and data as values |
secret_key | String (optional) | The secret key used for encryption |
ENTRY LINK OBJECT
Field | Type | Description |
---|---|---|
entry_url | String | Generated one time use Entry Link URL |
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 .
|