❗️

We’ve migrated to a new, more advanced callback system. Updated documentation will be available soon. In the meantime, the UI may look slightly different, but all underlying principles and behaviors remain the same.

What is a survey callback?

You can use the Survey Callback field when you want to receive only survey-related postbacks or if you prefer to handle surveys through a separate endpoint rather than using the standard Reward Callback field.

How to set up survey callbacks

Create a new advanced survey callback. Once added, a new configuration window will appear, allowing you to define all settings for this specific callback.

Multiple fields must be configured for a survey callback:

Callback URL Host

Enter the callback endpoint URL that you have set up to receive survey postbacks.

Protocol

Select the protocol for your callback URL. In most cases, the default value can be left as is.

Callback Parameters

Add all parameters required to process callbacks correctly.
We highly recommend including the following mandatory parameters:

• USER:UID
• TX
• CURRENCY:VALUE
• CURRENCY:USD

For surveys, it is also recommended to include:

• TYPE – indicates the survey state, which can be one of:
  • SCREENOUT
  • RECONCILIATION
  • START_BONUS
  • COMPLETE

Learn more about the survey states (type) here.

• Custom Parameters:
  If you want to attach your own static parameters, you can add them here. Note that only static values are supported.

• Example URL:
  This shows an example of a survey callback URL you might receive.
  Important: The hash shown in the example is for illustration purposes only and is not valid.

Below is an example of how a survey callback URL could be configured:

Press the Save button and then the Save Changes button in the top right.

Survey states

Each survey callback will have a different state (type). The following states (types) are available:

COMPLETE: The COMPLETE callback will be sent when a survey reward is being sent. A COMPLETE callback can also be sent if a user completes an install task, which usually gives a $0 reward. Notice that for surveys it is COMPLETE instead of COMPLETED.

START_BONUS: The START_BONUS callback will be sent when a user completes the starting bonus survey. It contains a reward similar to the COMPLETE callback. To receive START_BONUS callbacks separately, we offer a separate callback field.

SCREENOUT: A SCREENOUT callback will be sent when a user is disqualified from a survey. Our survey partner will evaluate the profile of a user during the survey. If at any point they notice that the profile is not matching with what they are looking for, a SCREENOUT will be sent. A SCREENOUT can also be sent, if a user is violating the survey's terms (speeding, not answering honestly, ...).

RECONCILIATION: A RECONCILIATION callback will be sent when a survey reward is reconciled. This means that we deduct the reward, mainly because of fraudulent reasons. 95% of reconciliations occur in the first 30 days after completion, but technically a reconciliation can occur anytime. A RECONCILIATION callback can occur after a COMPLETE was sent. Notice that for surveys it is RECONCILIATION instead of RECONCILED. The transaction IDs for reconciled callbacks will have the an r prefix. You can reference back to the initial callback by looking up the ref parameter.

Reconciliation callbacks

These callbacks notify you when there has been a reconciliation of previous transactions. This happens when researchers are not satisfied with the answers of a user, for example when a user just chose the first option for each question without any context. In this case, the transaction has to be reversed. If you are paying users with real money, we highly recommend setting up these reconciliation callbacks as they may prevent users from cashing out unrightfully.

Although it does not happen often, note that it can happen that a complete callback receives more than one following reconciliation callback. For example: a user completes a $2 survey. After that, you receive a reconciliation callback of -$2 indicating that the complete was reconciled. Sometimes, you might receive another reconciliation callback of $2 again showing that the reconciliation was send incorrectly and should be inverted again.

Note that every reconciliation callback has a unique transaction ID that is also different from the transaction ID of the complete callback. If you need the transaction ID of the COMPLETE callback instead, have a look at the [%REF%] parameter.

To receive reconciliation callbacks on a separate endpoint, we offer a dedicated callback field.

Survey parameters

For surveys we do provide additional parameters for additional information:

For a full list of all parameters, click here.

How to test survey callbacks

We offer a callback tester on the dashboard to test your configured callback endpoints. Learn more about it here.

Legacy way of testing

🚧

The following part of the documentation explains how callbacks were tested before the callback tester on the dashboard existed. We highly recommend not using the following method anymore!

To test if the callbacks are being sent correctly, use our survey test mode.

Enable the survey test mode on the BitLabs Dashboard -> Apps -> Your App -> Surveys -> Test Mode. Changes might need up to 5 minutes to apply because of caching.

Once the test mode is enabled, visit your offer wall and go to the surveys section. On there press any of the first 5 tiles to send a callback.

When you see a success screen, then the callback is sent. You now need to check in your system if you have processed it correctly.

If you see an error JSON response, you most likely have not set up the callbacks correctly.

Test callbacks will not be logged on the dashboard.