Create Requests
Adding Requests to a Collection is achieved by making an HTTP PUT to the /collections/COLLECTION_ID endpoint (where COLLECTION_ID is the id of the Collection to add Requests to). The body of the request should be a JSON array of request objects (up to 1000 Requests can be added per call). The maximum number of Requests per Collection is 15,000 (or 100 when adding requests with include_html=true set).
The /collections/COLLECTION_ID endpoint used for adding Requests to a Collection is the same endpoint as used when Updating a Collection, we've just listed them seperately in the Docs for ease of reference.
The parameters for creating a Request are the same as those used when making a request via the Home Improvement Product API.
Collection Status Requests can only be added to a Collection when the Collection is not running. To check whether a Collection is currently running use the Get Collection endpoint.
Concurrency when Creating Requests You should make calls to the Create Request endpoint sequentially, rather than in parallel. Each call can contain up to 1000 Request to add though. If you make too many concurrent calls you will receive an HTTP 429 error.
Using include_html=true in Collections When adding requests with include_html=true to a Collection the maximum number of requests per Collection is 100 (rather than 15,000) because including the HTML within the response makes the Collection Result Sets much larger. The limit is in place to ensure Result Set files are of a manageable size. If you have need to run a large number of requests all with include_html=true then simply split the requests across multiple 100-request Collections.
PUT /collections/COLLECTION_ID
In the example below we add a new Request to a Collection with id=123456 :
Custom IDs When you add a Request to a Collection Backyard API assigns it an unique id - you can use this id to track the Request across multiple Result Sets.
Backyard API also lets you specify your own custom_id , in addition to the Backyard API-assigned id, making it easy to use an ID from your app track Requests.
Backyard API responds with the following JSON confirming the Requests have been successfully created. Note the requests_total_count now reflects the count of the Requests the Collection has, including those just added. To List the Requests in the Collection use the List Requests endpoint:
Next Steps Update Request Delete Request List Requests