PureSpectrum
PureSpectrum websiteHelp center
PureSpectrum websiteHelp center
  1. Guides
  • Intro
  • API Overview
  • Definitions
  • Survey Lifecycle
  • Create Your First Survey
  • Redirect URLs
  • Changelog
  • HTTP Status Codes
  • API Rate Limits
  • Status Page
  • Quick Integration Steps
  • General Reference Codes
    • Survey Status Codes
    • Respondent Status Codes
    • Survey Category Codes
    • Age Unit Codes
    • Currency Codes
    • Survey Localization Codes
  • Guides
    • Getting Started
    • Quick Start
    • Create Survey Examples
    • Multi-Country Surveys
    • Children Age & Gender
    • Append Respondent Demographics to the Survey Entry Link
    • Test Survey Flow
    • Supplier Blends & Groups
    • Respondent Exclusion / Recontact
    • Survey Exclusion Group
    • Quotas on Clicks
    • Field Evenly Over Time (FEOT)
    • Quota Based Pricing (QBP)
    • Quota Level Complete (QLC)
    • Quota Throttling
    • Templates
    • Bypassing Automatic Variable Mapping
    • Research Defender's Predupe
    • Subscriber Emails
    • Real-Time Notifications (SNS)
    • Reconciliation Guide
  • API Reference
  • Schemas
    • Feasibility
      • Feasibility request schema
      • Feasibility response schema
    • Surveys
      • Create survey full request schema
      • Create survey minimum request schema
      • Create survey response schema
      • Update survey status request schema
      • Update survey status response schema
      • Get survey status response
    • Qualifications
      • Qualification Schema
      • Create qualification request schema
    • Quotas
      • Quota Schema
      • Create quota request schema
      • Create quota response schema
    • Attributes
      • Get attributes response
    • Supplier management
      • Supplier
      • List of all suppliers response
      • List of all suppliers per survey response
      • Update the list of suppliers for a Survey request
      • Update the list of suppliers for a Survey response
    • Other
      • Generic error response
  1. Guides

Reconciliation Guide

This guide walks you through reconciling completes with the Buy API, from choosing an approach to confirming the result.

How reconciliation works#

Reconciliation is how you tell PureSpectrum which completes passed your quality checks. Rejected completes aren't billed. You can reconcile through the API, as this guide describes, or in the PureSpectrum UI.
There are two ways to reconcile, and the request is different for each:
Before close (live or paused survey): you send the completes you reject. Every other complete stays accepted, and the survey can keep fielding.
At close (closed survey): you send the completes you accept. Every complete left out of the request is rejected.
Each request is processed in the background. The response returns an adjustment_id straight away, which you use to check the result.

Rules#

Most reconciliation errors come from one of these rules:
Only completes can be reconciled. Test transactions can't be reconciled.
Each transaction can be reconciled once. After a transaction is accepted or rejected, it can't be changed through the API.
There's a time limit. A transaction can be reconciled until the end of the month after the month it was completed in.

Step 1: Choose an approach#

Choose one approach when you build your integration, and use it for every survey. Both approaches use the same endpoint, but they work differently and need the survey in a different status.
Reconcile before closeReconcile at close
Survey status when the request is sentLive (22) or paused (33)Closed (44)
Transactions sentThe rejected completesThe accepted completes
Completes left outStay acceptedAre rejected
Query parametersoperationType=LIVE_RECONCILIATION and reconStatus=2None
Survey after reconcilingStays live or paused; rejected completes can be replacedStays closed
Requests per surveyAs many as neededOne
Best forRemoving poor-quality completes as they're found, so new respondents can replace themOne final quality check after fieldwork
Closing a survey can't be undone, so plan when your integration closes surveys:
Reconcile before close: send all rejections while the survey is live or paused, and close the survey only after the last rejections. After the survey is closed, further rejections go through your account manager.
Reconcile at close: close the survey once fieldwork and quality checks are finished, then send every accepted complete in one request.

Step 2: Build the list of transactions#

Start from the completes you've reviewed:
1
Remove test transactions
Test transactions can't be reconciled.
2
Remove transactions already reconciled
Each transaction can only be reconciled once.
3
Remove transactions outside the reconciliation window
A transaction can be reconciled until the end of the month after the month it was completed in.
4
Keep the transactions for your approach
Before close: the completes to reject. Add a change_reason to each one.
At close: every complete to accept.
When reconciling before close, change_reason can be Suspected Fraud, Respondent Quality, Ghost Completes, Client Rejected or Duplicate Respondent. Any other value is recorded as Respondent Quality.
When reconciling at close, any complete missing from the list is rejected. Check the list against your full set of accepted completes before sending it.

Step 3: Send the reconciliation request#

Send the list to Survey reconciliation as a JSON array. First check that the survey is in the right status: live (22) or paused (33) to reconcile before close, or closed (44) to reconcile at close. The Get survey information endpoint returns the survey's status.

Reconcile before close#

Add operationType=LIVE_RECONCILIATION and reconStatus=2 to the URL.
Each rejected complete is removed from the quota count, so a new respondent can take its place.

Reconcile at close#

Send the request with no query parameters.

Step 4: Save the adjustment ID#

The response comes back straight away with HTTP 200 OK and a status of Pending:
{
  "status": 1,
  "statusDescription": "Pending",
  "adjustment_id": "abc06685-b59c-4351-8910-ad3870cf7ffd",
  "summary": { ... }
}
1
Store the adjustment ID
You need the adjustment_id in Step 5.
2
Check the summary
The summary shows how many transactions were eligible, and how many were left out as test, alreadyReconciled or invalid.

Step 5: Check the result#

1
Call the status endpoint
Call Get reconciliation status for an adjustment ID with the survey ID and the adjustment ID:
GET https://staging.spectrumsurveys.com/buyers/v2/surveys/{SURVEY_ID}/adjustments/{ADJUSTMENT_ID}
2
Wait while the request is pending
If status is 1 (Pending), wait and call the endpoint again. Most requests finish within a few minutes, but a long list can take up to 20 minutes.
3
Confirm the request succeeded
When status is 6 (Success), the request is complete. The other status values are in the table below.
4
Check individual transactions
To check a single transaction, call Get transaction info (V3) and read Reconciliation Status:
0: not yet eligible to reconcile at close. It can still be reconciled before close.
1: eligible to reconcile.
2: already reconciled.
3: already reconciled before close.
Don't rely on Reconciliation Date: it's currently filled in even when the transaction hasn't been reconciled.
5
Find a request without its adjustment ID
If you didn't store the adjustment_id, call Get status of a reconciliation request to list every reconciliation request on the survey with its status:
GET https://staging.spectrumsurveys.com/buyers/v2/surveys/{SURVEY_ID}/adjustments
The reconciliation status values are:
statusstatusDescriptionWhat it means
1PendingThe request is waiting to be processed
3Message In FlightThe request has been sent for processing
4ProcessingThe request is being processed
5Error In ProcessingThe request couldn't be finished. Send it again.
6SuccessThe request has been processed
7Upload InterruptedThe request stayed Pending for more than 30 minutes and wasn't processed. Send it again.
8Recon Cap ReachedThe request would go over the rejection threshold and wasn't processed. Contact your account manager.
9Waiting for a running processAnother request for the same survey is being processed. This one runs next.
10Success (Partial)Multi survey requests only: some surveys were processed, and others reached the threshold

Step 6: Fix any errors#

If the request fails, find the error below.
If only some of the transactions in the request are ineligible, the request still runs: those transactions are skipped and the rest are reconciled. Compare transactions with eligible in the summary to see how many were skipped.
CodeMessageCauseFix
9999File contains transactions that are ineligible for reconciliation...A test transaction, a transaction already reconciled, a transaction outside the reconciliation window, or a second request on a closed surveyRemove those transactions and send the request again
9999Invalid OperationoperationType has the wrong valueUse LIVE_RECONCILIATION exactly
9999The number of total rejects for this survey exceeds our threshold...The rejections on the survey would go over the thresholdContact your account manager
1006Survey not foundThe survey ID is wrong or belongs to another accountCheck the survey ID and your access token
9999Some transactions belongs to another survey, Please check the requestSome transaction IDs belong to a different surveyRemove them, or use Multi survey reconciliation

Sending several requests#

When reconciling before close, you don't have to send every rejection at once. You can send a request after each batch of quality checks.
You can send a new request before the previous one has finished. Requests for the same survey are queued and processed one at a time. While a request waits, its status is 9 (Waiting for a running process).
Never include a transaction in more than one request. A repeat is left out and counted as alreadyReconciled.
There's no set limit on the number of transactions in a request.
The reconciliation endpoints allow 80 requests per minute per API key.
To reconcile completes from several surveys in one call, use Multi survey reconciliation. It works the same way: add operationType=LIVE_RECONCILIATION&reconStatus=2 to reject completes on live or paused surveys, or send accepted completes with no parameters for closed surveys. If some surveys reach the rejection threshold, the rest are still processed and the status is 10 (Success (Partial)).

The rejection threshold#

There's a limit on how many completes can be rejected on a survey. Your account manager sets it. The threshold:
counts every rejection on the survey, across all requests
is based on the survey's completes
doesn't count rejections made by PureSpectrum
doesn't apply to surveys with fewer than 10 completes
counts every complete left out of a closed-survey request as a rejection
goes up when completes are accepted before the survey closes, because the survey then has more completes
If a request would go over the threshold, it fails with HTTP 400, error 9999 and the message "The number of total rejects for this survey exceeds our threshold and can't be processed." None of the transactions in that request are reconciled. To reject more, contact your account manager.
If this error appears on a closed survey when the request held only a few transaction IDs, the request probably contained rejections. On a closed survey, send the accepted completes.

Fixing a mistake#

Reconciliation can't be undone through the API. If a complete was accepted or rejected by mistake:
1
Note what's affected
Note the survey ID and the transaction IDs affected.
2
Contact Customer Success
Contact Customer Success before the reconciliation window closes.

Test the flow in staging#

Test transactions can't be reconciled, so testing this flow needs real completes. Staging uses the base URL https://staging.spectrumsurveys.com/buyers/v2.
1
Get completes loaded
Ask your PureSpectrum contact to load completes onto a live survey in staging.
2
Test reconciling before close
Reject a few completes and check the result.
3
Close the survey
Closing can't be undone, so finish the before-close tests first.
4
Test reconciling at close
Send the accepted completes and check that the rest are rejected.
See Test Survey Flow for other staging tests.

Overview Diagram#

image.png

FAQ#

Does rejecting a complete reopen the survey?
Can I undo a rejection?
Why didn't some transactions change?
What causes error 9999?
Can I reconcile a closed survey twice?
Is there a limit on transactions per request?
Modified at 2026-11-20 11:09:30
Previous
Real-Time Notifications (SNS)
Next
API Reference