Survey Support

Overview

The User History API returns a support_form_url on eligible survey entries. Show it to your users as a help button so they can contact BitLabs support directly about a specific survey, for example when they believe they were screened out unfairly.

The link opens a support form that already knows who the user is and which survey attempt they mean. Your users don't need to copy IDs, and you don't need to forward tickets. If support grants the request, BitLabs credits the user and notifies you through your callback.

Before you start

Survey Support must be enabled for your app. When it is off, support_form_url is never returned. To enable it, contact your BitLabs account manager.

Survey Support is configured per app with these settings:

Setting	What it controls
Enabled	Turns the support URL on or off for the app.
Eligible survey statuses	Which outcomes get a support URL, e.g. screenouts only, or screenouts and completes.
Credit cap	The maximum amount a single manual credit can pay out.
Length of interview (LOI)	Limits which surveys qualify, based on their length.

Opened or abandoned survey attempts (OPEN, LEAVE) never get a support URL, even if configured.

Getting the URL

Call Get User History for the user and read support_form_url on each survey entry. Add filter=surveys to return survey entries only.

GET https://api.bitlabs.ai/v1/client/user/history?filter=surveys
X-Api-Token: <your app token>
X-User-Id: <your user id>

The endpoint also accepts token and uid as query parameters. See the Get User History reference for all options.

Example survey entry with a support URL:

{
  "type": "SCREENOUT",
  "tx_id": 123456789,
  "user_value": "0.10",
  "created_at": "2026-10-20T14:03:11Z",
  "duration": "4m",
  "reconciled": false,
  "support_form_url": "https://support.bitlabs.link/bitburst/survey/contact?user_id=<encoded>&tx_id=<encoded>"
}

What to know about the field:

Use it as-is. The user and transaction IDs in the URL are encrypted by BitLabs. Don't build, decode or modify the URL yourself.
It can be missing or empty. Treat a missing, null or empty value as "no help link" for that entry.
It is tied to one attempt. Each URL belongs to the tx_id of its entry. Always use the URL from the entry the user is looking at.

Using the URL

Show a help button on every survey history entry that has a support_form_url, and open the URL when the user taps it.

Render your survey history from the User History response.
For each entry with a non-empty support_form_url, show a button such as "Get help" or "Report a problem".
On tap, open the URL in a new browser tab, or in an in-app browser on mobile.
Refresh the history when the user comes back, so the entry reflects any change.

Don't show the button on entries without the field, and don't fall back to a generic support link for them. BitLabs removes the URL on purpose, for example after an attempt has already been credited.

After the user contacts support

If support approves the request, BitLabs pays a manual credit: the user gets the survey's promised reward, and you receive a callback.

The user submits the support form for one survey attempt.
BitLabs support reviews it against your app's Survey Support settings and the user's account status.
If approved, the user's balance is credited once for that attempt. The amount is the promised reward, capped by your credit cap and converted to your app's currency.
A new MANUAL_CREDIT entry appears in the user's history. The original entry stays a screenout and no longer has a support_form_url.
You receive a callback for the credit.

Example MANUAL_CREDIT history entry:

{
  "type": "MANUAL_CREDIT",
  "tx_id": 123456789,
  "user_value": "250",
  "amount": "1.23",
  "created_at": "2026-10-22T09:30:00Z"
}

user_value is in your app's currency, amount is in USD, and tx_id matches the original survey attempt. The entry is returned with filter=surveys and filter=others.

The manual credit callback

Manual credits are a separate callback type, not a survey complete.

Field	Value
Activity	`SURVEY`
Type	`MANUAL_CREDIT`
Transaction ID	`smc` + the attempt's ID, e.g. `smc123456789`

Which of your callback URLs fire:

Your callback setup	Manual credit callback
Fallback URL only (advanced callbacks off)	Fires
Advanced callbacks, Surveys with type All	Fires
Advanced callbacks, Surveys with type Complete only	Does not fire

If you only listen for completes, add a URL for All, or your users get credited without you being notified. Handle MANUAL_CREDIT separately from completes, since the user did not finish the survey.

FAQ and troubleshooting

No entry has a support_form_url. Survey Support is probably not enabled for your app, or the entries' statuses are not in your eligible list. Ask your account manager to check the settings.

The URL disappeared from an entry. That attempt was already credited. Each attempt can be credited only once, so the help link is removed.

Can I build the URL myself? No. The IDs are encrypted with a key only BitLabs holds. Always take the URL from the API response.

Older integrations used survey_id in the URL. URLs now use tx_id. If you cached or built URLs with survey_id, switch to the value returned by the API. survey_id on history entries is deprecated and mirrors tx_id.

Will a manual credit count as a complete? No. It is reported, billed and called back as MANUAL_CREDIT, and the attempt stays a screenout in history.

Do I earn on manual credits? Yes. You earn your usual share, and manual credits appear as their own line in your billing, separate from completes and screenouts.