Surveys API | Besitos Knowledge Base

The Surveys API provides links to surveys, estimated completion times, and reward amounts. Use this data to give your users access to engaging surveys and the information they need to decide which surveys to take.

Additionally, you can subscribe to the User Profiling API to receive users' responses to survey profiling questions, which provides insights into your user base.

Preparing to connect

Follow these steps to prepare to connect to Besitos APIs:

Have your partner ID ready.
Contact your Besitos Account Manager to request API access.
Set up postback.
Generate and save your bearer token for authentication.

Continue reading for a complete description of the API parameters and response attributes, or visit our Postman collection to start testing.

Endpoint

Endpoint URL	https://wall.besitos.ai/data/surveys/wall/{partner_id}/{partner_user_id}
HTTP Method	GET
Refresh rate	5 minutes

Path parameters

Path parameter	Data type	Required	Description
`partner_id`	string	yes	Your Besitos partner ID.
`partner_user_id`	string	yes	The ID of a user in your database. Maximum 50 characters

Query parameters

The request supports the following optional query parameters.

Query parameter	Data type	Required	Description
`device`	string	yes	The user's device can be a mobile phone, tablet, or desktop computer.
`user_ip`	string	yes	The user's IP address.
`gender`	string	no	The user's gender as `m` for male or `f` for female.
`dob`	date/time	no	The user's date of birth in YYYY-MM-DD format.
`postal_code`	integer	no	The user's postal code. Maximum of 20 characters

Examples

Request

GET https://wall.besitos.ai/data/surveys/wall/vwidqtrrn6sx/abc123?device=mobile&user_ip=107.4.147.79

Response

[
    {
        "id": 1,
        "name": "test_1",
        "length": 1,
        "amount": 0.5,
        "amount_currency": "$",
        "cpi": 1,
        "url": "http://besitos.kashkick.loc/survey/redirect/4ypj1wuwensd/1/b-sr5wijvkx2hyutbgwe/545d3f3f-0e8c-413e-91a6-529dcfaa088c",
    },
    {
        "id": 2,
        "name": "test_2",
        "length": 5,
        "amount": 0.5,
        "amount_currency": "$",
        "cpi": 1,
        "url": "http://besitos.kashkick.loc/survey/redirect/4ypj1wuwensd/2/b-sr5wijvkx2hyutbgwe/52431ea4-22ca-4b15-8dc3-4fad5fc6437d",
    },
    {
        "id": 3,
        "name": "test_3",
        "length": 6,
        "amount": 0.25,
        "amount_currency": "$",
        "cpi": 0.5,
        "url": "http://besitos.kashkick.loc/survey/redirect/4ypj1wuwensd/3/b-sr5wijvkx2hyutbgwe/74da5fe6-df78-441a-986a-7d476973c9be",
    },
    {
        "id": 4,
        "name": "test_4",
        "length": 0.8333333333333334,
        "amount": 0.13,
        "amount_currency": "$",
        "cpi": 0.25,
        "url": "http://besitos.kashkick.loc/survey/redirect/4ypj1wuwensd/4/b-sr5wijvkx2hyutbgwe/822f4bea-0bdc-4304-902f-7df15a10d06b",
    },
    {
        "id": 4,
        "name": "test_4",
        "length": 0.8333333333333334,
        "amount": 0.13,
        "amount_currency": "$",
        "cpi": 0.25,
        "url": "http://besitos.kashkick.loc/survey/redirect/4ypj1wuwensd/4/b-sr5wijvkx2hyutbgwe/e476ebc0-1511-44f6-94be-a92d02112d0c",
    },
    {
        "id": 3,
        "name": "test_3",
        "length": 6,
        "amount": 0.25,
        "amount_currency": "$",
        "cpi": 0.5,
        "url": "http://besitos.kashkick.loc/survey/redirect/4ypj1wuwensd/3/b-sr5wijvkx2hyutbgwe/3eeae948-60de-48a4-96b6-a300ebd83308",
    },
    {
        "id": 7,
        "name": "test_7",
        "length": 7.883333333333334,
        "amount": 0.13,
        "amount_currency": "$",
        "cpi": 0.25,
        "url": "http://besitos.kashkick.loc/survey/redirect/4ypj1wuwensd/7/b-sr5wijvkx2hyutbgwe/50b0d0fe-088d-42d7-b8f9-baad8f9d721f",
    }
]

Response attributes

Attributes	Data Type	Description	Example
`id`	string	Unique survey identifier.	`3`
`name`	string	Unique survey title.	`"Survey 1"`
`length`	float	The estimated time, in minutes, it takes to complete the survey.	`5`
`amount`	float	The user's total earning potential in the partner's (your) currency.	`1`
`amount_currency`	string	Currency type sign	`"$"`
`cpi`	float	Your (the partner's) payout in USD.	`.5`
`url`	string	The link to the survey.	`"http://besitos.kashkick.loc/survey/redirect/4ypj1wuwensd/2/b-2l7bx9r30mz1fehqzo/496d4929-ed61-4e90-b249-9bf76657eca4"`

With the Surveys API enabled, you'll receive type and survey_ID attributes in the Conversion Data API response and postback.

Survey redirect link

As part of the setup, we need to know where you want to send users after they complete a survey. For example, you might return them to your app or website, where they can take more surveys.

The redirect URL should look like this:

https://{your_custom_survey_redirect}/?survey_id={surveyid}&user_id={user_id}&status={status}

Parameter	Type	Description
`survey_id`	string	Unique survey identifier.
`user_id`	string	Unique user identifier.
`status`	string	C = complete T = terminate