Use asynchronous invocation when a supported list request may take too long to complete synchronously. Start the job with POST {base_url}/async, store the returned reportKey, and poll GET {base_url}/async/{REPORT_KEY}/poll no more than once every 10 seconds until the server returns HTTP 200.

Standard, synchronous invocation of List methods may time out for larger data sets. In order to support these larger data sets, the API collections which may encounter this problem allow for asynchronous invocation. Those API collections which do support asynchronous invocation are documented below in each collection under the List method documentation.

In order to invoke the asynchronous List method, add the follow url suffix after the base method for the particular collection:

POST {base_url}/async?{query_parameters}

For example, to list punches, base_url would be /punches.

This POST call should return HTTP status 202, with a response body in the following format:

{ "success": true, "reportKey": "{REPORT_KEY}" }

Using the REPORT_KEY, you may then poll for the results at:

GET {base_url}/async/{REPORT_KEY}/poll

If poll returns HTTP status 202, that means the server is still processing the result, and you should try again later. When poll returns HTTP status 200, then the report is complete, and the response body will contain the result.

You should not poll more frequently than once every 10 seconds. Each poll call does count toward throttle.

FAQ

When should I use async instead of a normal GET list request?

Use async when a supported collection may return enough data to risk timing out during a normal synchronous list call.

What does HTTP 202 mean during async polling?

HTTP 202 Accepted means the report is still being generated. Continue polling later using the same reportKey.

How often should I poll for async results?

Do not poll more often than once every 10 seconds, and remember that each poll request still counts toward throttling limits.