← Documentation

Overview

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.

Data Conventions

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.

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"
  }
 }
}

Authentication

There are two methods by which an EVP Everywhere client application can authenticate itself to the server, to identify who is making the request:

  • By using Basic Authentication via the Authorization header
  • By sending an EstateVal DT0 via a X-EVP-DT0 header

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.

Common Arguments

While each endpoint accepts endpoint-specific arguments, they also all have the following query-string arguments:

  • version: The version of the request and response data, either 1.0 or 1.1; a version number. (Optional. Default: 1.0.)
  • output: xml or json. (Optional. Default: json.) When the response from an endpoint can be a "Report" response, defined below, pdf, rtf (rich text format), txt (plain text), and xlsx (Excel) are also allowed.

Endpoints

Convenience Endpoints

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

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:

  • identifier: A CUSIP, SEDOL or ticker symbol; a string. (Optional. Default: "IBM".)
  • date: The date-of-death for the evaluation for dod and alt reports; the holdings as-of date for apr and dst reports; a date in YYYYMMDD format. (Optional. Default: Yesterday.)
  • date_other: The valuation date for apr or dst reports; a date in YYYYMMDD format. (Opitonal, only used for apr or dst reports. Default: date value.)
  • report: dod for date-of-death reports, alt for alternate date, apr for appraisal date, or dst for distribution date. (Optional. Default: dod.)
  • passthrough: A value that is passed through EVP Everywhere to the invoice details, allowing the evaluation to be associated with a paricular client, account or portfolio. (Optional.)

Output: This endpoint produces a "Report" response, defined below. This response can be validated by its XSD (1.0, 1.1).

Example:

GET https://api.evpsys.com/estateval/report?version=1.0&output=json&identifier=MSFT&date=20161119&report=alt

Lifecycle Endpoints

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:

  • A portfolio can be created with POST /portfolio
  • The resulting portfolio-id used to edit the contents of the portfolio with PUT /portfolio/{portfolio-id}
  • A report can be started with POST /portfolio/{portfolio-id}/estateval/report
  • The resulting report-id used to monitor the reports progress by polling GET /portfolio/{portfolio-id}/estateval/report/{report-id}/status
  • Output (as JSON, XML, PDF, rich text, or plain text) can be retrieved from GET /portfolio/{portfolio-id}/estateval/report/{report-id} once it is ready
  • A list of previously created portfolios is listed by using GET /portfolio, while previously generated reports for each are returned from GET /portfolio/{portfolio-id}/estateval/report

POST /portfolio

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).

<output version="1.0">
 <status>ok</status>
 <portfolio-id>{portfolio-id}</portfolio-id>
</output>

PUT /portfolio/{portfolio-id}

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).

<output version="1.0">
 <status>ok</status>
</output>

GET /portfolio

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:

  • portfolio_id_last: The portfolio_id of the last item in the previous batch. The resulting list will begin at the portfolio prior to this one. (Optional.)
  • portfolio_filter: Text that will cause only portfolios with a partially matching name, account, or title to be returned; a string. (Optional.)

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).

<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}

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}

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).

<output version="1.0">
 <status>ok</status>
</output>

PUT /portfolio/{portfolio-id}/estateval/report

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:

  • number: The lot number of the holding in the portfolio; an integer. (Optional. Default: One greater than the current highest lot number in the portfolio.)
  • identifier: A CUSIP, SEDOL or ticker symbol; a string.
  • shares: The number of shares/par for the identifier; a float. (Optional. Default: `1`.)
  • date: The date-of-death for the evaluation for dod and alt reports; the holdings as-of date for apr and dst reports; a date in YYYYMMDD format. (Optional. Default: Current portfolio value; if none is defined at the portfolio level, the default is yesterday.)
  • date_other: The valuation date for apr or dst reports; a date in YYYYMMDD format. (Optional, only used for apr or dst reports. Default: Current portfolio value; if none is defined at the portfolio level, the date value is used.)
  • report: dod for date-of-death reports, alt for alternate date, apr for appraisal date, or dst for distribution date. (Optional. Default: dod.)
  • passthrough: A value that is passed through EVP Everywhere to the invoice details, allowing the evaluation to be associated with a paricular client, account or portfolio. (Optional. Default: Current portfolio value; if none is defined at the portfoilo level, the default is empty.)

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).

POST /portfolio/{portfolio-id}/estateval/report

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:

  • report: dod for date-of-death reports, alt for alternate date, apr for appraisal date, or dst for distribution date. (Optional. Default: dod.)

Output: Returns one of the following responses. These responses can be validated by their XSD (1.0, 1.1).

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

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).

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}.

<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}

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).

GET /portfolio/{portfolio-id}/estateval/report

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:

  • report_id_last: The report_id of the last item in the previous batch. The resulting list will begin at the report prior to this one. (Optional.)

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).

<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}

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).

<output version="1.0">
 <status>ok</status>
</output>

Input

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.

input

The <input> tag encloses the entire input. Arguments include:

  • version: The version of the input format the request is in; a version number. (Optional. Default: 1.0.)

Portfolio

"Portfolio" inputs are used to initially define or modify an existing portfolio on the server, encoded inside a <input> tag.

portfolio

At the top-level is the <portfolio> tag, which includes the following attributes:

  • death-date: The date of death; a date.
  • appraisal-date: The date of appraisal; a date. (Optional, used only by "Appraisal Date" reports; death-date is used as the inventory as-of date.)
  • distribution-date: The date of distribution; a date. (Optional, used only by "Distribution Date" reports; death-date is used as the inventory as-of date.)
  • name: The name of the decedendent; a string. (Optional.)
  • account: The account name or number associated with the portfolio; a string. (Optional.)
  • passthrough: A value that will pass through EVP Systems and be returned as-is in the usage breakdown included with the invoice, for re-billing clients; a string. (Optional.)
  • title-1: The first title line of the report; a string. (Optional.)
  • title-2: The second title line of the report; a string. (Optional.)
  • title-3: The third title line of the report; a string. (Optional.)

portfolio → lot

Enclosed in the <portfolio> tag will be one or more <lot> tags, which define the holdings for the portfolio. Attributes include:

  • number: The number of the lot inside the portfolio; an integer between 1 and 9999. (Optional. Default: 1, or the previous value plus 1.)
  • identifier: The CUSIP, SEDOL or ticker symbol that defines the holding of the lot; a string. Omitting this value causes the lot identified by number to be removed from the portfolio.
  • shares: The shares or par-value of the lot on the Date of Death/As-of Date; a float. (Optional. Default: 1.0.)
  • description: The user-generated description of the lot on the evaluation date; a string. (Optional.)
  • manual: If the value of the lot on the evaluation date is defined by the properties value and accrual; a boolean. (Optional. Default: false.)
  • value: The value of the lot, if manual is true, calculated according to the property pervalue. (Optional.)
  • pervalue: The method for calculating the value of the lot, if manual is true; a string, one of Per Security Type, Per Share, Per Par, Total for Lot. (Optional. Default: Total for Lot.)
  • accrual: The accrual of the lot, if manual is true. (Optional.)
  • peraccrual: The method for calculating the accrual of the lot, if manual is true; a string, one of Per Security Type, Per Share, Per Par, Total for Lot. (Optional. Default: Total for Lot.)

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"
 }
}

portfolio → lot → alt

portfolio → lot → dst

portfolio → lot → apr

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:

  • shares: The shares or par-value of the lot still held on the Alternate, Distribution or Appraisal Date; a float. (Optional. Default: the same shares as the enclosing <lot> tag.)
  • description: The user-generated description of the lot on the evaluation date; a string. (Optional.)
  • manual: If the value of the lot on the evaluation date is defined by the properties value and accrual; a boolean. (Optional. Default: false.)
  • value: The value of the lot, if manual is true, calculated according to the property pervalue. (Optional.)
  • pervalue: The method for calculating the value of the lot, if manual is true; a string, one of Per Security Type, Per Share, Per Par, Total for Lot. (Optional. Default: Total for Lot.)
  • accrual: The accrual of the lot, if manual is true. (Optional.)
  • peraccrual: The method for calculating the accrual of the lot, if manual is true; a string, one of Per Security Type, Per Share, Per Par, Total for Lot. (Optional. Default: Total for Lot.)

portfolio → lot → alt, dst, apr → action

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:

  • type: The type of action for this particular inventory adjustment; see below for a full list.
  • date: The date of the action; a date. (Optional. If the action is a "held" type, the date assumed to be the Alternate Date, Distribution Date, or Appraisal Date as appropriate; if the action is a "sold" type, it must be the date of the action, between the Date of Death/As-of Date and the Alternate Date, Distribution Date, or Appraisal Date.)
  • identifier: The CUSIP, SEDOL or ticker symbol that is undergoing the action; a string. (Optional. Default: the same identifier from the enclosing <lot> tag.)
  • shares: The shares or par-value of the security undergoing the action on the date. (Optional. Default: 1.0.)
  • description: The user-generated description of the lot on the evaluation date; a string. (Optional.)
  • manual: If the value of the lot on the evaluation date is defined by the properties value and accrual; a boolean. (Optional. Default: false.)
  • value: The value of the lot, if manual is true, calculated according to the property pervalue. (Optional.)
  • pervalue: The method for calculating the value of the lot, if manual is true; a string, one of Per Security Type, Per Share, Per Par, Total for Lot. (Optional. Default: Total for Lot.)
  • accrual: The accrual of the lot, if manual is true. (Optional.)
  • peraccrual: The method for calculating the accrual of the lot, if manual is true; a string, one of Per Security Type, Per Share, Per Par, Total for Lot. (Optional. Default: Total for Lot.)

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:

  • Sold
  • Distributed
  • Redeemed
  • Called
  • Matured
  • Liquidated
  • Transferred Out
  • Transferred Out (within Estate)

"Held" types may be any of the following strings:

  • Held
  • Held (via Spin-Off)
  • Held (via Merger)
  • Held (via Name Change)
  • Held (via Transfer In)
  • Held (via Exchange)

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.

Output

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.

output

The <output> tag encloses the entire result. Arguments includes:

  • version: The version of the output format this response is in; in major-minor format. Example: 1.0.
  • application: The application that produced this response, plus its version number; a string, a slash, and a major-minor-patch version. (Optional.) Example: EstateVal/8.1.0.
  • company: The name of the company that produced this response; a string. (Optional.) Example: Estate Valuations & Pricing Systems, Inc..
  • company-nickname: The nickname of the company that produced this response; a string. (Optional.) Example: EVP Systems.
  • address: The postal address of the company that produced this response; a string. (Optional.) Example: 1531 Chapala St., Suite 1, Santa Barbara, CA 93101.
  • phone: The phone number of the company that produced this response; a string. (Optional.) Example: (818) 313-6300.
  • site: The website of the company that produced this response; a domain name. Example: www.evpsys.com.
  • href: The URL of the company that produced this response; a URL. Example: https://www.evpsys.com/.
  • mail: The e-mail address to contact for more information about this response; an e-mail address. (Optional.) Example: developer@evpsys.com.
  • mail-support: The e-mail address to contact for technical support for this response; an e-mail address. (Optional.) Example: support@evpsys.com.

Report

"Report" responses are the results of a single portfolio report, encoded inside the common <output> tag.

report

At the top-level is the <report> tag, which includes the attributes:

  • type: The type of report: a string: "Date of Death", "Alternate Date", "Appraisal Date" or "Distribution Date".
  • death-date: The date of death; a date. (Optional, only included on "Date of Death" or "Alternate Date" reports.)
  • alternate-date: The alternate date; a date. (Optional, only included on "Alternate Date" reports.)
  • asof-date: The inventory as-of date; a date. (Optional, only included on "Appraisal Date" or "Distribution Date" reports.)
  • appraisal-date: The appraisal date; a date. (Optional, only included on "Appraisal Date" reports.)
  • distribution-date: The distribution date; a date. (Optional, only included on "Distribution Date" reports.)
  • processing-date: The date the report was created; a date.
  • name: The name of the decedendent; a string. (Optional.)
  • account: The account name or number associated with the portfolio; a string. (Optional.)
  • passthrough: The passthrough value associated with the portfolio; a string. (Optional.)
  • title-1: The first title line of the report; a string. (Optional.)
  • title-2: The second title line of the report; a string. (Optional.)
  • title-3: The third title line of the report; a string. (Optional.)

report → total

Enclosed in the <report> tag will be one <total> tag, describing the total value for the report. Attributes include:

  • value: The value for the report on the valuation date, in USD; a float. (Optional.)
  • accrual: The accrual for the report on the accrual date, in USD; a float. (Optional.)
  • income: The income for the report on the valuation date, in USD; a float. (Optional.)
  • total: The total for the report on the valuation date, in USD; a float.

report → notes

Enclosed in the <report> tag is an optional <note> tag. Its body is an arbitrary string of text that describes the portfolio.

report → lot

Enclosed in the <report> tag is any number of <lot> tags, which contain the details of each lot held by the portfolio. Attributes include:

  • number: The lot's number in the portfolio; an integer. Lots will be ordered according to their number but may not be sequential. Example: 42.
  • purchase-price: The lot's original purchase price, in USD; a float. (Optional.) Example: 23553.54.
  • description: An arbitrary description of the lot; a string. (Optional.) Example: Held in broker account 1234.

report → lot → subtotal

Enclosed in the <lot> tag will be one <subtotal> tag, describing the subtotal values for the lot. Attributes include:

  • value: The value for the lot on the valuation date, in USD; a float. (Optional.)
  • accrual: The accrual for the lot on the accrual date, in USD; a float. (Optional.)
  • income: The income for the lot on the valuation date, in USD; a float. (Optional.)
  • total: The total for the lot on the valuation date, in USD; a float.

report → lot → inventory

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:

  • type: Type type of security; a string: "[Unknown]", "Stock", "Mutual Fund", "Corporate Bond", "Municipal Bond", "Treasury Bond or Note", "Mortgage-Backed Security", "Treasury Bill", "Savings Bond, Series E/EE", "Savings Bond, Series H/HH", "Certificate of Deposit (Short Term)", "Bond (Generic Accrual)", "Common Trust Fund", "Unit Investment Trust", "Limited Partnership", "Text", "Text and Shares", "Savings Note", "Certificate of Deposit (Long Term)", "Index" or "User-Defined". ("[Unknown]" is only used when a secruity has not been evaluted yet. "Certificate of Deposit (Short Term)", "Common Trust Fund" and "Limited Partnership" are historical types that are no longer returned from evaluations. "Bond (Generic Accrual)" and "User-Defined" are manually set types, and are never returned from evaluations. "Text and Shares" is set by the special-case identifier CASH. "Text" is only returned when an identifier could not be classified; the name is set to Unknown (Identifier|CUSIP|SEDOL|Pool Number|Cryptocurrency|Currency|Commodity), depending on what pattern the identifier has.)
  • identifier: The identifier of the security, a CUSIP or SEDOL or ticker; a string. Example: 45920010.
  • identifier-original: The original identifier of the security, as entered; a string. identifier-original might be a ticker, for example, while identifier is normalized in the report to a CUSIP. (Optional.) Example: IBM.
  • shares: The number of shares/par; a float. (Optional, if the value is 0.0.) Example: 123.456.
  • name: The name of the security; a string. Example: INTERNATIONAL BUSINESS MACHINES.
  • source: The source of the pricing data; a string. (Optional.) Example: New York Stock Exchange.
  • country: The ISO code for the country the security is headquartered in. (Optional.) Example: US.
  • income: The income of the inventory item, in USD; a float. (Optional.)
  • description-1: The first line of description about the security; a string. (Optional.)
  • description-2: The second line of description about the security; a string. (Optional.)
  • description-3: The third line of description about the security; a string. (Optional.)
  • description: A description of the specific inventory item; a string. (Optional.)
  • action: The action that was taken to cause this inventory item to be in the report for the particular valuation date; a string. (Optional.) Example: Held on 11/19/1995.
  • acquisition-date: The date the inventory item was acquired; a date. (Optional.)
  • accrual-date: The accrual date for the inventory item; a date.
  • value-date: The valuation date for the inventory item; a date.

report → lot → inventory → subtotal

Enclosed in the <inventory> tag will be one <subtotal> tag, describing the subtotal values for the inventory. Attributes include:

  • value: The value for the inventory on the valuation date, in USD; a float. (Optional.)
  • accrual: The accrual for the inventory on the accrual date, in USD; a float. (Optional.)
  • income: The income for the inventory on the valuation date, in USD; a float. (Optional.)
  • total: The total for the inventory on the valuation date, in USD; a float.

report → lot → inventory → price

Enclosed in each <inventory> tag is an optional <price> tag that describes general information about the price of the lot. Attributes include:

  • value: The total value of the price, in USD; a float. (Optional.)
  • accrual: The total accrual of the price, in USD; a float. (Optional.)
  • info: Arbitrary descriptive information about the price; a string. (Optional.)

report → lot → inventory → price → last

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:

  • date: The date of the price; a date.
  • low: The low/bid/only price, in the security's native currency; a float.
  • high: The high/ask price, in the security's native currency; a float. (Optional.)
  • type: The type of low/high pricing; a string: "H/L" for high/low, "A/B" for ask/bid, "Mkt" for low-only prices.
  • mean: The mean of the low/high pricing, in the securitiy's native currency; a float.
  • mode: The pricing mode used to get the high/low pricing; a string: "Primary" for primary-exchange pricing, "Composite" for composite pricing, "Default" for default mode, which can be primary or composite depending on the valuation date.
  • adjustment: The adjustment made to the mean by capital changes, in the security's native currency; a float. (Optional.)
  • currency: The currency the security is priced in; an ISO currency code.
  • info: Arbitrary descriptive information about the price; a string. (Optional.)

report → lot → inventory → price → next

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:

  • date: The date of the price; a date.
  • low: The low/bid/only price, in the security's native currency; a float.
  • high: The high/ask price, in the security's native currency; a float. (Optional.)
  • type: The type of low/high pricing; a string: "H/L" for high/low, "A/B" for ask/bid, "Mkt" for low-only prices.
  • mean: The mean of the low/high pricing, in the security's native currency; a float.
  • mode: The pricing mode used to get the high/low pricing; a string: "Primary" for primary-exchange pricing, "Composite" for composite pricing, "Default" for default mode, which can be primary or composite depending on the valuation date.
  • adjustment: The adjustment made to the mean by capital changes, in the security's native currency; a float. (Optional.)
  • currency: The currency the security is priced in; an ISO currency code.

report → lot → inventory → price → mean

Enclosed in each <price> is a single <mean> tag, giving the weighted mean of the <last> and any <next> price. Attributes include:

  • mean: The weighted mean, in the security's native currency; a float.
  • adjustment: The adjustment made to the weighted mean, in the security's native currency; a float. (Optional.)
  • value: The value of the mean price, in USD; a float.
  • accrual: The accrual of the mean price, in USD; a float. (Optional.)
  • total: The total of the mean price, in USD; a float.

report → lot → inventory → generic-value

Optionally enclosed in each <inventory> may be a single <generic-value> tag, giving any value arbitrarily provided by the portfolio. Attributes include:

  • value: The generic value, in USD; a float.

report → lot → inventory → generic-accrual

Optionally enclosed in each <inventory> may be a single <generic-accrual> tag, giving any accrual arbitrarily provided by the portfolio. Attributes include:

  • accrual: The generic accrual, in USD; a float.
  • info: A description of the accrual; a string. (Optional.)

report → lot → inventory → dividends

Optionally enclosed in each <inventory> may be a single <dividends> tag, enclosing information about individual dividends. Attributes include:

  • info: Arbitrarily information about the dividends; a string. (Optional.)
  • currency: The default currency for the dividends; an ISO currency code. Example: "USD". (Optional.)

report → lot → inventory → dividends → adjustments

report → lot → inventory → dividends → accruals

report → lot → inventory → dividends → values

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.

report → lot → inventory → dividends → adjustments, accruals, values → dividend

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:

  • ex-date: The ex-date of the dividend; a date.
  • record-date: The record-date of the dividend; a date.
  • pay-date: The pay-date of the dividend; a date.
  • dividend: The dividend value, in the dividend's native currency; a float.
  • currency: The currency the dividend value is in; an ISO currency code. (Optional.)
  • currency-rate: The currency-conversion rate between the currency and USD; a float. (Optional.)
  • note: An arbitrarily description of any special attributes of the dividend; a string. (Optional.)
  • total: The total value of the diviend, in USD; a float. (Optional.)

report → lot → inventory → bond

Optionally enclosed in the <inventory> tag, the <bond> tag provides details for bond and bond-like securities. Attributes include:

  • accrual-date: The date the security as accrued to; a date.
  • issue-date: The issue date of the security; a date. (Optional.)
  • maturity-date: The maturity date of the security; a date. (Optional.)
  • call-date: The call date of the security; a date. (Optional.)
  • last-coupon-date: The coupon date of the security previous to the accrual date; a date. (Optional.)
  • next-coupon-date: The coupon date of the security after the accrual date; a date. (Optional.)
  • rate: The interest rate of the security, on the accrual date; a float. (Optional.)
  • status: The status of the security on the accrual date; a string: "Active", "In Arrears", or "Default". (Optional.)
  • info: Arbitrary information about the security; a string. (Optional.)
  • note: Arbitrary information about the security; a string. (Optional.)
  • days: The number of days between the last coupon payment and the accrual date; an integer.
  • accrual: The value of the accrual on the accrual date, in USD; a float.

report → lot → inventory → mbs

Optionally enclosed in the <inventory> tag, the <mbs> tag provides details for mortgage-backed securities: GNMAs, FNMAs, FHMLCs and CMOs. Attributes include:

  • type: The type of mortgage-backed security; a string: "GNMA I", "GNMA II", "FNMA", "FHMLC", "CMO".
  • maturity-date: The maturity date of the mortgage-backed security; a date.
  • rate: The interest rate of the mortgage-backed security on the accrual date; a float.
  • delay: The number of days after the coupon date that the coupon pays; an integer. (Optional.)
  • factor: The pay-down factor of the mortgage-backed security on the accrual date; a float.
  • adjustment: The adjustment to the mean if the mortgage-backed security pays between pricing days; a float.
  • info: Arbitrary information about the mortgage-backed security; a string. (Optional.)

report → lot → inventory → mbs → payment

Enclosed in the <mbs> tag, any number of <payment> tags give details about the mortgage-backed security's payments. Attributes include:

  • start-date: The start-date of this payment; a date.
  • end-date: The end-date of this payment; a date.
  • accrual: The accrual of this payment, in USD; a float.
  • value: The value of this payment, in USD; a float.

report → lot → inventory → uit

Optionally enclosed in the <inventory> tag, a single <uit> tag give details about a unit investment trust. Attributes include:

  • adjustment: The adjustment to the mean casued by the UIT, in USD; a float.

report → lot → inventory → notes

Optionally enclosed in the <inventory> tag, a single <notes> tag further encloses individual <note> tags. There are no attributes.

report → lot → inventory → notes → note

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.

billing

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 responses:

  • time: The time the billing record was created; an RFC 3339 / ISO 8601 timestamp.

billing → item

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.

  • identifier: The security identifier used to generation the evaluation; a string.
  • type: The type of evaluation performed on the identifier; a string: "none", "dod", "alt", "apr", "dst" or "cmo".
  • surcharge: The type of surcharge added to the cost, a string: "none" or "foreign".
  • date: The evaluation date for the security; a date.
  • cost: The amount billed for the evaluation of the identifier, in USD; a float.

Examples

A Date of Death report (XML, JSON, PDF)

An Alternate Date report (XML, JSON, PDF)

Sample Code

Code to create, modify, and build a report (Python)

Code to evaluate a single security (Visual Studio C++, Powershell)