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
EndpointsGET
/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
ProducesJSON
PaginationYes
OAuth ScopesFILES 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.

AttributeTypeExample
report_idThe unique id of the report for which the report generation job was run.46
report_nameThe name of the report for which the report generation job was run."Quarterly Performance Report"
statusThe 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_atString representing the time instant in UTC at which this report generation job was started."2021-02-14T10:15:30.00Z"
completed_atString representing the time instant in UTC at which this report generation job finished."2021-02-14T14:25:45.00Z"
job_typeSpecifies whether the report job was scheduled or ad hoc. "SCHEDULED" or "AD_HOC"
generated_portfoliosAn 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_typeOne of entity or group."entity"
portfolio_idUnique id of the portfolio.21
portfolio_nameName of the portfolio."Tony Stark"
file_idUnique id of the generated file. It can be used to download the actual binary file from GET /v1/files/:id/download.101
failed_portfoliosAn array of objects providing information of failed portfolios during report generation. Includes portfolio type, portfolio ID, and portfolio name."failed_portfolios"
portfolio_typeOne of entity or group."entity"
Relationships
creatorThe user who created the report generation job that generated the associated files.

Optional Parameters

ParameterDescriptionExample
filter[completed_after]=YYYY-MM-DDTHH:MM:SSZReturns jobs run after this date. The timestamp is in UTC.[completed_after]=2021-05-14T12:03:39Z
filter[completed_before]=YYYY-MM-DDTHH:MM:SSZReturns 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",
        "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 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"
        }
      }
    }
  }
}

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