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 close | Reconcile at close |
|---|
| Survey status when the request is sent | Live (22) or paused (33) | Closed (44) |
| Transactions sent | The rejected completes | The accepted completes |
| Completes left out | Stay accepted | Are rejected |
| Query parameters | operationType=LIVE_RECONCILIATION and reconStatus=2 | None |
| Survey after reconciling | Stays live or paused; rejected completes can be replaced | Stays closed |
| Requests per survey | As many as needed | One |
| Best for | Removing poor-quality completes as they're found, so new respondents can replace them | One 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#
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.
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:| status | statusDescription | What it means |
|---|
| 1 | Pending | The request is waiting to be processed |
| 3 | Message In Flight | The request has been sent for processing |
| 4 | Processing | The request is being processed |
| 5 | Error In Processing | The request couldn't be finished. Send it again. |
| 6 | Success | The request has been processed |
| 7 | Upload Interrupted | The request stayed Pending for more than 30 minutes and wasn't processed. Send it again. |
| 8 | Recon Cap Reached | The request would go over the rejection threshold and wasn't processed. Contact your account manager. |
| 9 | Waiting for a running process | Another request for the same survey is being processed. This one runs next. |
| 10 | Success (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.
| Code | Message | Cause | Fix |
|---|
| 9999 | File 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 survey | Remove those transactions and send the request again |
| 9999 | Invalid Operation | operationType has the wrong value | Use LIVE_RECONCILIATION exactly |
| 9999 | The number of total rejects for this survey exceeds our threshold... | The rejections on the survey would go over the threshold | Contact your account manager |
| 1006 | Survey not found | The survey ID is wrong or belongs to another account | Check the survey ID and your access token |
| 9999 | Some transactions belongs to another survey, Please check the request | Some transaction IDs belong to a different survey | Remove 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.
Overview Diagram#
FAQ#