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 /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"`
`job_type`	Specifies whether the report job was scheduled or ad hoc.	`"SCHEDULED"` or `"AD_HOC"`
`generated_portfolios`	An array of objects providing information of successfully generated portfolios. Includes portfolio type, portfolio id, portfolio name, file id, and publish to portal status.	`"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"`

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`
filter[xxx][entityId]	Returns the jobs for this entity's portfolio.	[entityId]=12345
filter[xxx][groupId]	Returns the jobs for this group's portfolio.	[groupId]=54789

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",
        "job_type": "AD_HOC",
        "generated_portfolios": [
          {
            "portfolio_type": "entity",
            "portfolio_id": 21,
            "portfolio_name": "Tony Stark",
            "file_id": 101,
            "has_been_published": false
          },
          {
            "portfolio_type": "group",
            "portfolio_id": 31,
            "portfolio_name": "Avengers",
            "file_id": 102,
            "has_been_published": false
          }
        ],
        "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",
        "job_type": "AD_HOC",
        "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"
  }
}

Example with various 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",
      "job_type": "AD_HOC",
      "generated_portfolios": [
        {
          "portfolio_type": "entity",
          "portfolio_id": 21,
          "portfolio_name": "Tony Stark",
          "file_id": 101,
          "has_been_published": false
        },
        {
          "portfolio_type": "group",
          "portfolio_id": 31,
          "portfolio_name": "Avengers",
          "file_id": 102,
          "has_been_published": false
        }
      ],
      "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": "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"
        }
      }
    }
  }
}

Example with portfolio filter parameter

GET /v1/generated_reports/?page[size]=50&page[number]=0&filter[entityId]=1234

{
  "data": [
    {
      "type": "generated_reports",
      "id": "A-UUID-ASSOCIATED-WITH-EACH-RUN",
      "attributes": {
        "report_id": 42,
        "report_name": "Quarterly Performance Report",
        "status": "FINISHED",
        "started_at": "2021-02-14T10:15:30.00Z",
        "completed_at": "2021-02-14T14:25:45.00Z",
        "job_type": "AD_HOC",
        "generated_portfolios": [
          {
            "portfolio_type": "entity",
            "portfolio_id": 1234,
            "portfolio_name": "Tony Stark",
            "file_id": 101,
            "has_been_published": false
          },
          {
            "portfolio_type": "group",
            "portfolio_id": 31,
            "portfolio_name": "Avengers",
            "file_id": 102,
            "has_been_published": false
          }
        ],
        "failed_portfolios": []
      },
      "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",
        "job_type": "AD_HOC",
        "generated_portfolios": [
          {
            "portfolio_type": "entity",
            "portfolio_id": 1234,
            "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&filter[entityId]=1234"
  }
}

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",
      "job_type": "AD_HOC",
      "generated_portfolios": [
        {
          "portfolio_type": "entity",
          "portfolio_id": 21,
          "portfolio_name": "Tony Stark",
          "file_id": 101,
          "has_been_published": false
        },
        {
          "portfolio_type": "group",
          "portfolio_id": 31,
          "portfolio_name": "Avengers",
          "file_id": 102,
          "has_been_published": false
        }
      ],
      "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": "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"
        }
      }
    }
  }
}

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 or the report is currently being generated

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