Generated Reports

The Generated Reports API provides access to generated report objects representing the metadata associated with a single completed run of a report generation job.

A report generation job is initiated from the Addepar web application or the Report Generation API and generates report PDFs for the portfolios associated with a given report.


Base route	/v1/generated_reports
Endpoints	GET /v1/generated_reports/:id /v1/generated_reports/:id/creator /v1/generated_reports/:id/zipped_file /v1/generated_reports/:id/zipped_file/download
Produces	JSON
Pagination	Yes
OAuth Scopes	`FILES` for all except /v1/generated_reports/:id/creator, which requires `FILES` and `USERS`
Application Permissions Required	"Access to all tools and portfolios."

Resource Overview

All attributes will be returned in successful GET responses.

Attribute	Type	Example
`report_id`	The unique id of the report for which the report generation job was run.	`46`
`report_name`	The name of the report for which the report generation job was run.	`"Quarterly Performance Report"`
`status`	The status of the completed job. Either, `FINISHED`, `ERROR`, or `CANCELED`. `ERROR` is due to system failure. `CANCELED` is an action taken by a user. Both these statuses might still result in one or more successful portfolios.	`"ERROR"`
`started_at`	String representing the time instant in UTC at which this report generation job was started.	`"2021-02-14T10:15:30.00Z"`
`completed_at`	String representing the time instant in UTC at which this report generation job finished.	`"2021-02-14T14:25:45.00Z"`
`generated_portfolios`	An array of objects providing information of successfully generated portfolios. Includes portfolio type, portfolio id, portfolio name, and file id.	`"generated_portfolios"`
`portfolio_type`	One of entity or group.	`"entity"`
`portfolio_id`	Unique id of the portfolio.	`21`
`portfolio_name`	Name of the portfolio.	`"Tony Stark"`
`file_id`	Unique id of the generated file. It can be used to download the actual binary file from `GET /v1/files/:id/download`.	`101`
`failed_portfolios`	An array of objects providing information of failed portfolios during report generation. Includes portfolio type, portfolio ID, and portfolio name.	`"failed_portfolios"`
`portfolio_type`	One of entity or group.	`"entity"`

Relationships
`creator`	The user who created the report generation job that generated the associated files.

Optional Parameters

Parameter	Description	Example
filter[completed_after]=YYYY-MM-DDTHH:MM:SSZ	Returns jobs run after this date. The timestamp is in UTC.	`[completed_after]=2021-05-14T12:03:39Z`
filter[completed_before]=YYYY-MM-DDTHH:MM:SSZ	Returns jobs run before this date. The timestamp is in UTC.	`[completed_before]=2021-05-14T12:03:39Z`
filter[status]=[FINISHED, ERROR, CANCELED]	Returns jobs by status. Filter by one or more of the following: `FINISHED` - done running `ERROR` - report ended in an error with one or more jobs failing `CANCELED` - A user stopped the job while it was in progress	`[status]=FINISHED,ERROR`

Get all generated reports

Retrieves all generated reports that a user is authenticated to view, sorted in reverse chronological order of completion time.

GET /v1/generated_reports/

GET https://examplefirm.addepar.com/api/v1/generated_reports

200 OK: Success

{
  "data": [
    {
      "type": "generated_reports",
      "id": "A-UUID-ASSOCIATED-WITH-EACH-RUN",
      "attributes": {
        "report_id": 42,
        "report_name": "Quarterly Performance Report",
        "status": "ERROR",
        "started_at": "2021-02-14T10:15:30.00Z",
        "completed_at": "2021-02-14T14:25:45.00Z",
        "generated_portfolios": [
          {
            "portfolio_type": "entity",
            "portfolio_id": 21,
            "portfolio_name": "Tony Stark",
            "file_id": 101
          },
          {
            "portfolio_type": "group",
            "portfolio_id": 31,
            "portfolio_name": "Avengers",
            "file_id": 102
          }   
        ],
        "failed_portfolios": [
          {
            "portfolio_type": "entity",
            "portfolio_id": 22,
            "portfolio_name": "Thanos"
          },
          {
            "portfolio_type": "group",
            "portfolio_id": 32,
            "portfolio_name": "Chitauri"
          }   
        ]
      },
      "relationships": {
        "creator": {
          "links": {
            "self": "/v1/generated_reports/A-UUID-ASSOCIATED-WITH-EACH-RUN/relationships/creator",
            "related": "/v1/generated_reports/A-UUID-ASSOCIATED-WITH-EACH-RUN/creator"
          },
          "data": [
            {
              "type": "users",
              "id": "84"
            }
          ]
        }
      }
    },
    {
      "type": "generated_reports",
      "id": "ANOTHER-UUID-ASSOCIATED-WITH-EACH-RUN",
      "attributes": {
        "report_id": 43,
        "report_name": "Market Benchmark Report",
        "status": "FINISHED",
        "started_at": "2021-02-14T11:15:30.00Z",
        "completed_at": "2021-02-14T13:25:45.00Z",
        "generated_portfolios": [
          {
            "portfolio_type": "entity",
            "portfolio_id": 21,
            "portfolio_name": "Tony Stark",
            "file_id": 103
          },
          {
            "portfolio_type": "group",
            "portfolio_id": 31,
            "portfolio_name": "Avengers",
            "file_id": 104
          }   
        ],
        "failed_portfolios": []
      },
      "relationships": {
        "creator": {
          "links": {
            "self": "/v1/generated_reports/ANOTHER-UUID-ASSOCIATED-WITH-EACH-RUN/relationships/creator",
            "related": "/v1/generated_reports/ANOTHER-UUID-ASSOCIATED-WITH-EACH-RUN/creator"
          },
          "data": [
            {
              "type": "users",
              "id": "84"
            }
          ]
        }
      }
    }
  ],
  "included": []
}

Example with parameters

GET /v1/generated_reports/?page[size]=50&page[number]=0&filter[status]=FINISHED,ERROR&filter[completed_before]=2021-05-14T12:03:39Z

200 OK: Success


{
  "data": [
    {
      "type": "generated_reports",
      "id": "A-UUID-ASSOCIATED-WITH-EACH-RUN",
      "attributes": {
        "report_id": 42,
        "report_name": "Quarterly Performance Report",
        "status": "ERROR",
        "started_at": "2021-02-14T10:15:30.00Z",
        "completed_at": "2021-02-14T14:25:45.00Z",
        "generated_portfolios": [
          {
            "portfolio_type": "entity",
            "portfolio_id": 21,
            "portfolio_name": "Tony Stark",
            "file_id": 101
          },
          {
            "portfolio_type": "group",
            "portfolio_id": 31,
            "portfolio_name": "Avengers",
            "file_id": 102
          }   
        ],
        "failed_portfolios": [
          {
            "portfolio_type": "entity",
            "portfolio_id": 22,
            "portfolio_name": "Thanos"
          },
          {
            "portfolio_type": "group",
            "portfolio_id": 32,
            "portfolio_name": "Chitauri"
          }   
        ]
      },
      "relationships": {
        "creator": {
          "data": {
            "type": "users",
            "id": "84"
          },
          "links": {
            "self": "/v1/generated_reports/A-UUID-ASSOCIATED-WITH-EACH-RUN/relationships/creator",
            "related": "/v1/generated_reports/A-UUID-ASSOCIATED-WITH-EACH-RUN/creator"
          }
        },
        "zipped_file": {
          "data": {
             "type": "archive/files",
             "id": "61"
          },
          "links": {
            "self": "/v1/generated_reports/A-UUID-ASSOCIATED-WITH-EACH-RUN/relationships/zipped_file",
            "related": "/v1/generated_reports/A-UUID-ASSOCIATED-WITH-EACH-RUN/zipped_file"
          }
        }
      }
    },
    {
      "type": "generated_reports",
      "id": "ANOTHER-UUID-ASSOCIATED-WITH-EACH-RUN",
      "attributes": {
        "report_id": 43,
        "report_name": "Market Benchmark Report",
        "status": "FINISHED",
        "started_at": "2021-02-14T11:15:30.00Z",
        "completed_at": "2021-02-14T13:25:45.00Z",
        "generated_portfolios": [
          {
            "portfolio_type": "entity",
            "portfolio_id": 21,
            "portfolio_name": "Tony Stark",
            "file_id": 103
          },
          {
            "portfolio_type": "group",
            "portfolio_id": 31,
            "portfolio_name": "Avengers",
            "file_id": 104
          }   
        ],
        "failed_portfolios": []
      },
      "relationships": {
        "creator": {
          "data": {
            "type": "users",
            "id": "84"
          },
          "links": {
            "self": "/v1/generated_reports/ANOTHER-UUID-ASSOCIATED-WITH-EACH-RUN/relationships/creator",
            "related": "/v1/generated_reports/ANOTHER-UUID-ASSOCIATED-WITH-EACH-RUN/creator"
          }
        },
        "zipped_file": {
          "data": {
             "type": "archive/files",
             "id": "62"
          },
          "links": {
            "self": "/v1/generated_reports/ANOTHER-UUID-ASSOCIATED-WITH-EACH-RUN/relationships/zipped_file",
            "related": "/v1/generated_reports/ANOTHER-UUID-ASSOCIATED-WITH-EACH-RUN/zipped_file"
          }
        }
      }
    }
  ],
  "included": [],
  "links": {
     "next": "/v1/generated_reports?page[number]=1&page[size]=50"
   }
}

Responses

200 OK: Success
400 Bad Request: include query parameter not allowed
403 Forbidden: Lacking admin permission

Get generated report by job ID

Retrieves a generated report by job ID within the authenticated user's firm.

GET /v1/generated_reports/:id

GET https://examplefirm.addepar.com/v1/generated_reports/42

200 OK: Success

{
  "data": {
    "type": "generated_reports",
    "id": "A-UUID-ASSOCIATED-WITH-EACH-RUN",
    "attributes": {
      "report_id": 42,
      "report_name": "Quarterly Performance Report",
      "status": "ERROR",
      "started_at": "2021-02-14T10:15:30.00Z",
      "completed_at": "2021-02-14T14:25:45.00Z",
      "generated_portfolios": [
        {
          "portfolio_type": "entity",
          "portfolio_id": 21,
          "portfolio_name": "Tony Stark",
          "file_id": 101
        },
        {
          "portfolio_type": "group",
          "portfolio_id": 31,
          "portfolio_name": "Avengers",
          "file_id": 102
        }   
      ],
      "failed_portfolios": [
        {
          "portfolio_type": "entity",
          "portfolio_id": 22,
          "portfolio_name": "Thanos"
        },
        {
          "portfolio_type": "group",
          "portfolio_id": 32,
          "portfolio_name": "Chitauri"
        }   
      ]
    },
    "relationships": {
      "creator": {
        "links": {
          "self": "/v1/generated_reports/A-UUID-ASSOCIATED-WITH-EACH-RUN/relationships/creator",
          "related": "/v1/generated_reports/A-UUID-ASSOCIATED-WITH-EACH-RUN/creator"
        },
        "data": [
          {
            "type": "users",
            "id": "84"
          }
        ]
      }
    }
  },
  "included": []
}

Responses

200 OK: Success
400 Bad Request: include query parameter not allowed
403 Forbidden: Lacking admin permission
404 Not Found: Nonexistent/non-permissioned generated report ID

Get report creator by ID

Retrieves all information related to the user who generated the reports for the job id.

GET /v1/generated_reports/:id/creator

GET https://examplefirm.addepar.com/v1/generated_reports/42/creator

200 OK: Success

{
    "data": {
        "id": "84",
        "type": "users",
        "attributes": {
            "first_name": "Nick",
            "last_name": "Fury",
            "two_factor_auth_enabled": false,
            "admin_access": true,
            "all_data_access": true,
            "login_method": "email_password",
            "email": "[email protected]"
        },
        "relationships": {
            "permissioned_entities": {
                "links": {
                    "self": "/v1/users/84/relationships/permissioned_entities",
                    "related": "/v1/users/84/permissioned_entities"
                },
                "data": []
            },
            "assigned_role": {
                "data": null
            },
            "permissioned_groups": {
                "links": {
                    "self": "/v1/users/84/relationships/permissioned_groups",
                    "related": "/v1/users/84/permissioned_groups"
                },
                "data": []
            }
        },
        "links": {
            "self": "/v1/users/84"
        }
    },
    "included": []
}

Responses

200 OK: Success
400 Bad Request: Invalid relationship queried
403 Forbidden: Lacking admin permission
404 Not Found

Get reports in a zipped file by ID

Retrieves all information related to the zipped file generated for the job ID.

GET /v1/generated_reports/:id/zipped_file

GET https://examplefirm.addepar.com/v1/generated_reports/61/zipped_file

200 OK: Success

{
    "data": {
        "id": "61",
        "type": "files",
        "attributes": {
            "content_type": "application/zip",
            "bytes": 36599,
            "name": "Quarterly Performance Report at 05-15-2021.zip",
            "created_at": "2021-05-17T12:34:38Z"
        },
        "relationships": {
            "associated_groups": {
                "links": {
                    "self": "/v1/files/61/relationships/associated_groups",
                    "related": "/v1/files/61/associated_groups"
                },
                "data": []
            },
            "associated_entities": {
                "links": {
                    "self": "/v1/files/61/relationships/associated_entities",
                    "related": "/v1/files/61/associated_entities"
                },
                "data": []
            }
        },
        "links": {
            "self": "/v1/files/61"
        }
    },
    "included": []
}

Responses

200 OK: Success
400 Bad Request: Invalid relationship queried
403 Forbidden: Lacking admin permission
404 Not Found

Download reports in a zipped file by ID

Returns a binary zipped file.

GET /v1/generated_reports/:id/zipped_file/download

GET https://examplefirm.addepar.com/v1/generated_reports/61/zipped_file

HTTP/1.1 200

Content-DispositionL attachment; filename="Quarterly Performance Report at 05-15-2021.zip"
Content-Type: application/binary

<RAW_FILE_DATA>

Responses

200 OK: Success
403 Forbidden: Lacking admin permission
404 Not Found

See more types of file downloads