Report Generation

Running a report generates a PDF for each stated portfolio for a given time period. Use the Report Generation API to run reports from outside of Addepar, publish reports to the Client Portal, and notify clients when their report is available.

Overview


Base route	`/v1/report_generation_job`
Produces	JSON
Pagination	No
OAuth scopes	`REPORTS_WRITE`

Access requirements

API Access: Create, edit, and delete. Access to all tools and portfolios.

Resource overview

The Report Generation API returns a resource object containing the Report Job ID in successful POST responses.

Attribute	Description
`job_id`	The unique id of the report generation job. String. Example: `"b37e4e27-14b8-486c-b2c9-d0d6c9991fcb"`

Parameters

Required parameters

You can request a report generation job by providing the below resource object attributes.

Attribute	Description
`report_id`	The ID of the report that you want to run. Integer. You can find a report's ID in its Addepar web application URL. Example: `4`. Returns `400 Bad Request` if missing `report_id`. Returns `404 Not Found` if you don't have access to the report, or the report was deleted.
`portfolios`	The list of entities or groups that you want to run reports for. The provided portfolios can be associated with the report, but don't need to be. JSON object. For each portfolio, provide both: `portfolio_type` (either "entity" or "group", String) and `portfolio_id` (the portfolio's Entity ID or Group ID, String). Example: `[{"portfolio_type": "entity", "portfolio_id": "22"}, {"portfolio_type": "group", "portfolio_id": "3"}]`. Returns `400 Bad Request` if missing portfolio type, missing portfolio ID, or if the types for the request are not supported.
`start_date`	The report's start date. String, formatted as YYYY-MM-DD. Cannot be later than `end_date`. Example: `"2023-07-01"`. Returns `400 Bad Request` if `start_date` is on or after `end_date`.
`end_date`	The report's end date. String, formatted as YYYY-MM-DD. Cannot be earlier than `start_date`. Example: `"2023-08-01"`. Returns `400 Bad Request` if `end_date` is on or before `start_date`.

Optional parameters

Attribute	Description
`portal_publishing`	Determines if the report should also be published to Portal. Values: `PUBLISH`, `DO_NOT_PUBLISH`, `USE_CONTACT_PREFERENCE`. You must specify a `contact_notification` when publishing to Portal. Example: `"portal_publishing": "PUBLISH"`. Returns `400 Bad Request` if `portal_publishing` is set to `PUBLISH` or `USE_CONTACT_PREFERENCE` and `contact_notification` is not provided.
`contact_notification`	When the report is published to the Portal, this determines if the contact is notified. Values: `NOTIFY`, `DO_NOT_NOTIFY`, `USE_CONTACT_PREFERENCE`. You must specify `portal_publishing` when notifying a contact. Returns `400 Bad Request` if the value is invalid or if the request is missing the `portal_publishing` attribute.
`label`	List the label IDs you'd like to attach to the generated PDF. Labels must already exist in Addepar. Example: `"label": [1,2,3]`. Returns `400 Bad Request` if the label doesn't exist in Addepar or if the label is invalid.
`brand_id`	Determines the color palette used on charts in the report. The value provided on this parameter is actually a `team_id` and the associated brand will be fetched. If the parameter is not included in the request or is NULL, the default will be determined based on the combination of report access and firm settings. Example: `"brand_id": "12345"` or `"brand_id": "-1"` (firm palette). Returns `404 Not Found` if you don't have access to the team. Returns `400 Bad Request` if it's an invalid request based on the configurations.

Run a report

Requests to generate a report PDF for each associated and specified portfolio.

POST /v1/report_generation_job

Authentication

This endpoint requires an OAuth token with the REPORTS_WRITE scope. Pass the token in the Authorization header as Bearer {token}.

Example:

curl -X POST 'https://{firm}.addepar.com/api/v1/report_generation_job' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Addepar-Firm: {firm_id}' \
  -d '{
    "data": {
        "type": "report_generation_job",
        "attributes": {
            "report_id": "5",
            "portfolios": [
                {
                    "portfolio_type": "entity",
                    "portfolio_id": "22"
                }
            ],
            "start_date": "2023-07-01",
            "end_date": "2023-08-01",
            "portal_publishing": "PUBLISH",
            "contact_notification": "NOTIFY",
            "label": [1,2,3]
        }
    }
}'

{
    "data": {
        "id": "b37e4e27-14b8-486c-b2c9-d0d6c9991fcb",
        "type": "report_generation_job_id",
        "links": {
            "self": "/v1/report_generation_job_id/b37e4e27-14b8-486c-b2c9-d0d6c9991fcb"
        }
    },
    "included": []
}

Response codes

200 OK -- Success
400 Bad Request -- Incorrect or missing parameters. See parameter tables for more information.
403 Forbidden -- You don't have the correct reporting or Portal permission to complete a certain action in Addepar. Reach out to your Addepar firm administrator.
404 Not Found -- The requested report was not found.

Check job status

After submitting a report generation request, poll the Jobs API to check whether the report has finished generating.

curl -X GET 'https://{firm}.addepar.com/api/v1/jobs/{job_id}' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Addepar-Firm: {firm_id}'

The job status will be one of: processing, completed, or failed. Once completed, the generated report PDF is available via the Generated Reports API.

Related resources

Report List -- Retrieve report IDs for use with this endpoint.

Generated Reports -- Access completed report PDFs.

Jobs -- Poll for job completion status.