EVP Everywhere uses REST HTTP queries through https://api.evpsys.com to create, manage, and evaluate portfolios using Estate Valuations & Pricing Systems software: EstateVal, CostBasis, and GiftVal.
All endpoints return HTTP response-codes; 2xx values represent a successful request, 4xx values request a problem with the client request, and 5xx values represent a problem on the server side. Additional data can be submit to certain endpoints via either query-string arguments or the HTTP body. Additional data may be returned from an endpoint as an HTTP body.
The public certificate for the website, if you want to verify connection security, is available here.
All EVP Everywhere HTTP body requests can be made as XML or JSON, and the server will automatically determine which format is used. Body responses can be requested as XML or JSON (or PDF, RTF, text, or Excel in the case of reports), via the common output query-string, defined below.
For XML request and responses, all attributes are entity-encoded.
All date-based attributes use the YYYYMMDD format. All boolean attributes are strings, either true or false. All currency attributes are strings, three capital letters corresponding to the ISO code for the currency. (For example, USD, JPY, or EUR.)
The data descriptions below document the XML format, but the JSON format contain all the same data. XML tags are equivalent to JSON dictionaries; XML attributes are converted into into JSON keys with the attribute name prefixed with an @; XML tag contents are converted into JSON keys with the name #text; XML nodes that may have multiple instances inside a container are treated as JSON arrays filled with dictionaries.
For example, this XML:
<tag-1 attribute-1="arg-1" attribute-2="arg-2"> <tag-2 attribute-3="arg-3" /> <tag-3 attribute-4="arg-4"> body-1 <tag-4 attribute-5="arg-5" /> <tag-4 attribute-6="arg-6" /> </tag-3> </tag-1>
...would be delivered as the JSON:
{
"tag-1": {
"@attribute-1": "arg-1",
"@attribute-2": "arg-2",
"tag-2": {
"@attribute-3": "arg-3"
},
"tag-3": {
"@attribute-4": "arg-4",
"tag-4": [
{
"@attribute-5": "arg-5"
},
{
"@attribute-6": "arg-6"
}
],
"#text": "body-1"
}
}
}
There are two methods by which an EVP Everywhere client application can authenticate itself to the server, to identify who is making the request:
Basic Authentication uses the standard Authorization header, with a payload of the word "Basic", followed by a space, followed by a base-64 encoding of your EVP Systems Client Token, a colon, and your client's EVP Systems Account Information Key:
Authentication: Basic base64(client-token:account-key)
The DT0 method expects an EVP Systems Client Token as the payload for a X-EVP-Username header and a base-64 encoding of a .DT0 file as the payload for a X-EVP-DT0 header:
X-EVP-Username: client-token
X-EVP-DT0: base64(binary-contents-of-EVPS.DT0)
DT0 is the license file from an EstateVal installation, usually stored in %APPDATA%\EVP Systems\EVPS.DT0 on the user's Windows machine. The advantage of this method is that if EstateVal is already installed and configured, EVP Everywhere can use the existing license file without any additional effort on the user's part.
The Client Token is provided to you by EVP Systems and is unique to your company or the particular software that is making requests to EVP Everywhere. It should be hard-coded into your application.
The Account Information Key is provided to you or your users by EVP Systems when an account is set up. If your software is in-house or you plan to re-bill your clients for EVP Everywhere evaluations, the Account Information Key can be hard-coded to a single value; the passthrough portfolio element can be used to identify the client the charge should be made to, if you wish to re-bill them. If you want your clients to be directly billed for any EVP Everywhere evaluations, they should sign up with EVP Systems, and your software should allow them to enter the Account Information Key they receive then. If your software runs on Windows, it might also check for the EstateVal .DT0 file, and use that instead of a new Account Information Key, simply for convenience.
If no authentication method is included in an endpoint request, the response will be an HTTP 401 with a WWW-Authenticate header, asking for authorization details. If the authentication method uses an unknown, suspended or invalid Client Token, the response will be an HTTP 403. If the authentication method uses an improperly formatted Information Key, the response will be HTTP 400.
While each endpoint accepts endpoint-specific arguments, they also all have the following query-string arguments:
The following are "convenience" endpoints, designed for small, simple, synchronous evaluations. No data generated by them persists on the server. To create, edit, evaluate, and retrieve complete portfolios and reports, please see the below.
GET /estateval/report returns a report that prices a single security for 1,000 shares/par. It is designed to allow quick reports without the overhead of constructing an entire portfolio.
Input: In addition to the common query-string arguments defined above, allowed query-string arguments are:
Output: This endpoint produces a "Report" response, defined below. This response can be validated by its XSD (1.0, 1.1, 1.2).
Example:
GET https://api.evpsys.com/estateval/report?version=1.0&output=json&identifier=MSFT&date=20161119&report=alt
The following are endpoints that provide access to the full lifecycle of a portfolio, its evaluation, and the resulting data. Multiple calls to the various functions are required. For instance:
POST /portfolio creates a portfolio object on the server, which can then be modified and evaluated by further calls. It is designed to allow for large or complex portfolios to be evaluated, when single or one-at-a-time evaluations (via endpoints like GET /estateval/report are not appropriate or efficient.
Input: This endpoint accepts a "Portfolio" input, defined below. There are no query-string arguments other than the common ones, defined above.
Output: Returns a response as follows, with {portfolio-id} used to identify the portfolio in other calls. This response can be validated by its XSD (1.0, 1.1, 1.2).
<output version="1.0">
<status>ok</status>
<portfolio-id>{portfolio-id}</portfolio-id>
</output>
PUT /portfolio/{portfolio-id} modifies an existing portfolio on the server.
Input: This endpoint takes a "Portfolio" input, defined below. Any element of the "Portfolio" input not included cause that data to be preserved as-is in the existing portfolio. Any that are sent as blank -- for instance, name="" or <lot number="123" /> -- cause that data to be removed. The only query-string arguments are the common ones, defined above.
Output: Returns a response as follows. This response can be validated by its XSD (1.0, 1.1, 1.2).
<output version="1.0"> <status>ok</status> </output>
GET /portfolio returns a list of portfolios associated with the authenticated account, in fifty-portfolio batches, sorted by their creation date in descending order.
Input: This endpoint accepts the following query-string arguments, in addition to the common ones defined above:
Output: Returns a list of metadata about portfolios. more is true if there are more portfolios to retrieve using portfolio_id_last, false otherwise. This response can be validated by its XSD (1.0, 1.1, 1.2).
<output version="1.0">
<status>ok</status>
<more>{true|false}</more>
<portfolio id="{portfolio-id}" death-date="{portfolio-date}" name="{portfolio-name}" account="{portfolio-account}" title="{portfolio-title}" passthrough="{portfolio-passthrough}" portfolio_time_created="{portfolio-time-created}" portfolio_time_updated="{portfolio-time-created}" />
...
</output>
GET /portfolio/{portfolio-id} returns the portfolio as an EVP file, usable by the desktop version of EstateVal.
Output: The output is an EVP Portfolio file, and always XML.
DELETE /portfolio/{portfolio-id} will delete a portfolio from the server, along with all its reports.
Output: Returns a response as follows. This response can be validated by its XSD (1.0, 1.1, 1.2).
<output version="1.0"> <status>ok</status> </output>
PUT /portfolio/{portfolio-id}/estateval/report adds a single lot to a portfolio, evalutes only that lot, and returns a report that includes information only about that lot. Like GET /estateval/report, it is intended to allow quick, single-call evaluation of a security, but it also adds the security to a portfolio, preserving the evaluation data to be referenced by future calls, including evaluation and reporting on the full portfolio. The portfolio is expected to have already been created via POST /portfolio. Portfolio-level infromation like dates and passthrough data are defaulted to the current valueson the portfolio; if they are defined as part of the call, the portfolio-level values are overwritten.
Input: The endpoint accepts the following query-string arguments, in addition to the common ones defined above:
Output: The output is a "Report" response, defined below. It will include only the lot number defined in the request. This response can be validated by its XSD (1.0, 1.1, 1.2).
POST /portfolio/{portfolio-id}/estateval/report begins the process of creating a report from a portfolio. A report-id is returned, to reference the report in later calls.
Input: The endpoint accepts the following query-string arguments, in addition to the common ones defined above:
Output: Returns one of the following responses. These responses can be validated by their XSD (1.0, 1.1, 1.2).
The first indicates a successful start to the report generation, with {report-id} used to identify the report in other calls.
<output version="1.0">
<status>error<status>
<report-id>{report-id}</report-id>
</output>
The second indicates an error, with error-code defining the error code and error-text a human-readable reason for the failure.
<output version="1.0">
<status>error<status>
<error-code>{error-code}</error-code>
<error-text>{error-text}</error-text>
</output>
GET /portfolio/{portfolio-id}/estateval/report/{report-id}/status returns the current status of the specified report. It should be polled at regular intervals to determine when the evaluation of the report is complete.
Input: There are no inputs other than the common query-string arguments, defined above.
Output: Returns one of the follow responses. These responses can be valided by their XSD (1.0, 1.1, 1.2).
The first indicates that the report generation has successfully completed, and the report itself can be requested using GET /portfolio/{portfolio-id}/estateval/report/{report-id}.
For reports generated and queried using version 1.2, the ok result will also include the <report>, <disclaimers> and <billing> elements of a GET /portfolio/{portfolio-id}/estateval/report call, so the call to retrive the report (at least in JSON or XML format) will not need to be made.
<output version="1.0"> <status>ok</status> </output>
This indicates that the report generation is on-going, with {pending-percent} giving the progress as an integer between 0 and 100, and {pending-text} as human-readable text describing the current action.
<output version="1.0">
<status>pending</status>
<pending-percent>{pending-percent}</pending-percent>
<pending-text>{pending-text}</pending-text>
</output>
This indicates that the report generation has failed, with {error-code} giving the failure code, and {error-text} a human-readable description of the failure.
<output version="1.0">
<status>error</status>
<error-code>{error-code}</error-code>
<error-text>{error-text}</error-text>
</output>
GET /portfolio/{portfolio-id}/estateval/report/{report-id} returns the report, once GET /portfolio/{portfolio-id}/estateval/report/{report-id}/status returns a status of ok. Once a report has been successfully generated, it can be repeatedly requested, with either the same or different output formats.
Input: Inputs are limited to the common query-string arguments, defined above.
Output: The output is a "Report" response, defined below. This response can be validated by its XSD (1.0, 1.1, 1.2).
GET /portfolio/{portfolio-id}/estateval/report returns a list of reports run on the portfolio, in fifty-report batches, sorted by their creation date in descending order.
Input: This endpoint accepts the following query-string arguments, in addition to the common ones defined above:
Output: Returns a list of metadata about the reports for the portfolio. more is true if there are more reports to retrieve using report_id_last, false otherwise. This response can be validated by its XSD (1.0, 1.1, 1.2).
<output version="1.0">
<status>ok</status>
<more>{true|false}</more>
<report id="{report-id}" death-date="{report-death-date}" other-date="{report-other-date}" type="{dod|alt|apr|dst}" report_status="{ok|pending}" report_percent="{report-percent-complete}" report_time_created="{report-time-created}" report_time_updated="{report-time-created}" />
...
</output>
DELETE /portfolio/{portfolio-id}/estateval/report/{report-id} will delete a report from the server.
Output: Returns a response as follows. This response can be validated by its XSD (1.0, 1.1, 1.2).
<output version="1.0"> <status>ok</status> </output>
EVP Everywhere takes input via query-string arguments (on the URL itself) and via the HTTP request body. The query-string arguments are defined in common and per-endpoint above, but common body formats are defined below, are accepted as either XML or JSON.
The <input> tag encloses the entire input. Arguments include:
"Portfolio" inputs are used to initially define or modify an existing portfolio on the server, encoded inside a <input> tag.
At the top-level is the <portfolio> tag, which includes the following attributes:
Enclosed in the <portfolio> tag will be one or more <lot> tags, which define the holdings for the portfolio. Attributes include:
Example: This input body would define a portfolio of three securities for a decedendent who passed on April 3, 2018:
<input version="1.0"> <portfolio death-date="20180503" name="John Doe" account="Account #123" title-1="Estate of John Doe"> <lot number="1" identifier="IBM" shares="123.456" /> <lot number="2" identifier="MSFT" shares="789" /> <lot number="4" identifier="AMZN" shares="9876.54321" /> </portfolio> </input>
Alternately, it can be constructed as JSON:
{
"input": {
"portfolio": {
"@death-date": "20180503",
"@name": "John Doe",
"@account": "Account #123",
"@title-1": "Estate of John Doe",
"lot": [
{ "@number": 1, "@identifier": "IBM", "@shares": "123.456" },
{ "@number": 2, "@identifier": "MSFT", "@shares": "789" },
{ "@number": 4, "@identifier": "AMZN", "@shares": "9876.54321" }
]
},
"@version": "1.0"
}
}
Optionally enclosed in each <lot> tag can be an inventory adjustment, to indicate the final disposition of the lot's holdings on the Alternate Date, Distribution Date, or Appraisal Date. These adjustments to the lot's holdings are indicated by any or all of the <alt>, <dst> or <apr> tags. If the lot's holdings are the same between the Date of Death/As-of Date and the Alternate Date, Distribution Date, or Appraisal Date, then these tags are not needed. Attributes include:
Further, there can be up to fifty <action> tags inside each of the <alt>, <dst> or <apr> tags, to enumerate other changes to the original lot -- sales, spin-offs, mergers, etc. -- between the Date of Death/As-of Date and the Alternate Date, Distribution Date, and Appraisal Date. Attributes include:
For <dst> and <apr> inventory adjustments, only two <action> types are available: "Held" and "Sold". If type is "Held", the inventory adjustment is evaluated as identifier holding shares on the Distribution or Appraisal Date, as appropriate, and added to the report. If type is "Sold", the inventory adjustment is evaluated as identifier holding shares on date and added to the report.
For <alt> (Alternate Date) adjustments, type can be more expressive, though they all function as "Sold" or "Held", just with different text describing the action on the report.
"Sold" types may be any of the following strings:
"Held" types may be any of the following strings:
Example: Expanding on the example above, if the estate had sold 23.456 shares of IBM a month after the date of death, then distributed 50 shares a month after that, and sold off MSFT a month after that (so it held no Microsoft on the Alternate Date) with a note after acquiring an (invented for this example) spin-off, the XML to build the portfolio would look like this:
<input version="1.0">
<portfolio death-date="20180503" name="John Doe" account="Account #123" title-1="Estate of John Doe">
<lot number="1" identifier="IBM" shares="123.456">
<alt shares="50">
<action type="Sold" date="20180603" shares="23.456" />
<action type="Distributed" date="20180703" shares="50" />
</alt>
</lot>
<lot number="2" identifier="MSFT" shares="789">
<alt shares="0">
<action type="Sold" date="20180803" shares="789" description="Sold at the request of the trustee" />
<action type="Held (via Spin-Off)" identifier="FAKE" shares="12.5" />
</alt>
</lot>
<lot number="4" identifier="AMZN" shares="9876.54321" />
</portfolio>
</input>
Important: It's very important to note that if a lot has its inventory adjusted by the inclusion of any <alt>, <dst> or <apr> tags, the automatic split handling that is normally done for unadjusted inventories is not performed. If a security splits between the Date of Death/As-of Date and the Alternate, Distribution or Appraisal Date and its inventory is adjusted, the user is obligated to change the shares values as appropriate for each <action>, as well as the shares on the <alt>, <dst> or <apr> tags themselves.
Each <lot> element represents a single holding of a specific security. To edit the details of those securities, you can set the attributes below:
Example: This sets the details of a lot and security manually, for custom pricing:
<input version="1.0"> <portfolio death-date="20180503" name="John Doe" account="Account #123" title-1="Estate of John Doe"> <lot number="1" identifier="BOB" shares="123.456" manual="true" value="567.89" /> <lot number="2" identifier="BOB" shares="789.012" manual="true" value="1234.56" /> <security identifier="BOB" name="BOB'S COMPANY" description-1="A DIVISION OF BOBOCO" description-2="PRIVATELY HELD" /> </portfolio> </input>
EVP Everywhere produces different kinds of responses for different endpoint queries. Each of the output formats documented below are shown in XML, but they will also be delivered in JSON, depending on the output argument passed to the endpoint request.
The <output> tag encloses the entire result. Arguments includes:
"Report" responses are the results of a single portfolio report, encoded inside the common <output> tag.
At the top-level is the <report> tag, which includes the attributes:
Enclosed in the <report> tag will be one <total> tag, describing the total value for the report. Attributes include:
Enclosed in the <report> tag is an optional <note> tag. Its body is an arbitrary string of text that describes the portfolio.
Enclosed in the <report> tag is any number of <lot> tags, which contain the details of each lot held by the portfolio. Attributes include:
Enclosed in the <lot> tag will be one <subtotal> tag, describing the subtotal values for the lot. Attributes include:
Enclosed in each <lot> tag will be one or more <inventory> tags. For "Date of Death" reports, there will only ever be one inventory item -- the holdings of the lot on the Date of Death. For "Alternate Date" reports, there may be any number, describing the changes to the Date of Death holding between the Date of Death itself and the Alternate Date. Attributes include:
Enclosed in the <inventory> tag will be one <subtotal> tag, describing the subtotal values for the inventory. Attributes include:
Enclosed in each <inventory> tag is an optional <price> tag that describes general information about the price of the lot. Attributes include:
Enclosed in each <price> tag is a single <last> tag, giving details about the last-available price, either on or before the valuation date. Attributes include:
Optionally enclosed in each <price> tag can be a <next> tag, giving details about the next-available price, if the <last> price is not on the valuation date and a next-price is available. Attributes include:
Enclosed in each <price> is a single <mean> tag, giving the weighted mean of the <last> and any <next> price. Attributes include:
Optionally enclosed in each <inventory> may be a single <generic-value> tag, giving any value arbitrarily provided by the portfolio. Attributes include:
Optionally enclosed in each <inventory> may be a single <generic-accrual> tag, giving any accrual arbitrarily provided by the portfolio. Attributes include:
Optionally enclosed in each <inventory> may be a single <dividends> tag, enclosing information about individual dividends. Attributes include:
Optionally enclosed in the <dividends> tag may be any of <adjustments>, <accruals> or <values> tags, further enclosing individual dividends that either adjust the mean price, or contribute to the value or accrual of the inventory. There are no attributes.
Enclosed in the <adjustments>, <accruals> or <values> tags, the <dividend> tag describes details about an individual dividend, in the context of the containing tag. Attributes include:
Optionally enclosed in the <inventory> tag, the <bond> tag provides details for bond and bond-like securities. Attributes include:
Optionally enclosed in the <inventory> tag, the <mbs> tag provides details for mortgage-backed securities: GNMAs, FNMAs, FHMLCs and CMOs. Attributes include:
Enclosed in the <mbs> tag, any number of <payment> tags give details about the mortgage-backed security's payments. Attributes include:
Optionally enclosed in the <inventory> tag, a single <uit> tag give details about a unit investment trust. Attributes include:
Optionally enclosed in the <inventory> tag, a single <notes> tag further encloses individual <note> tags. There are no attributes.
Enclosed in the <notes> tag, any number of <note> tags give arbitrary information about the inventory item, as the tag's body. There are no attributes.
Optionally enclosed in the top-level <output> tag is the <disclaimers> tag, which has no attributes.
Enclosed in the <disclaimers> tag are one or more of the <header>, <bottom>, and <footer> tags, which contain disclaimer text appropriate for the associated location in the report: the space at the top of each page, the space at the end of the report after the totals, and the space at the bottom of each page.
Optionally enclosed in the top-level <output> tag is the <billing> tag, which has no attributes for version 1.0 responses, and the following for 1.1 and 1.2 responses:
Enclosed in the <billing> tag will be one or more <item> tags, describing the bill for each identifier priced in the generation of the report.
A Date of Death report (XML, JSON, PDF)
An Alternate Date report (XML, JSON, PDF)
Code to create, modify, and build a report (Python, Python with a .txt extender)
Code to evaluate a single security (Visual Studio C++, Powershell, Powershell with a .txt extender)