Flashpoint.AIFlashpoint.AIdocs

Integrate your API

For partners we expect to field with continuously. We build an adapter against your API, and your panel appears directly in the buyer's targeting interface — they select your audience, see feasibility and price, approve, and watch it field, without leaving Flashpoint.AI.

This page sets out how the project runs and exactly what we need from you. Most of it is questions rather than requirements. Sample APIs differ enormously in shape — study-based, project-and-line-item, quota-group — and we don't need yours to look like anything in particular. We need to know its shape precisely before we write against it.

What you get

  • Demand from the buyer's own workflow. Buyers reach your panel while designing the study, not by filing a request with an account team.
  • Clean traffic. Every entrant is screened for fraud and duplication before they start, and returned to you on a dedicated leg if blocked.
  • Correct outcome reporting. Five distinct return codes, including over-quota as its own event.
  • Reconciliation through your API where you support it, rather than as a spreadsheet emailed to your account team.
  • Real inputs to your pricing. We pass our incidence and length-of-interview estimates at quote time, so a floor price computed from IR, LOI and country is computed from honest numbers.

How the project runs

StageWhat happensTypical duration
0. Spec exchangeYou send API docs (and an OpenAPI spec if you have one). We return a written gap analysis against this page.2 working days
1. Staging accessYou issue staging credentials. We run a read-only probe to confirm the answers empirically.2–3 days
2. BuildWe write and test the adapter. We'll come back with questions; a named engineering contact on your side keeps this short.1–2 weeks
3. CertificationJoint walk-through of the test script below, on staging.2–3 days
4. Soft launchA small live buy at reduced quotas, watched closely by both sides.1 week
5. Generally availableYour panel appears in the picker for all teams.—

The slowest stage is almost always 0 — not because the questions are hard, but because they're usually spread across several people. Nominating one technical owner on your side typically halves the timeline.

1. Operations

OperationWhat we use it forRequired
Create project / studySet up the buy in draft, without spendingYes
LaunchGo liveYes
Pause / resumeStop and restart spend mid-fieldYes
StatusLive counts: completes, starts, in-progress, screen-outs, over-quotaYes
Close / completeEnd fieldwork cleanlyYes
Feasibility"Can you deliver 800 of this audience?"Yes — mechanism flexible
PricingA cost we can charge againstYes — mechanism flexible

Feasibility and pricing are capabilities we require, but the mechanism is yours to choose. Neither has to be an API endpoint. What we can't do is sell sample we can't size and can't cost — a buyer who pays for a study that never fills is a refund and a lost client, and we won't put a partner in that position either.

Feasibility — required, mechanism flexible

Before we take a buyer's money we have to answer "will this fill?". We accept any of three mechanisms:

  1. A feasibility endpoint. Preferred.
  2. A documented soft-launch protocol. Launch at reduced quotas, read the result, then scale or stop. It costs money but it gives a true answer, and it's what several exchanges recommend themselves. If this is your model, we need the protocol written down — what percentage, how long to wait, what signal means "go".
  3. A committed human response time. Your team answers a feasibility request within a stated number of working hours, on a channel we can build a process around.

What we can't work with is none of the three.

If you do have an endpoint:

  • Does it need an object created first? Some APIs have no pre-project feasibility — it exists only on a draft project, so asking the question creates something. If that's your model, say so; it changes how we clean up abandoned quotes.
  • Synchronous or polled? If polled, tell us the states and a sensible backoff.
  • Chargeable or rate-limited? We'd like to probe several locales to learn which are live. If that's abusive on your side, tell us the budget.
  • Is the number a pool size or a deliverable estimate? These are routinely conflated and they are not the same thing. "How many panelists match these filters" and "how many completes we can deliver" are different numbers, and payloads rarely distinguish them. Quoting the first to a buyer as though it were the second over-promises badly, so please say which you return.
  • Does it account for price, LOI and quotas, or targeting alone? Raising the CPI usually changes the answer, so a feasibility that ignores price tells us much less.

Of our normalised result, which can you populate?

FieldMeaning
feasibleCan this be delivered at all
estimated_completesHow many — pool or deliverable, per above
estimated_irExpected incidence
estimated_loiExpected length of interview
estimated_daysTime to fill
country_availabilityWhich requested markets are live

And one that matters more than it first appears: how do you signal "I can't answer" as distinct from "the answer is zero"? A market your engine doesn't model and a market with no panelists are different facts. Collapsing them means we tell a client a country is dead when it isn't. An explicit refusal for locales you can't predict in is the right behaviour. If you return 0 for both, we need to know, so we never report it as unavailability.

Pricing — required, and here's exactly why

We cannot show a buyer a quote, or take a payment, without a cost for the buy. This isn't a preference — a provider with no cost signal cannot be sold through the product at all.

Three sources work, in order of preference:

  1. A cost returned with feasibility, or a dedicated pricing endpoint. Common on exchanges, and the simplest for everyone — feasibility and pricing become a single integration rather than two.
  2. A cost calculator. We name an offer price, you return the all-in total including your fees. Suits models where the buyer sets the incentive.
  3. A rate card you give us, which we hold. Entirely workable, but it must arrive before launch, not after. We need:
    • CPI by country × LOI band × IR band
    • The premium for niche or low-incidence targeting, as a multiplier or an absolute
    • Currency, and whether the figure is all-in or exclusive of your fee
    • Validity period, and who notifies whom when it changes

A floor price you enforce internally but don't expose is not a pricing mechanism — we can't read it, so we can't quote from it. If that's your situation today, option 3 is the fix.

Floor prices

If you derive a floor price from incidence rate, length of interview and country — as most exchanges do — one answer matters above all others:

Is the floor enforced, or advisory?

If it's enforced, a buy priced below it fails at creation, we see the error, and we correct before anyone is charged. If it's advisory, an under-priced survey goes live and quietly under-fills: we can't detect that from the API, the buyer has already paid, and the first signal is a study sitting at 30% a week later. It materially changes how we build the pricing path.

Changes once it's live

Which of these can change mid-field, and do they apply to traffic already in flight?

  • Sample size / completes wanted
  • Price per complete
  • Quota cell targets
  • Targeting criteria
  • Field end date

Price especially. If the remedy for slow fill is "raise the CPI", we need to do that through the API rather than by email.

2. Authentication and request semantics

We need service credentials, not a human login. An integration authenticating as a named person's email and password breaks when that person leaves, rotates, or enables MFA.

  • Credential type (OAuth2 client credentials, API key, signed request) and the token endpoint
  • Exact Authorization header format, including whether a Bearer prefix is expected — some APIs take the raw token and reject the prefix
  • Token lifetime, and whether there's a refresh endpoint or we re-authenticate
  • Any rate limit on token minting. Worth flagging early: we run multiple API replicas and a deploy restarts them together. If minting is capped per credential per hour, we need a shared token cache to avoid locking ourselves out. Knowing in advance makes it a design decision instead of an incident.
  • Separate credentials for staging and production
  • Rate limits per endpoint family, and the response shape on 429

Idempotency. Creating a project and launching it are the two calls where a network timeout is genuinely dangerous — we don't know whether it landed, and a blind retry can create a second live buy spending real money. Do you accept an Idempotency-Key header, or another safe-retry mechanism, on creates and launches? If not, we'll build a read-back-before-retry path instead.

Error semantics. Which responses are retryable and which are terminal? A 400 that actually means "try again in a moment" — for instance a draft that reads back empty for a second after a successful write — is worth documenting rather than leaving us to discover.

3. How your objects map to a study

Our unit is a survey, which may run in several countries and languages at once.

  • What is the unit that actually fields — a study, a line item, a target group, a stream?
  • Is it scoped to one country and one language? If so, a single multi-market study of ours becomes several objects on yours. We need to know how they're grouped, and whether quotas and exclusions span them.
  • Is there a container above it we also have to create?
  • Which identifiers must we store to operate the buy afterwards? Some APIs need both a parent and a child id on every subsequent call.

4. Entry links

We generate the survey URL. You append or substitute your respondent identifier.

  • The exact placeholder token for the respondent id (for example [%RID%], {psid}, %rdud%), and whether it's case-sensitive
  • If you've retired an older token, please say so explicitly, and tell us which pages of your documentation are out of date
  • Can you pipe qualification answers into the entry link? If a respondent has already told you their age and gender, we'd rather not ask again: it costs LOI and it annoys panelists. What's the syntax, and which qualifications are available?
  • Any URL length limit, and is HTTPS required?
  • What happens if the same respondent id re-enters — resume, or duplicate?
  • Do you support device targeting (desktop / tablet / mobile), and is it enforced on your side or expected to be ours?

5. Targeting and filters

This is where most of the integration effort goes.

The demographics we always map

These are the canonical keys buyers use. We need your equivalent for each — attribute or question id, and the option codes.

Canonical keyNotes
age / age_min / age_maxUsually a range rather than banded options
genderTell us if your question has only two options, so we warn rather than mistarget
household_incomeBanded, and bands differ per market
education
employment_status
employment_sectorIndustry, where available
ethnicity / race
hispanic / originOften a multi-option origin question rather than yes/no
marital_status
household_compositionHousehold size
parental_status / has_children
student_status
languageFirst or spoken language
nationalityWhere distinct from country of residence
countryISO 3166-1 alpha-2 preferred
us_state, us_region, zipAnd equivalents for other markets

Anything beyond this list we resolve at request time from your catalogue rather than hard-coding, so the catalogue endpoint matters as much as the standard list.

How conditions are expressed

  • Condition types: selection from a list, numeric range, open-ended value list (ZIP or postcodes), derived? We need to know which type each attribute is — they serialise differently.
  • Boolean semantics, precisely: within one attribute, are multiple options OR-ed? Between attributes, AND-ed? Is there negation?
  • Is there a limit on conditions per survey, or a point past which feasibility collapses?
  • Are some attributes usable only for screening and others only for quotas? If you expose separate flags, tell us which is which — reading the wrong one silently drops valid targeting.
  • Can we send a raw, vendor-native targeting payload as an escape hatch when a buyer needs something our canonical mapping doesn't cover?

Catalogue stability

  • Endpoint for the full attribute / qualification catalogue, with option codes
  • Are ids stable across locales, or does each market renumber? If question ids are global but option codes are per-market, say so — it decides whether we can cache a static map or must resolve per market.
  • How often does the catalogue change? Is there a changelog or version?
  • Countries and languages, and critically which combinations you can actually field rather than sell into. A locale in a catalogue is not the same as a locale with panelists behind it, and a market quoted in the wrong language can succeed quietly while fielding the wrong people.

6. Quotas

  • Can you enforce quotas at all, or do you send undifferentiated traffic and expect us to terminate over-quota respondents?
  • Are cell targets counts or percentages?
  • Do you support interlocked cells (age and gender in one cell), or only independent dimensions?
  • Can quota targets change mid-field?
  • When a cell fills, do you stop sending matching respondents, or do they keep arriving for us to bounce?
  • Is there a cap on the number of cells?

Anything you can't field, we enforce ourselves — targets hold either way. The difference is efficiency: a split you can't field means respondents reach the survey and get screened out, which wastes your sample and bounces panelists for nothing.

7. Return legs

When a respondent finishes we redirect them back to you. We need to signal five outcomes distinctly:

OutcomeMeaning
CompleteFinished and qualified
Screen-outFailed a screener question
Over-quotaQualified, but their quota cell was already full
Quality terminateFailed a data-quality check
Security terminateFailed a fraud check

Over-quota must not collapse into screen-out. They are commercially different events. A respondent who qualified and hit a full cell is not a screener failure, and merging them corrupts the incidence rate on both sides of the trade — which then misprices the next wave and misreports to your suppliers. If your protocol genuinely has no over-quota code, tell us and we'll record the limitation rather than silently mislabel.

Quality and security must be separable from an ordinary terminate. A quality flag affects a panelist's reputation score and can trigger supplier disputes. We don't emit one without a real signal, and we'd ask that you don't treat our ordinary terminates as quality events either.

For each outcome:

  • The exact URL, or the single URL plus the distinguishing code
  • Parameter names, and whether order matters
  • The signing scheme, if any — algorithm, precisely which string is signed (full URL? path and query? which parameters, in what order?), whether a secret is included in the signed string but excluded from the sent URL, the parameter carrying the hash, and where we obtain the secret
  • Whether signing is account-level opt-in. If it can be enabled later, we want to know now — the failure mode is every respondent bouncing at once.

A worked example with a real signature we can reproduce is worth more than a page of prose.

8. Status delivery

In order of preference: server-to-server, then webhooks, then polling.

Server-to-server

What we'd rather use. The respondent's browser is an unreliable carrier — redirects get lost, blocked and spoofed, and a lost one is a ghost complete. If you accept a server-side status post we'll use it and treat the redirect as confirmation.

  • Endpoint and auth. Is it the same credential as the main API, or a separate key?
  • The status code values — and whether they share a namespace with your redirect codes. Overlapping numeric namespaces are common: the same integer meaning one thing on a redirect and another on a status post. If yours differ, please flag it clearly; if they're identical, say that too.
  • Ordering. Do we post before or after redirecting the browser? And does a successful post change which URL we should redirect to — some protocols send an acknowledged respondent to a different confirmation URL.
  • What does a 200 mean — accepted, or committed?
  • Idempotency and replay: what happens if we post the same respondent twice, or post after a redirect already landed?
  • Your p99 latency. This sits on the respondent's submit path, so we hold it to a hard timeout and fall back rather than make a panelist wait.
  • Is there a validation endpoint — "is this respondent genuinely in-survey right now?" We use that to catch replayed or fabricated respondent ids before accepting a complete, and it's one of the more valuable things an API can offer.

Webhooks

Which events, what retry policy, how the payload is signed, and whether we can register the endpoint through the API or your team configures it.

Polling

Rate limit, pagination model, and how quickly data is consistent after a respondent finishes.

9. Test traffic

We QA every survey before it fields, and we won't do that against live panelists.

  • Is there a test or preview link that walks entry and return without spending or touching real supply?
  • Can we exercise all five return legs on staging and see the outcome recorded on your side?
  • Does staging have a usable qualification catalogue, or is it empty?
  • Can a staging survey be launched, paused and closed like a real one?

10. Exclusions and recontact

  • Can we exclude respondents who took a previous wave, by respondent id?
  • Can we recontact a specific list of respondent ids for a follow-up?
  • How long are respondent ids stable — across a project, or for the life of the panelist?
  • Is there deduplication across sources within one survey?

11. Reconciliation and billing

We run fraud and data-quality screening and exclude respondents after fieldwork, so:

  • Can we push rejections back via API? Without it we pay for respondents we've already discarded, and cleanup becomes a spreadsheet emailed to your account team.
  • What's the reconciliation deadline, and is there a rejection-rate cap before it needs a conversation?
  • Do you report per-respondent cost? That makes "did we under-price this?" answerable with data rather than at invoice time.
  • Do you report your own terminates — respondents rejected before they reached our survey — granularly enough to tell fraud from a closed quota?
  • When does a complete become billable, and when is it final? On redirect, on acknowledgement, or at reconciliation close? This decides when we can settle with the buyer.
  • Do you measure and report actual IR and LOI? That's the input to pricing the next wave.

12. Commercial, legal and operational

  • Coverage and specialisms. Markets, approximate reach per market, and any sector or audience you're genuinely strong in — B2B, healthcare professionals, IT decision-makers, automotive, finance, low-incidence medical. Buyers ask us for these by name, and a panel that can reach one reliably gets routed work an exchange can't service.
  • Staging and production base URLs, and whether staging can create, launch and return test traffic
  • Support contact and escalation path for live fieldwork, with hours
  • Invoiced or per-transaction billing, and settlement currencies
  • Whether an existing agreement with us covers API access or it needs a separate contract
  • Data protection: your DPA, the controller/processor split, data residency, and the basis on which panelists consent to third-party research
  • Any survey content review or category restrictions before fielding

The checklist

Answer in whatever format suits you — a document, a spreadsheet, or inline in an email. We'll take any of them.

#Question
Auth
1Service credentials available (not a personal login)? Auth type and token endpoint?
2Token lifetime, and any rate limit on minting tokens?
3Exact Authorization header format — Bearer prefix or raw?
4Idempotency key accepted on create and launch?
Commercial
5Feasibility mechanism: endpoint, documented soft launch, or SLA'd human answer?
5aIf an endpoint: does it require creating a draft object first?
6Feasibility synchronous or polled? Rate-limited or chargeable?
7Does feasibility return a pool size or a deliverable estimate?
8Which of feasible, completes, IR, LOI, days, availability can you populate?
9How do you distinguish "can't answer" from "zero available"?
10Pricing mechanism: cost with feasibility, a cost calculator, or a rate card you give us?
10aIf a rate card: CPI by country × LOI × IR, niche premium, currency, validity
11If there's a floor price: enforced or advisory?
12Can price, sample size and quotas change mid-field, and does it apply to live traffic?
Structure
13What object fields — is it scoped to one country and one language?
14Which ids must we store to operate the buy afterwards?
Entry
15Exact respondent-id placeholder for the entry link
16Can qualifications be piped into the entry link? Syntax?
17Device targeting supported, and enforced by whom?
Targeting
18Attribute/question ids and option codes for the standard demographics list
19Condition types supported (selection, range, open-ended list)
20Boolean semantics: OR within an attribute, AND between, negation?
21Are ids stable across locales, or does each market renumber?
22Screening-only vs quota-eligible attributes — separate flags?
23Country × language combinations you can genuinely field
Quotas
24Can you enforce quotas, or is it all our side?
25Counts or percentages? Interlocked cells supported?
26When a cell fills, do you stop sending matching respondents?
Returns
27Return URL or code for each of: complete, screen-out, over-quota, quality, security
28Redirect signing: algorithm, exact signed string, secret source, hash parameter
29Is signing account-level opt-in?
Status
30S2S, webhook, or polling? Endpoint and auth
31If S2S: do status codes share a namespace with the redirect codes?
32If S2S: post before or after redirect, and does it change the redirect URL?
33If S2S: idempotency, p99 latency, and is there a respondent validation endpoint?
34If polling: rate limit and pagination
Data
35Can we push reconciliation rejections back? Deadline and caps?
36Is per-respondent cost reported?
37When does a complete become billable and final?
38Are actual IR and LOI reported back?
Operations
39Test/preview link exercising entry and all five return legs without spending
40Staging environment that can create and launch
41Respondent exclusion and recontact by id — supported?
42Support and escalation contact for live fieldwork
42aSector or audience specialisms, and approximate reach per market
43DPA, data residency, controller/processor split
44Any survey content review or category restrictions

Certification

Before going live we walk this jointly, on staging, with real test traffic:

  1. All five return legs, each confirmed as the correct outcome on your side
  2. A complete that attributes and bills correctly
  3. An over-quota recorded as over-quota, not as a screen-out
  4. Pause genuinely stopping spend, and resume restarting it
  5. Quota cells filling and closing as expected
  6. A reconciliation rejection round-tripping, if supported
  7. Status counts on your side matching ours

We share the script in advance and run it together.

Get started

Email developers@flashpoint.ai with your API documentation — and an OpenAPI specification if you have one, which shortens the first pass considerably. We'll come back within two working days with a written gap analysis against this page.

If you'd rather prove the commercial fit before committing engineering time on either side, send us traffic first. It's live the same day and nothing about it blocks this route later.

Next steps