header.banner.text
Web Service Documentation / Categories / Reporting Services / Data Response API Guide
Data Response API Guide
How the APIs are organized
The Data Response APIs are designed so that you can respond to data requests on behalf of your customer that you are connected to – similar to how your customer can respond to data requests on their own using the user interface. You can also use the same APIs to respond to data requests in your own account. These APIs interface with data requests so they are only available in the Live environment since creating data requests can only be performed within the user interface. These APIs do not provide functionality to create data requests – only responding to them. The Data Response APIs are designed around two important concepts that you should be familiar with:
- Data Request
- Data Response
Data Request
Your customer must have already accessed the data request and it must appear in their Portfolio Manager account in the Reporting tab. There are no APIs to initially access the data request on your customer's behalf. The unique identifier to a data request will be referred to as the dataRequestId.
Data Response
The steps to responding to a data request follow the same flow if you were responding to a data request in the user interface. Each time you respond to a data request, you need to reference a data response. A data response includes a list of properties that you want to release information for. Each time you generate a data response preview, it will overwrite the previously generated data response preview until it is submitted (i.e., sent). The unique identifier to a data response will be referred to as the dataResponseId.
.Quick Reference Guide
Below is a quick reference guide to responding to a data request for a specific customer. It is assumed that you are connected with the customer and the customer has already accepted the data request.
General Steps to Responding to a Data Request
These steps describe the typical scenario of responding to a data request.
| Step | Method | REST URI | Description |
|---|---|---|---|
| 1. | GET | /reports/customers/(customerId)/dataRequests?status=(status) | Get a list of all data requests for your customer using the customerId. This step can be skipped if you already know the dataRequestId. |
| 2. | GET | /reports/customers/(customerId)/dataRequests/(dataRequestId) | If needed, get details on the data request using the dataRequestId. |
| 3. | POST | /reports/customers/(customerId)/dataResponses | Create/prepare a data response with a list of properties. A dataResponseId is returned. This step can be skipped if you already have active data response that has not been submitted (i.e., sent). |
| 4. | POST | /reports/customers/(customerId)/dataResponses/(dataResponseId)/generate | Generate a preview of the data response using the dataResponseId. |
| 5. | GET | /reports/customers/(customerId)/dataResponses/(dataResponseId)/status | Check the data response preview's status using the dataResponseId until the data response preview is finished generating. |
| 6. | GET | /reports/customers/(customerId)/dataResponses/(dataResponseId)/download?type=(type) | Download the preview of the data response using the dataResponseId. The data response preview is streamed as a file. It is not part of the XML response body. |
| 7. | POST | /reports/customers/(customerId)/dataResponses/(dataResponseId)/send | Submit the data response using the dataResponseId. |
| 8. | GET | /reports/customers/(customerId)/dataResponses/(dataResponseId)/receipt/download | Download the PDF receipt using the dataResponseId. |
Resubmitting a Response for the Same Property
You already submitted (i.e., sent) a data response for a particular property and realized that you need to re-submit a data response again for the same property. To submit another data response for that same property, you need to generate a new preview response, review it, and then submit it. The following outlines the step that needs to be performed.
| Step | Method | REST URI | Description |
|---|---|---|---|
| 1. | POST | /reports/customers/(customerId)/dataResponses | Create/prepare a new data response with a correct list of properties. A dataResponseId is returned. Follow the same steps to generate a data response preview, verify it, and submit the data response. Note that the property referenced in newer data response will overwrite the same property in the previous data response submission. |
Regenerating a Response Preview for a Different Property
You already generated a data response preview that references the wrong property (but haven't submitted it yet) and need to update the data response to reference the correct property. To make sure the data response references the correct property, you need to update that data response with the correct property, review it, and then submit it. The following outlines the step that needs to be performed.
| Step | Method | REST URI | Description |
|---|---|---|---|
| 1. | PUT | /reports/customers/(customerId)/dataResponses/(dataResponseId) | Update the data response with the correct list of properties using the dataResponseId. Follow the same steps to generate a data response preview, verify it, and submit the data response. Note that the property referenced in newer data response will overwrite the property in the previous data response submission. |
