Documentation

Overview

EVP Everywhere uses REST HTTP queries through https://api.evpsys.com/1.3 to create, manage, and evaluate portfolios using Estate Valuations & Pricing Systems software: EstateVal, CostBasis, GiftVal, and CapWatch capital-change data. The current canonical public API URL shape puts the API version before the endpoint path, for example /1.3/estateval/report.

All endpoints return HTTP response-codes; 2xx values represent a successful request, 4xx values represent a problem with the client request, and 5xx values represent a problem on the server side. Additional data can be submitted 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.

Interactive API documentation is available at /api/docs and loads the current OpenAPI contract automatically. The hosted page disables browser Try it out controls because authenticated API calls require customer-specific credentials and environment verification; use the examples and OpenAPI schema as the public contract, then call the API from your integration environment.

Machine-readable OpenAPI documentation is available as /api/openapi.yaml and /api/openapi.json. Version-specific artifacts are also available for 1.0, 1.1, and 1.2, and 1.3. The legacy /api/api.raml file remains available, but OpenAPI is the preferred machine-readable contract.

Start here

New integrations should start with the current versioned base URL, https://api.evpsys.com/1.3, and use Basic Authentication with the EVP Systems Client Token as the user name and the Account Information Key as the password. The hosted Swagger UI at /api/docs is the canonical endpoint reference, but Try it out is disabled; send authenticated calls from your own integration environment.

Choose the response format. Use output=json or output=xml for structured responses. Report downloads can also request pdf, rtf, txt, or xlsx when the endpoint supports rendered report output.
Run a quick report. For a single-security EstateVal smoke test, call GET /1.3/estateval/report?output=json&identifier=MSFT&date=20161119&report=dod. Use report=cst or report=gft only on /1.3.
Use the async lifecycle for portfolios. Create a portfolio with POST /1.3/portfolio, start a report with POST /1.3/portfolio/{portfolio-id}/estateval/report or the CostBasis/GiftVal product-specific report endpoint, poll the Location status URL until the response status is ok, then download or delete the completed report as needed.
Handle errors by status code. A missing-authentication 401 response may have no JSON/XML body and includes WWW-Authenticate. Other client/server errors generally return the standard <output> envelope with <status>error</status> in the requested format when possible.

Changelog

The preferred API version selector is the URL prefix: /1.0/..., /1.1/..., or current /1.3/.... The legacy version query-string argument remains supported, and unversioned URLs remain supported as stable legacy/default behavior. If a URL version and a conflicting version= query string are both supplied, the request returns HTTP 400. CapWatch, CostBasis, and GiftVal are version 1.3 features and require the /1.3 URL prefix; they are not available on /1.0, /1.1, /1.2, or unversioned legacy URLs.

Version 1.3

Made /1.3 the current public API contract and hosted docs default.
Kept /1.2 as the pre-9.3 API surface; CostBasis, GiftVal, CapWatch, and status payload enhancements are /1.3-only.
Added version 1.3 OpenAPI and XSD artifacts; current /api/openapi.yaml and /api/openapi.json now alias version 1.3.
Corrected version 1.3 report creation, completed-report export, and XML schema validation so /1.3 portfolio and report responses validate as version 1.3.
Relaxed the version 1.3 report XSD identifier pattern so short alphanumeric original identifiers emitted by completed reports validate correctly.
Added CostBasis and GiftVal report selectors, cst and gft, with CostBasis/GiftVal portfolio fields for full portfolio uploads. These selectors require the /1.3 URL prefix.
Added product-specific CostBasis/GiftVal full-report lifecycle endpoints under /1.3/portfolio/{portfolio-id}/costbasis/report and /1.3/portfolio/{portfolio-id}/giftval/report. The single-lot incremental endpoint does not support cst or gft.
Added CapWatch endpoints under /1.3/capwatch for security search, action list, and action detail lookups.
For GET /1.3/portfolio/{portfolio-id}/estateval/report/{report-id}/status, GET /1.3/portfolio/{portfolio-id}/costbasis/report/{report-id}/status, and GET /1.3/portfolio/{portfolio-id}/giftval/report/{report-id}/status, added optional busy-mode support so desktop API callers can receive a busy-message headline for non-Progress busy displays while polling long-running reports.

Version 1.2

Added machine-readable OpenAPI 3.0 artifacts at /api/openapi.yaml, /api/openapi.json, and version-specific /api/openapi-1.0.*, /api/openapi-1.1.*, and /api/openapi-1.2.* paths.
Added report inventory identifier metadata: identifier-type and optional identifier-original-type.
Added canonical URL-versioned API routes such as GET /1.2/estateval/report while preserving unversioned legacy routes.
Added version 1.2 XSD links for documented EstateVal endpoints.

Version 1.1

Added a time timestamp attribute to <billing> in report responses.

Version 1.0

Baseline schema for authentication, portfolio lifecycle endpoints, EstateVal report generation, JSON/XML response formats, report download formats, and XSD validation links.

Current endpoint behavior available in all supported versions

Added optional caller-attribution headers: X-EVP-Actor-Email and X-EVP-Actor-Windows-User.
Added account preference endpoints, GET /1.3/preferences and PUT /1.3/preferences, exposing approved EstateVal [Report] Title All and [Report] Disclaim.Foot preferences.
Added renumber support for portfolio updates.
Added stored portfolio report-file-name plus per-report file-name / file-id overrides for report rendering.
Added refresh support to force server-side rehydration instead of using stored fallback security/currency data; adjusted-inventory action symbols and action dates are included for alt, dst, and apr reports.
Added Alternate Date adjusted-inventory Other actions with optional custom other report text.
Added report run correlation metadata: sessionid, lotcount, and securitycount.
Added support for uploaded portfolio fallback/history data: security/data, currency/rate, history, reportruns/reportrun, and security/valuations/valuation. Uploaded report history is treated as caller-supplied/imported; source="api" is reserved for server-side report execution.
Documented the existing dodclose Date of Death with Close report type.
Portfolio share/par attributes are normalized without adding unnecessary trailing decimal zeroes.
Large portfolio report requests return the report-id before server-side portfolio repair and batch preparation; progress is reported through the status endpoint.
hilo request-level Primary/Composite pricing mode is supported on both full portfolio report requests and single-lot portfolio report requests.
Added request-scoped calculation preference arguments for report requests: calc-stale-count, calc-mortgage-input, calc-full-coupon, calc-trust-fund-days, calc-extra-day-accrual, calc-user-defined, and calc-payment-column.

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 requests 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 contains all the same data. XML tags are equivalent to JSON dictionaries; XML attributes are converted 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:

Authorization: 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.

Caller Attribution Headers

EVP Everywhere also supports optional caller-attribution headers for direct API integrations that authenticate with a shared client token or shared account credentials but still need per-request user attribution.

X-EVP-Actor-Email: The preferred per-request caller identity. Example: jane.doe@example.com.
X-EVP-Actor-Windows-User: An optional Windows-account value. Example: DOMAIN\jdoe.

These headers are metadata only:

They do not replace or change authentication.
They are not credentials.
If both are supplied, current usage visibility prefers X-EVP-Actor-Email.
If only X-EVP-Actor-Windows-User is supplied, it is used as the fallback caller value.

For direct API callers that want to avoid current shared-runtime attribution such as Ubuntu, send the upstream user on report and evaluation requests. Example:

X-EVP-Actor-Email: jane.doe@example.com
X-EVP-Actor-Windows-User: DOMAIN\jdoe

In the current Invoice Mailer summary/details spreadsheets, the existing User column will prefer the supplied actor e-mail and otherwise fall back to the supplied Windows-account value when available.

Common Arguments

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

version: Legacy query-string version selector for the request and response data, either 1.0, 1.1, 1.2, or 1.3; a version number. Prefer the URL prefix, for example /1.3/portfolio. Unversioned URLs default to legacy 1.0 behavior and do not float to the newest version. A conflicting version= query string returns HTTP 400. (Optional. Default for unversioned URLs: 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 for supported report renderings. Legacy compatibility outputs are not recommended for new integrations.

Request-Level Report Calculation Arguments

Report-producing endpoints can accept request-scoped calculation preference overrides. These are merged with account preferences for the current evaluation only and do not modify stored account preferences. Boolean-style calculation preferences use 0 or 1.

calc-stale-count: Override [Calc] Stale Count; an integer from 0 through 999. (Optional.)
calc-mortgage-input: Override [Calc] Mortgage Input; 0 or 1. (Optional.)
calc-full-coupon: Override [Calc] Full Coupon; 0 or 1. (Optional.)
calc-trust-fund-days: Override [Calc] Trust Fund Days; 0 or 1. (Optional.)
calc-extra-day-accrual: Override [Calc] Extra Day Accrual; 0 or 1. (Optional.)
calc-user-defined: Override [Calc] User Defined Default; one of Per Security Type, Per Share, Per Par, or Total for Lot. (Optional.)
calc-payment-column: Override [Calc] Payment Column; one of Default, Include, or Omit; an empty value is treated as Default. (Optional.)

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 /1.3/estateval/report`

GET /1.3/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, ISIN, SEDOL, OCC option identifier, or ticker symbol; a string. (Optional. Default: "IBM".)
date: The date-of-death for the evaluation for dod, dodclose, and alt reports; the holdings as-of date for apr, dst, and cst reports; the gift date for gft reports; a date in YYYYMMDD format. (Optional. Default: 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: date value.)
report: dod for date-of-death reports, dodclose for date-of-death reports using closing prices, alt for alternate date, apr for appraisal date, dst for distribution date, cst for CostBasis, or gft for GiftVal. cst and gft are version 1.3 and require the /1.3 URL prefix. (Optional. Default: dod.)
hilo: default, primary, or composite to select the request-level Primary/Composite pricing mode. It can be used with account preferences; it does not modify the stored account preferences. (Optional.)
calc-*: Request-level report calculation preference overrides, defined above. (Optional.)
passthrough: A value that is passed through EVP Everywhere to the invoice details, allowing the evaluation to be associated with a particular 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, 1.2, 1.3).

Example:

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

CapWatch Endpoints

The CapWatch endpoints are version 1.3 and expose classic capital-change searches for authenticated clients. They require the /1.3 URL prefix and are not available on /1.0, /1.1, /1.2, or unversioned legacy URLs. Security search is free; action list and detail responses may include usage metadata for client records. Usage writes fail closed before billable response data is returned.

`GET /1.3/capwatch/securities`

Searches CapWatch securities by 6/8/9-character CUSIP prefix or target/initial name prefix. Optional date_first and date_last arguments limit capital-change dates. Results return the classic target CUSIP and target name display fields. This response can be validated by its version 1.3 XSD (1.3).

Input: In addition to the common output query-string argument, this endpoint accepts:

query: CUSIP prefix, target name prefix, or initial name prefix. (Required.)
date_first: First capital-change date to include, in YYYYMMDD format. (Optional.)
date_last: Last capital-change date to include, in YYYYMMDD format. (Optional.)

Example:

GET https://api.evpsys.com/1.3/capwatch/securities?output=xml&query=IBM

`GET /1.3/capwatch/securities/{cusip}/actions`

Returns action numbers, action types, dates, and display fields for a target CUSIP using classic duplicate/update suppression. Successful calls may include informational usage metadata for client records. This response can be validated by its version 1.3 XSD (1.3).

Input: In addition to the common output query-string argument, this endpoint accepts optional date_first and date_last filters in YYYYMMDD format.

Example:

GET https://api.evpsys.com/1.3/capwatch/securities/03093810/actions?output=xml

`GET /1.3/capwatch/actions/{number}`

Returns action detail text, type, date, initial security fields, and target security fields for the requested action number. Successful calls may include informational usage metadata for client records; unknown action numbers return 404 and do not emit usage. This response can be validated by its version 1.3 XSD (1.3).

Input: In addition to the common output query-string argument, the path contains the numeric CapWatch action number.

Example:

GET https://api.evpsys.com/1.3/capwatch/actions/1051390?output=xml

Account Preference Endpoints

The following endpoints manage approved EstateVal preferences for the authenticated account. They do not allow arbitrary ini-file editing and do not modify global estates.ini. The exposed preferences are [Report] Title All, which controls whether non-empty report title lines repeat on every report page, and [Report] Disclaim.Foot, which controls the footer disclaimer text shown on generated EstateVal reports.

Managed account preferences are defaults for that authenticated account/application scope. Request-level pricing arguments such as hilo=primary, hilo=composite, or hilo=default are merged into the effective report preferences for that request only and do not modify the stored account preference file. In XML, configured="false" means the response is showing the server default rather than an account-specific override; the equivalent JSON key is @configured.

`GET /1.3/preferences`

GET /1.3/preferences returns the authenticated account's managed EstateVal preference values.

Output: Returns a response as follows. This response can be validated by its XSD (1.0, 1.1, 1.2, 1.3).

<output version="1.0">
 <status>ok</status>
 <preference section="Report" name="Disclaim.Foot" value="" configured="false" />
 <preference section="Report" name="Title All" value="FALSE" configured="false" />
</output>

`PUT /1.3/preferences`

PUT /1.3/preferences updates approved EstateVal preferences for the authenticated account.

Input: This endpoint accepts a preferences input encoded inside an <input> tag. Each <preference> requires section, name, and value. Boolean values such as true, yes, and 1 are normalized to TRUE; false, no, and 0 are normalized to FALSE. Footer text for Disclaim.Foot may be blank to clear the footer, may be up to 2048 characters, and uses {{NEWLINE}} for explicit line breaks. JSON callers may also send actual newline characters, which are normalized to {{NEWLINE}}.

<input>
 <preferences>
  <preference section="Report" name="Title All" value="TRUE" />
  <preference section="Report" name="Disclaim.Foot" value="Report generated by EVP Systems" />
 </preferences>
</input>

The equivalent JSON input is:

{
 "input": {
  "preferences": {
   "preference": [
    {
     "@section": "Report",
     "@name": "Title All",
     "@value": "TRUE"
    },
    {
     "@section": "Report",
     "@name": "Disclaim.Foot",
     "@value": "Report generated by EVP Systems"
    }
   ]
  }
 }
}

Output: Returns the updated managed preference values. This response can be validated by its XSD (1.0, 1.1, 1.2, 1.3).

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 /1.3/portfolio
The resulting portfolio-id used to edit the contents of the portfolio with PUT /1.3/portfolio/{portfolio-id}
An EstateVal report can be started with POST /1.3/portfolio/{portfolio-id}/estateval/report
A CostBasis or GiftVal full-portfolio report can be started with the product-specific POST /1.3/portfolio/{portfolio-id}/costbasis/report or POST /1.3/portfolio/{portfolio-id}/giftval/report endpoints
The resulting report-id is used to monitor the report's progress by polling the matching status endpoint, for example GET /1.3/portfolio/{portfolio-id}/estateval/report/{report-id}/status, GET /1.3/portfolio/{portfolio-id}/costbasis/report/{report-id}/status, or GET /1.3/portfolio/{portfolio-id}/giftval/report/{report-id}/status
Output (as JSON, XML, PDF, rich text, or plain text) can be retrieved from the matching report endpoint, for example GET /1.3/portfolio/{portfolio-id}/estateval/report/{report-id}, once it is ready
A list of previously created portfolios is listed by using GET /1.3/portfolio, while previously generated reports for each are returned from GET /1.3/portfolio/{portfolio-id}/estateval/report or the product-specific CostBasis/GiftVal report list endpoints

`POST /1.3/portfolio`

POST /1.3/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 /1.3/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, 1.3).

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

`PUT /1.3/portfolio/{portfolio-id}`

PUT /1.3/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. In addition to the common query-string arguments defined above, this endpoint also accepts renumber. When renumber=yes, surviving lots are compacted into contiguous lot numbers after the update is applied; otherwise the legacy sparse numbering behavior is preserved.

Output: Returns a response as follows. This response can be validated by its XSD (1.0, 1.1, 1.2, 1.3).

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

`GET /1.3/portfolio`

GET /1.3/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, 1.2, 1.3).

<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 /1.3/portfolio/{portfolio-id}`

GET /1.3/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 /1.3/portfolio/{portfolio-id}`

DELETE /1.3/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, 1.3).

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

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

PUT /1.3/portfolio/{portfolio-id}/estateval/report adds a single lot to a portfolio, evaluates only that lot, and returns a report that includes information only about that lot. Like GET /1.3/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 /1.3/portfolio. Portfolio-level information like dates and passthrough data are defaulted to the current values on the portfolio; if they are defined as part of the call, the portfolio-level values are overwritten.

This single-lot incremental endpoint does not support cst or gft. Use the full-portfolio CostBasis/GiftVal report endpoints because CostBasis and GiftVal require product-specific portfolio and lot context such as costbasis-date, costbasis-mode, gift-basis, and gift-accflag.

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, dodclose, 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, dodclose for date-of-death reports using closing prices, alt for alternate date, apr for appraisal date, or dst for distribution date. (Optional. Default: dod.)
hilo: default, primary, or composite to select the request-level Primary/Composite pricing mode. It can be used with account preferences; it does not modify the stored account preferences. (Optional.)
calc-*: Request-level report calculation preference overrides, defined above. (Optional.)
passthrough: A value that is passed through EVP Everywhere to the invoice details, allowing the evaluation to be associated with a particular client, account or portfolio. (Optional. Default: Current portfolio value; if none is defined at the portfolio level, the default is empty.)
refresh: true/false. When omitted or false, uploaded security/data and currency/rate fallback already stored on the portfolio is used first and only missing data is rehydrated from server-side sources. When true, matching fallback for the report date(s) is stripped before the evaluation so the server must refresh it; for adjusted alt, dst, and apr inventories, matching fallback for nested action symbols/dates is also stripped. (Optional. Default: false.)
sessionid: A caller-supplied report-run correlation ID, 1-64 URL-safe characters (A-Z, a-z, 0-9, ., _, -). If omitted, the server generates one. (Optional.)
lotcount: Caller-supplied non-negative lot count metadata to store with the report run. It does not change which lots are evaluated. (Optional.)
securitycount: Caller-supplied non-negative security count metadata to store with the report run. It does not change which securities are evaluated. (Optional.)

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

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

POST /1.3/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.

CostBasis and GiftVal full-portfolio reports may still be requested here using report=cst or report=gft for compatibility, but only on the version 1.3 URL prefix. New integrations should prefer the product-specific /1.3/portfolio/{portfolio-id}/costbasis/report and /1.3/portfolio/{portfolio-id}/giftval/report endpoints documented below.

Input: The endpoint accepts the following query-string arguments, in addition to the common ones defined above:

report: dod for date-of-death reports, dodclose for date-of-death reports using closing prices, alt for alternate date, apr for appraisal date, dst for distribution date, cst for CostBasis, or gft for GiftVal. cst and gft are version 1.3 and require the /1.3 URL prefix. (Optional. Default: dod.)
hilo: default, primary, or composite to select the request-level Primary/Composite pricing mode. It can be used with account preferences; it does not modify the stored account preferences. (Optional.)
calc-*: Request-level report calculation preference overrides, defined above. (Optional.)
file-name: Overrides the file name used for report rendering, which controls the visible File ID in generated output formats that derive it from the evaluated EVP file name. (Optional.)
file-id: Compatibility alias for file-name. (Optional.)
refresh: true/false. When omitted or false, uploaded security/data and currency/rate fallback already stored on the portfolio is used first and only missing data is rehydrated from server-side sources. When true, matching fallback for the report date(s) is stripped before the evaluation so the server must refresh it; for adjusted alt, dst, and apr inventories, matching fallback for nested action symbols/dates is also stripped. (Optional. Default: false.)
sessionid: A caller-supplied report-run correlation ID, 1-64 URL-safe characters (A-Z, a-z, 0-9, ., _, -). If omitted, the server generates one. (Optional.)
lotcount: Caller-supplied non-negative lot count metadata to store with the report run. It does not change which lots are evaluated. (Optional.)
securitycount: Caller-supplied non-negative security count metadata to store with the report run. It does not change which securities are evaluated. (Optional.)

If the portfolio has a stored report-file-name value, it is used as the default when neither file-name nor file-id is supplied. A request-level override always wins.

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

The first indicates a successful start to the report generation, with {report-id} used to identify the report in other calls. The HTTP status is 202 Accepted, and the response includes a Location header pointing to /portfolio/{portfolio-id}/estateval/report/{report-id}/status.

<output version="1.0">
 <status>ok</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>

`POST /1.3/portfolio/{portfolio-id}/costbasis/report` and `POST /1.3/portfolio/{portfolio-id}/giftval/report`

These product-specific full-report endpoints are preferred for CostBasis and GiftVal. They are version 1.3, require the /1.3 URL prefix, and are not available on /1.0, /1.1, /1.2, or unversioned legacy URLs. POST /1.3/portfolio/{portfolio-id}/costbasis/report always creates a CostBasis (cst) report, and POST /1.3/portfolio/{portfolio-id}/giftval/report always creates a GiftVal (gft) report. Do not send a report argument unless it matches the endpoint's fixed selector; conflicting values are rejected.

The product-specific lifecycle endpoints are:

POST /1.3/portfolio/{portfolio-id}/costbasis/report and POST /1.3/portfolio/{portfolio-id}/giftval/report
GET /1.3/portfolio/{portfolio-id}/costbasis/report and GET /1.3/portfolio/{portfolio-id}/giftval/report
GET /1.3/portfolio/{portfolio-id}/costbasis/report/{report-id} and GET /1.3/portfolio/{portfolio-id}/giftval/report/{report-id}
GET /1.3/portfolio/{portfolio-id}/costbasis/report/{report-id}/status and GET /1.3/portfolio/{portfolio-id}/giftval/report/{report-id}/status
DELETE /1.3/portfolio/{portfolio-id}/costbasis/report/{report-id} and DELETE /1.3/portfolio/{portfolio-id}/giftval/report/{report-id}

The input and output shapes are the same as the EstateVal full-report lifecycle endpoints, including the request-level hilo and calc-* report calculation preference arguments. The Location header returned from a successful product-specific POST points to the matching product-specific status URL. Product-specific list, get, status, and delete calls only access reports of the matching product type, so a CostBasis URL will not retrieve or delete a GiftVal report ID, and vice versa. These responses reuse the EstateVal report lifecycle XSDs linked in the corresponding sections.

There are no product-specific single-lot incremental PUT endpoints for CostBasis or GiftVal.

`GET /1.3/portfolio/{portfolio-id}/estateval/report/{report-id}/status`

GET /1.3/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: In addition to the common query-string arguments, defined above, allowed query-string arguments are:

busy-mode: Optional desktop busy display mode. For version 1.3 status calls, non-Progress values such as Top Stories, Business Headlines, World Headlines, Sports Headlines, Health Headlines, Science Headlines, Technology Headlines, Politics Headlines, Entertainment Headlines, Odd Headlines, or Quotes request a headline/message in the response. Progress or omitted values return normal status progress only. (Optional.)

Output: Returns one of the follow responses. These responses can be valided by their XSD (1.0, 1.1, 1.2, 1.3).

The first indicates that the report generation has successfully completed, and the report itself can be requested using GET /1.3/portfolio/{portfolio-id}/estateval/report/{report-id}.

For reports generated and queried using version 1.3, the ok result will also include the <report>, <disclaimers> and <billing> elements of a GET /1.3/portfolio/{portfolio-id}/estateval/report call, so the call to retrieve the report (at least in JSON or XML format) will not need to be made. When a recognized non-Progress busy-mode is supplied to a version 1.3 status call, the response may also include <busy-message> for the desktop busy display.

<output version="1.3">
 <status>ok</status>
 <busy-message>{headline-or-message}</busy-message>
</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.3">
 <status>pending</status>
 <pending-percent>{pending-percent}</pending-percent>
 <pending-text>{pending-text}</pending-text>
 <busy-message>{headline-or-message}</busy-message>
</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 /1.3/portfolio/{portfolio-id}/estateval/report/{report-id}`

GET /1.3/portfolio/{portfolio-id}/estateval/report/{report-id} returns the report, once GET /1.3/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. If a file-name / File ID override was used when the report was created, repeated downloads of that same report-id will continue to use the same effective value.

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

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

GET /1.3/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, 1.2, 1.3).

<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|dodclose|alt|apr|dst|cst|gft}" report_status="{ok|pending}" report_percent="{report-percent-complete}" report_time_created="{report-time-created}" report_time_updated="{report-time-created}" />
 ...
</output>

`DELETE /1.3/portfolio/{portfolio-id}/estateval/report/{report-id}`

DELETE /1.3/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, 1.3).

<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 portfolio base date; the date of death for EstateVal reports, the gift date for GiftVal reports, or the As-of Date when a CostBasis portfolio uses costbasis-mode="As-of Date"; a date. (Optional for CostBasis Pricing Date portfolios that provide lot-level costbasis-date values.)
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.)
costbasis-mode: CostBasis pricing mode, either Pricing Date or As-of Date. (Optional. Default: Pricing 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.)
report-file-name: A stored default file name for report rendering. When present, later POST /1.3/portfolio/{portfolio-id}/estateval/report calls use it as the default visible File ID unless a request-level file-name override is supplied. (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.)
lot-description: The user-generated description of the lot across all inventory adjustment types; a string. (Optional.)
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.)
currency: The currency of the user-entered values, if manual is true; a currency. (Optional. Default: USD.)
costbasis-date / basis-date: The lot-level CostBasis/Basis Date in YYYYMMDD format, stored as the lot's CostBasis application date. Required for CostBasis reports unless a portfolio-level fallback date is intended. (Optional.)
gift-accflag: GiftVal accrued-income behavior, either Default/0, Include/1, or Omit/2. (Optional.)
gift-basis: GiftVal lot basis amount. (Optional.)

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 for the inventory adjustment type; 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.)
currency: The currency of the user-entered values, if manual is true; a currency. (Optional. Default: USD.)

`portfolio` → `lot` → `alt` → `action`

`portfolio` → `lot` → `dst` → `action`

`portfolio` → `lot` → `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.
other: Custom report action text when type="Other"; a string. For example, other="Tendered" is reported as Tendered on {date}. If omitted or blank, the report uses Valued on {date}. (Optional; only used for Alternate Date Other actions.)
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.)
currency: The currency of the user-entered values, if manual is true; a currency. (Optional. Default: USD.)

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. type="Other" is treated as a sold-style action and can use the other attribute to provide custom report text.

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

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

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

`portfolio` → `security`

Each <lot> element represents a single holding of a specific security. To edit the details of those securities, you can set the attributes below:

identifier: The CUSIP, SEDOL or ticker symbol that corresponds to the identifier element in a <lot> for which data is being set.
name: The name of the security; a string. (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.)

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>

`portfolio` → `security` → `data`

Portfolio inputs may include previously observed security data as fallback data for later evaluations. This data is merged into the stored portfolio and is used before server-side sources when it matches the report date. For adjusted alt, dst, and apr inventories, nested action symbols and action dates are also considered relevant report data. To force the server to ignore matching fallback data and refresh from server-side sources, use the refresh=true query-string argument on report-generation endpoints. Security fallback can be sent using the public identifier attribute or the XVF-style symbol attribute.

Attributes on <data> include:

date: The date this fallback data applies to; a date. (Required.)
currency: The native currency for prices or values in the data block. (Optional.)
country: The ISO country code associated with the security data. (Optional.)
currentcoupondate / previouscoupondate: Coupon dates used for bond-style calculations. (Optional.)

Common children of <data> include:

price: Price data for the security. It may contain last and next children. Each child contains the price as its body and accepts date, type, mode, and high attributes. price may also include a currency attribute.
dividend: Dividend data. The body is the dividend value; optional attributes include number, ex, record, pay, type, flag, note, split, principal, and currency.
split: Split ratio for the date. (Optional.)
generic: Manually supplied value/accrual fallback, with optional value and accrual children. (Optional.)
bond: Bond-specific fallback data, including optional factor children. (Optional.)
note and flag: Additional data annotations. (Optional.)

<input version="1.0">
 <portfolio death-date="20240531">
  <lot number="1" identifier="IBM" shares="100" />
  <security identifier="IBM" name="INTERNATIONAL BUSINESS MACHINES" source="uploaded">
   <data date="20240531" currency="USD" country="US">
    <price currency="USD">
     <last date="20240531" type="Mkt" mode="Default">166.85</last>
    </price>
    <generic>
     <value>166.85</value>
    </generic>
   </data>
  </security>
 </portfolio>
</input>

`portfolio` → `currency` → `rate`

Portfolio inputs may include currency conversion rates used by fallback security data.

type: The <currency> attribute naming the currency code being converted to USD; a currency. (Required.)
date: The <rate> attribute naming the date the conversion rate applies to; a date. (Required.)
rate: The conversion rate as the <rate> tag body; a decimal. (Required.)

<input version="1.0">
 <portfolio death-date="20240531">
  <currency type="EUR">
   <rate date="20240531">1.0865</rate>
  </currency>
 </portfolio>
</input>

`portfolio` → `history`

Portfolio inputs may include valuation history markers. History entries are merged by type, date, date1, and date2.

type: History type, such as dod, dodclose, alt, apr, dst, cst, or gft. (Required.)
date: The main history date. (Required.)
date1 / date2: Optional additional dates for two-date report types. (Optional.)

`portfolio` → `reportruns` → `reportrun`

Portfolio inputs may include report-run metadata for client-side correlation or migration from previously evaluated data.

sessionid: Client or server report-run correlation ID. (Required.)
reporttype: Report type, such as dod, dodclose, alt, apr, dst, cst, or gft. (Optional.)
product: Product that produced the run, such as estateval, costbasis, or giftval. (Optional.)
source, status, mode, message, origin, and confidence: Additional metadata. (Optional.) Uploaded history may use client/import provenance such as legacy, desktop, or imported; source="api" and server report IDs are reserved for reports actually run by the API server.
basedate / otherdate: Report dates. The aliases date1 and date2 are also accepted. (Optional.)
runat: Report-run timestamp. (Optional.)
lotcount / securitycount: Non-negative client metadata counts. (Optional.)

A <reportrun> may contain <lotref> children with lotid, number, symbol, and shares attributes.

When a portfolio upload includes report-run history, the server treats that history as caller-supplied/imported provenance unless it was created by a server-side report execution. Caller uploads cannot create or overwrite server-authoritative source="api" rows.

`portfolio` → `security` → `valuations` → `valuation`

Portfolio inputs may include per-security valuation metadata. The enclosing <security> must identify the security by identifier or symbol.

sessionid: Report-run correlation ID for this valuation. (Required.)
reporttype: Report type, such as dod, dodclose, alt, apr, dst, cst, or gft. The alias type is also accepted. (Required.)
product: Product that produced the valuation, such as estateval, costbasis, or giftval. (Optional. Default: estateval.)
source, status, origin, and confidence: Additional metadata. (Optional.) Uploaded valuation history may use client/import provenance such as legacy, desktop, or imported; source="api" and server report IDs are reserved for valuations recorded by API report execution.
basedate / otherdate: Report dates. The aliases date1 and date2 are also accepted. (Optional.)
runat: Valuation timestamp. (Optional.)
datadate: Date of the security data used by the valuation. For adjusted alt, dst, and apr reports, server-generated valuation metadata may use a nested action date when the action security is valued from that date. (Optional.)

<input version="1.0">
 <portfolio death-date="20240531">
  <reportruns>
   <reportrun sessionid="client-run-123" reporttype="dod" product="estateval" status="ok" basedate="20240531" lotcount="1" securitycount="1">
    <lotref number="1" symbol="IBM" shares="100" />
   </reportrun>
  </reportruns>
  <security identifier="IBM">
   <valuations>
    <valuation sessionid="client-run-123" reporttype="dod" product="estateval" status="ok" basedate="20240531" datadate="20240531" />
   </valuations>
  </security>
 </portfolio>
</input>

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", "Date of Death with Close", "Alternate Date", "Appraisal Date" or "Distribution Date".
death-date: The date of death; a date. (Optional, only included on "Date of Death", "Date of Death with Close", 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" and "Date of Death with Close" 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 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 security has not been evaluated 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-type: Type of identifier; a string: "cusip", "sedol", "isin", "cryptocurrency", "currency", "commodity", "poolnumber", "dummy", "ticker", "invalid" or "unknown". (Output version 1.2 or greater only.) Example: cusip.
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.
identifier-original-type: Type of identifier-original; a string: "cusip", "sedol", "isin", "cryptocurrency", "currency", "commodity", "poolnumber", "dummy", "ticker", "invalid" or "unknown". (Optional. Output version 1.2 or greater only.) Example: ticker.
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 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.
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 dividend, 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 caused 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.

`disclaimers`

Optionally enclosed in the top-level <output> tag is the <disclaimers> tag, which has no attributes.

`disclaimers` → `header`

`disclaimers` → `bottom`

`disclaimers` → `footer`

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.

`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, 1.2, and 1.3 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, Python with a .txt extender)

Code to evaluate a single security (Visual Studio C++, Powershell, Powershell with a .txt extender)

Overview

Start here

Changelog

Version 1.3

Version 1.2

Version 1.1

Version 1.0

Current endpoint behavior available in all supported versions

Data Conventions

Authentication

Caller Attribution Headers

Common Arguments

Request-Level Report Calculation Arguments

Endpoints

Convenience Endpoints

GET /1.3/estateval/report

CapWatch Endpoints

GET /1.3/capwatch/securities

GET /1.3/capwatch/securities/{cusip}/actions

GET /1.3/capwatch/actions/{number}

Account Preference Endpoints

GET /1.3/preferences

PUT /1.3/preferences

Lifecycle Endpoints

POST /1.3/portfolio

PUT /1.3/portfolio/{portfolio-id}

GET /1.3/portfolio

GET /1.3/portfolio/{portfolio-id}

DELETE /1.3/portfolio/{portfolio-id}

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

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

POST /1.3/portfolio/{portfolio-id}/costbasis/report and POST /1.3/portfolio/{portfolio-id}/giftval/report

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

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

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

DELETE /1.3/portfolio/{portfolio-id}/estateval/report/{report-id}

Input

input

Portfolio

portfolio

portfolio → lot

portfolio → lot → alt

portfolio → lot → dst

portfolio → lot → apr

portfolio → lot → alt → action

portfolio → lot → dst → action

portfolio → lot → apr → action

portfolio → security

portfolio → security → data

portfolio → currency → rate

portfolio → history

portfolio → reportruns → reportrun

portfolio → security → valuations → valuation

Output

output

Report

report

report → total

report → notes

report → lot

report → lot → subtotal

report → lot → inventory

report → lot → inventory → subtotal

report → lot → inventory → price

report → lot → inventory → price → last

report → lot → inventory → price → next

report → lot → inventory → price → mean

report → lot → inventory → generic-value

report → lot → inventory → generic-accrual

report → lot → inventory → dividends

report → lot → inventory → dividends → adjustments

report → lot → inventory → dividends → accruals

report → lot → inventory → dividends → values

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

report → lot → inventory → bond

report → lot → inventory → mbs

report → lot → inventory → mbs → payment

report → lot → inventory → uit

report → lot → inventory → notes

report → lot → inventory → notes → note

`GET /1.3/estateval/report`

`GET /1.3/capwatch/securities`

`GET /1.3/capwatch/securities/{cusip}/actions`

`GET /1.3/capwatch/actions/{number}`

`GET /1.3/preferences`

`PUT /1.3/preferences`

`POST /1.3/portfolio`

`PUT /1.3/portfolio/{portfolio-id}`

`GET /1.3/portfolio`

`GET /1.3/portfolio/{portfolio-id}`

`DELETE /1.3/portfolio/{portfolio-id}`

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

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

`POST /1.3/portfolio/{portfolio-id}/costbasis/report` and `POST /1.3/portfolio/{portfolio-id}/giftval/report`

`GET /1.3/portfolio/{portfolio-id}/estateval/report/{report-id}/status`

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

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

`DELETE /1.3/portfolio/{portfolio-id}/estateval/report/{report-id}`

`input`

`portfolio`

`portfolio` → `lot`

`portfolio` → `lot` → `alt`

`portfolio` → `lot` → `dst`

`portfolio` → `lot` → `apr`

`portfolio` → `lot` → `alt` → `action`

`portfolio` → `lot` → `dst` → `action`

`portfolio` → `lot` → `apr` → `action`

`portfolio` → `security`

`portfolio` → `security` → `data`

`portfolio` → `currency` → `rate`

`portfolio` → `history`

`portfolio` → `reportruns` → `reportrun`

`portfolio` → `security` → `valuations` → `valuation`

`output`

`report`

`report` → `total`

`report` → `notes`

`report` → `lot`

`report` → `lot` → `subtotal`

`report` → `lot` → `inventory`

`report` → `lot` → `inventory` → `subtotal`

`report` → `lot` → `inventory` → `price`

`report` → `lot` → `inventory` → `price` → `last`

`report` → `lot` → `inventory` → `price` → `next`

`report` → `lot` → `inventory` → `price` → `mean`

`report` → `lot` → `inventory` → `generic-value`

`report` → `lot` → `inventory` → `generic-accrual`

`report` → `lot` → `inventory` → `dividends`

`report` → `lot` → `inventory` → `dividends` → `adjustments`

`report` → `lot` → `inventory` → `dividends` → `accruals`

`report` → `lot` → `inventory` → `dividends` → `values`

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

`report` → `lot` → `inventory` → `bond`

`report` → `lot` → `inventory` → `mbs`

`report` → `lot` → `inventory` → `mbs` → `payment`

`report` → `lot` → `inventory` → `uit`

`report` → `lot` → `inventory` → `notes`

`report` → `lot` → `inventory` → `notes` → `note`

`disclaimers`

`disclaimers` → `header`

`disclaimers` → `bottom`

`disclaimers` → `footer`

`billing`

`billing` → `item`