Bulk SkipTrace API

Overview

The SkipTraceBatch API will allow you send up to 1,000 skip requests at a single time.

Benefits of using this API include higher throughput, and a decrease in the likelihood you will receive rate limiting errors.

By using this API, you are able to leverage our queuing architecture which uses a first in - first out queueing strategy.

General Endpoint Rules

The minimum number of skip request objects you can send is 10.
The maximum number of skip request objects you can send is 1,000.
The maximum size of the payload is 256KB. You will receive a 400 Bad Request response if the payload size is greater than 256KB.
key is required for each skip request item in the array of requests. key is an internal number that your system uses to identify and relate each request back to an associated record in your data. key must be unique for each item in the batch. key can be an integer value or a string value.

Input

`webcomplete_url`

webcomplete_url must be a valid https POST endpoint. The webhook_url should return a https status of 200. The response body can be empty.
webcomplete_url will be called once after all items in the batch have been processed and sent to your webhook_url. The call to this endpoint will signify that the entire batch has been processed. It will include statistics about the job such as total match, error, and processed counts.
- Note: webcomplete_url is not required. If a webcomplete_url is not passed, we will not attempt to send a completion message.
- webcomplete_url will be called with the same x-api-key header and key value so that you can be sure or the origination of the request.

`webhook_url`

webhook_url must be a valid https POST endpoint. The webhook_url should return a https status of 200. The response body can be empty.
- webhook_url will be called individually for all items in the batch. If you pass 1,000 request items, the webhook_url will be called 1,000 times. It will call your API at most 50 queries per second. If you need additional throttling, let us know and we can add an additional throttle to slow down calls to your url.
- New: webhook_url will be called with the same x-api-key header and key value so that you can be sure or the origination of the request.
You can use different webook_urls per item for additional specification you need. For instance, you could include a query string with meta data to pass back to your system.

Responses

Initial API Response / Acknowledgement

The Batch request will return an acknowledgement that the batch job has begun.

batchId is the unique task id in our system that can be used to trace the progress of batch request.

receiveCount is a validator you can use to ensure our system is processing the expected number of transactions based on the unique keys that were sent in the batch.

batchRequestIds is an array of your unique keys along with the associated unique batchRequestId our system generated to track each individual skip trace result in the overall batch.

Webhook Responses

Your webhook_url will be provided a POST request for each item in the batch array will include the batchId, batchRequestId, and the internal key that was provided in the POST body so that you have the best opportunity to match the webhook response to the associated record in your data... as well as validate the overall batch.

Note that key is included in the input object as input.key.

requestId is the id assigned by the skip trace process and returned from the single transaction based /SkipTraceAPI process.