Report Configuration API

One of the basic concepts in the BMC Public API is the concept of scheduling Benchmark reports. This API provides the ability to create, edit, list, and delete a report configuration.

What is a Report Configuration

The BMC Public API (v1) is a data vendoring API. It does not exercise real-time report generation. It allows users to create Benchmark reports using defined filters and parameters and then schedule those reports to be run by an asynchronous listener process

Message Structures

Request Example

The basic structure of Report Configuration Request is as follows:

{
    "Parameters" : {
        "BenchmarkId" : "ab79ec4c-d341-41a2-a104-9f7128639b72",
        "ReportType" : "<see ReportTypes enum>",
        "DataMode" : "2019Q2",
        "ModeType" : "Preliminary",
        "VintageYearBy": "FCF",
        "Scheduling" : {
            "Frequency" : "Daily"
        },
        "AttributeFilter" : [
            "IRRPooled",
            "IRREqualWeighted",
            "IRRAverage",
            "IRRMax",
            "IRR95Percentile",
            "IRRQuartileUpper", 
            "IRRQuartileLower",
            "IRR5Percentile",
            "IRRMin"
        ]
    }
}

Note : report type specific parameters (see below)

The request type is quite simple in that it supports a basic set of constructs and then permits a set of report attributes based on the ReportType.

Parameter	DataType	Nullable	Description
BenchmarkId	uuidv4	false	this is the ID of the predefined BMC benchmark
ReportType	string	false	this is one of the enumerated report types allowed (see below)
VintageYearBy	string	false	Defines whether "FCF" or "LID".
Scheduling.Frequency	string	false	Defines the scheduling model.Must be "One-Time" which tells the api to queue the report to execute asap (async) , "Daily" which will run the report every day during daily batch process, or "Quarterly" which will run based on BMC quarter data availability
ModeType	string	false	Defines whether "Preliminary" or "Published" data is requested in the calculations."Published" modetype should not be allowed for "Daily"
AttributeFilter	array of strings	true	See Note Below

You can think of AttributeFilter as the SQL SELECT clause describing the attributes you want the report to return. The value can be any valid attribute in the response message based on ReportType. The validation logic will compare the attribute defined in request against those which are available in profile. If specified attribute is not in your profile, you will receive a HTTP 403 - Forbidden error in response. If you leave the attribute null or an empty array, it will return all the attributes to which you have access based on your profile.

Report Types

There are total of five distinct report types supported by the Public API, each with a distinct set of parameters

Fund Since Inception (FUND_SINCE_INCEPTION)
Fund Since Inception mPME (FUND_SINCE_INCEPTION_MPME)
Fund Horizon (FUND_HORIZON)
Fund Horizon mPME (FUND_HORIZON_MPME)
Investment Since Inception (INVESTMENT_SINCE_INCEPTION)

Request Type Parameters

For POST or PUT methods, the following tables provide the available Parameters allowed per Report Type. These criteria will allow the user to filter the results they receive when the scheduled report runs.

Since Inception Report

Acceptable parameters for the Since Inception Report

Parameter	Data Type	Optional	Default	Notes
DataMode	string	false	Most current quarter	yyyyQ#, Old Quarters allowed only for One-Time scheduling,Future quarters not allowed
AsOfDate	date	true	Always same as DataMode date	yyyy-mm-dd
Universe	string	true	2	enumerated, 3 - ILPA , 4 - Impact Investing, 2 - C\|A Benchmark, 1 - All Funds
Currency	string	true	USD	ISO Curr
VintageYearBy	string	false	LID	LID - Legal Inception Date,FCF-First Cash Flow
VintageYears	string	true	None	Shows all vintage years if this is not used
ReportedBy	number	true	None	Only 11 (Vintage Year) is allowed
Internal	boolean	true	false	Should always be false
FreeText	string	true	None	Only for S&P. FreeText cannot be null or empty and less than 50 charecters. FreeText can only have A-z a-z 0-9 !@#$^&()[]{}'+

Since Inception mPME Report

Acceptable parameters for the Since Inception mPME Report

Parameter	Data Type	Optional	Default	Notes
DataMode	string	false	Most current quarter	yyyyQ#, Old Quarters allowed only for One-Time scheduling,Future quarters not allowed
AsOfDate	date	true	Always same as DataMode date	yyyy-mm-dd
Universe	string	true	2	enumerated, 3 - ILPA , 4 - Impact Investing, 2 - C\|A Benchmark, 1 - All Funds
Currency	string	true	USD	ISO Curr
VintageYearBy	string	false	LID	LID - Legal Inception Date,FCF-First Cash Flow
VintageYears	string	true	None	Shows all vintage years if this is not used
ReportedBy	number	true	None	Only 11 (Vintage Year) is allowed
Index	number	true	"1"(S&P 500), "18781"(CON NASDAQ PR/TR), "106"(R2000), "126"(R3000)	enumerated
Internal	boolean	true	false	Should always be false
FreeText	string	true	None	Only for S&P. FreeText cannot be null or empty and less than 50 charecters. FreeText can only have A-z a-z 0-9 !@#$^&()[]{}'+

Horizon Report

Acceptable parameters for the Horizon Report

Parameter	Data Type	Optional	Default	Notes
DataMode	string	false	Most recent quarter	yyyyQ#, Old Quarters allowed only for One-Time scheduling,Future quarters not allowed
StartDate	date	true		yyyy-mm-dd
EndDate	date	true		yyyy-mm-dd
Universe	string	true	2	enumerated, 3 - ILPA , 4 - Impact Investing, 2 - C\|A Benchmark, 1 - All Funds
Currency	string	true	USD	ISO Curr
VintageYearBy	string	false	LID	LID - Legal Inception Date,FCF-First Cash Flow
VintageYears	string	true	None	Shows all vintage years if this is not used
ReportedBy	number	true	None	Only 11 (Vintage Year) is allowed
Internal	boolean	true	false	Should always be false
FreeText	string	true	None	Only for S&P. FreeText cannot be null or empty and less than 50 charecters. FreeText can only have A-z a-z 0-9 !@#$^&()[]{}'+

Horizon mPME Report

Acceptable parameters for the Horizon mPME Report

Parameter	Data Type	Optional	Default	Notes
DataMode	string	false	Most current quarter	yyyyQ#, Old Quarters allowed only for One-Time scheduling,Future quarters not allowed
StartDate	date	true		yyyy-mm-dd
EndDate	date	true		yyyy-mm-dd
Universe	string	true	2	enumerated, 3 - ILPA , 4 - Impact Investing, 2 - C\|A Benchmark, 1 - All Funds
Currency	string	true	USD	ISO Curr
VintageYearBy	string	false	LID	LID - Legal Inception Date,FCF-First Cash Flow
VintageYears	string	true	None	Shows all vintage years if this is not used
Index	number	true	"1"(S&P 500), "18781"(CON NASDAQ PR/TR), "106"(R2000), "126"(R3000)	enumerated
Internal	boolean	true	false	Should always be false
FreeText	string	true	None	Only for S&P. FreeText cannot be null or empty and less than 50 charecters. FreeText can only have A-z a-z 0-9 !@#$^&()[]{}'+

Investment Since Inception

Acceptable parameters for the Investment Since Inception

Parameter	Data Type	Optional	Default	Notes
DataMode	string	false	Most current quarter	yyyyQ#, Old Quarters allowed only for One-Time scheduling,Future quarters not allowed
AsOfDate	date	true	Always same as DataMode date	yyyy-mm-dd
Universe	string	true	2	enumerated, 3 - ILPA , 4 - Impact Investing, 2 - C\|A Benchmark, 1 - All Funds
Currency	string	true	USD	ISO Curr
VintageYearBy	string	false	LID	LID - Legal Inception Date,FCF-First Cash Flow
ReportedBy	number	true	None	Enumeration different for Investment Level
ThenBy	number	true	None	Enumeration different for Investment Level
Internal	boolean	true	false	Should always be false

Response Example

Response Example

The response for this API call will echo a Payload which represents the parameters submitted, with the addition of the system generated ReportId and audit information (names and timestamps).

{
    "RequestId" : "692ddba1-1cd6-44df-8b32-be4fd6e89d8b",
    "StatusCode" : 202,
    "Errors" : null,
    "Payload" : [
        {
            "ReportId" : "0fe4dc19-71ae-48f2-8f1f-f3e20ffd8959",
            "BenchmarkId" : "ab79ec4c-d341-41a2-a104-9f7128639b72",
            "ReportType" : "<see ReportTypes enum>",
            //... report type specific parameters (see above)
            "DataMode" : "2019Q2",
            "ModeType" : "Preliminary",
            "VintageYearBy" : "LID",
            "Scheduling" : {
                "Frequency" : "Daily"
            },
            "AttributeFilter" : [
                "IRRPooled","IRREqualWeighted","IRRAverage","IRRMax",
                "IrrTop10Percentile","IrrBottom10Percentile","TvpiTop10Percentile",
                "TvpiBottom10Percentile ","IRR95Percentile","IRRQuartileUpper", 
                "IRRQuartileLower", "IRR5Percentile","IRRMin"],
            "CreatedOn" : "2020-06-25T13:21:51.000Z",
            "CreatedBy" : "jdoe",
            "LastModOn" : "2020-08-25T20:00:42.000Z",      
            "LastModBy" : "tsmith"
        }
    ],
    "Stats" : {}
}

Create Report Config API

Creates and configures a new scheduled report

POST /api/v1/reports/config

On Success: HTTP 202 - Accepted

Payload: JSON payload (see above)

Successful requests adds ReportId, which is the uniqueidentifier (uuidv4) representing this report throughout its lifecycle.

Update Report Config

Allows a user to update an existing report configuration

PUT /api/v1/reports/config/:reportId

On Success: HTTP 200 - OK

Payload: JSON payload (see above)

ReportId is the uniqueidentifier (uuidv4) returned by the Create Report Config.

Delete Report Config

Allows a user to delete an existing report configuration.

Please note: C|A will archive all report configurations, but there will not be an automated mechanism to restore a deleted report config. Moreover, all reports run for the specific config will also be deleted, if the config is removed.

DELETE /api/v1/reports/config/:reportId

On Success: HTTP 204 - No Content

Payload: None

List Report Config

Allows a user to list all the report configurations they have created in the API

GET /api/v1/reports/config?pagingHash=<value>

On Success: HTTP 200 - OK

Payload: JSON payload (see above)

Details About Paging Data

The system will return a max of 50 records in its results. If there are more records available, the system will generate a Stat called PagingHash which you may pass into a subsequent request to continue paging through the resource.

    "Stats" : {
        "PagingHash" : "0fe4dc19-71ae-48f2-8f1f-f3e20ffd8959"
    }
}

Get Report Configuration

Retrieves a specific Report Configuration by its Report ID

GET /api/v1/reports/config/:reportId

ReportId is the uniqueidentifier (uuidv4) returned by the Create Report Config.

On Success: HTTP 200 - OK

Payload: JSON payload (see above)