Integration
The contract, before the conversation
This is the whole integration surface: how we send a respondent to you, the four ways a session can end, how callbacks are signed, and how settlement stays correct when both channels fire. Read it before writing to us, not after signing anything.
The usual sequence is an NDA, then a call, then a document. That order wastes the time of every partner who reads the document and discovers their platform cannot do one of the required things. Publishing it inverts the filter: the people who write to us have already checked.
The entry link
We generate a session id per attempt and append it to your template. The placeholders we substitute:
| Placeholder | What it carries |
|---|---|
{SID} | Our session id for this attempt, 32 hex characters, unique and single-use |
{PID} | The respondent id you receive in place of any identity |
{BASE_URL} | Where your redirects come back to |
Nothing else travels. No email address, no name, no device identifier, no IP passed through as a parameter. If your platform requires one of those to run a session, this integration will not work and it is better to find that out now.
Four terminal states, and only four
A session ends in exactly one of these. Your own status codes map onto them in our supplier registry, so you keep whatever vocabulary your platform already uses.
| State | Meaning | What the respondent is paid |
|---|---|---|
complete | Finished and accepted | Full reward |
screenout | Did not match the audience | Fixed smaller amount |
quotafull | Cell already filled | Same as a screen-out |
security | Terminated on a quality or fraud signal | Nothing, and the reason is logged |
There is a fifth internal value, pending, which exists only between entry and callback. It never appears in a redirect and never reaches a landing page.
Callback signing
Every callback is signed. A callback endpoint without a signature is a publicly reachable URL that pays money to whoever types the right query string, and there is no configuration of the rest of the system that compensates for that.
- Take the agreed fields in the agreed order and join them with a pipe character. The field list and order are part of your configuration, not a global constant, because platforms differ on what they can send.
- Sign the result with HMAC-SHA256 using the shared secret. We support MD5 with a trailing secret for older platforms that cannot do otherwise, and we would rather you did not.
- Send it as a parameter alongside the session id and status.
We compare in constant time. A mismatch returns a plain invalid with no detail — not which field was wrong, not what we expected, not whether the session id exists. Any of those turns the endpoint into an oracle that tells an attacker how much closer each attempt got.
Secrets are read from the environment and never checked into anything. A supplier with no configured secret is disabled automatically rather than defaulting to unsigned, because the failure mode of the alternative is silent.
Two channels, one settlement
We accept both a server-to-server postback and a browser redirect, and we expect both to arrive. The postback is authoritative; the redirect exists so the respondent sees an outcome instead of a blank page.
Whichever lands first settles the attempt. Settlement is a single conditional update against an unsettled row, and the affected row count decides what happens next: one means this call settled it, zero means the other channel already did and this one is a duplicate to be acknowledged quietly. Reading the row first and then updating it looks equivalent and is not — under two channels firing at once it pays twice.
The respondent lands on a page carrying the terminal state and your source code, drawn from a bounded set rather than a random token. Random tokens in a landing URL produce thousands of unique addresses in analytics and make the reporting useless.
Before you write to us
Three questions worth answering first, because they decide the rest of the conversation. Can your platform sign a callback with a shared secret. Can it send a server-to-server postback as well as a redirect. And can you map your status codes onto the four states above without losing information.
If all three are yes, [email protected] gets you sandbox credentials and a test study. If one is no, write anyway and say which — some of them we can work around, and it is a shorter conversation than discovering it in week three. The commercial side is on the supply page.