VAULT API - VERSION 3.0 Developer’s Manual and Reference April 2023
Vault API - Version 3.0
Contents
1.
Motivation
3
2.
API Program
3
2.1 Overview
3
3.
Vault APIs
4
3.1 Multiple Calculations APIs
4
3.1.1 Run Multiple Calculations
4
3.1.2 Create and Update Vault calculation
8
3.1.3 Get Vault Calculation Status By ID
12
3.1.4 Get Vault Calculations Result By ID
15
3.1.5 Get All Calculations
17
3.1.6 Get Vault Calculations parameters by ID
20
3.1.7 Cancel Multiple Calculations
22
3.2 Lookup APIs
23
3.2.1 Vault Components Lookup
23
3.2.2 Vault Component Settings Lookup
25
3.2.3 Vault Configurations Lookup
27
3.2.4 Vault Configuration Settings Lookup
29
3.2.5 Account Lookup
31
3.2.6 Frequency Lookup
33
3.2.7 Dates Translation
35
4.
Troubleshooting
38
5.
Version Upgrade
39
6.
Appendix: Run Multiple Calculations Request Body Scenarios
39
FactSet Research Systems Inc. |
2
1. Motivation
In 1997, FactSet launched Portfolio Analysis 1.0, which set the foundation for Analytics. Soon after, Portfolio Analysis 2.0
integrated risk analytics from third-party vendors, and then expanded to include Fixed Income in 2004. FactSet now offers
a robust suite of multi-asset portfolio analytics products that leads the market in flexibility, analytics, and breadth. Today,
clients rely on FactSet for interactive analytics through various products, such as Portfolio Analysis (PA), SPAR, Alpha
Testing, Optimizers, and Portfolio Dashboard, as well as the distribution of analytics through Portfolio Batcher, Publisher
Flat Files, and Publisher documents.
2. API Program
2.1 Overview
Clients have been moving towards building a custom solution, driven by the need to increase productivity by consolidating
information into a single user experience. By exposing analytics, performance, and risk through APIs, it provides you with
a sophisticated channel to interact with FactSet’s leading multi-asset analytics. As the market continues to demand more
transparency and data, FactSet will provide flexible options to meet those demands. APIs complement the current analytics
suite offerings and facilitate partnerships by allowing you to build private experiences, integrate with third-party BI tools like
Tableau, third-party stat packages like RStudio, and increase control over internal consumption of analytics from FactSet.
The first stage of exposing APIs will focus on the analytics engines. Later, the program will expand to include other analytics
products, and APIs from other business units.
The program will provide the following:
FactSet Research Systems Inc. |
3
• Developer toolkit to build proof of concept
• Uniform feel across all FactSet’s Enterprise scale APIs
• Adherence to industry standards
• Versioned APIs
• Extensive documentation and tutorials on the developer portal
3. Vault APIs
Through the Vault API, request validated pre-calculated returns and attribution data archived in Portfolio Vault to
streamline your official performance and reporting workflows.
All APIs are hosted under https://api.factset.com. Authentication is handled using API Keys and authorization is handled
using FactSet’s in-house subscriptions product. You can find more information about using API Keys at
https://developer.factset.com/authentication.
HTTP request and response header names should be considered case insensitive as per HTTP Standard. Please do not
rely on case sensitive matching of headers in your code.
3.1 Multiple Calculations APIs
3.1.1 Run Multiple Calculations
POST /analytics/engines/vault/v3/calculations
Description
This endpoint runs multiple calculations on Vault data based on parameters specified in the POST body. It must be used
first, before checking status or cancelling endpoints. A successful response will contain the URL to check the status of the
request.
Request Headers
Header name
Description
Authorization
Standard HTTP header. Value needs to use ‘Basic <base64 encoded value>’ format.
Content-Type
Standard HTTP header. Value needs to specify application/JSON (i.e., caller needs to
specify that the body is in JSON format).
Request Body
Parameter
Data
Required Description
Format
name
type
data
Array
Yes
List of calculations to compute for
Each calculation represented by an object containing
each component.
calculation inputs. See below for schema and example
values.
FactSet Research Systems Inc.
|
4
meta
Object Yes
Allows users to specify the response
Valid contenttype values are ‘Json’ and ‘Binary’.
format and stachContentOrganization. Default is ‘Json’. Valid contentorganization values are
‘Row’, ‘Column, ‘SimplifiedRow’, and ‘None’. Default is
‘SimplifiedRow’.
Please refer to the STACH v2 documentation here for
more information on STACH v2 format types.
Below are the calculation parameters supported by data section:
Parameter name Data
Required
Description
Format
type
componentid
String
Yes
The Vault
Component ID can be fetched using the Vault Components Lookup
component
API.
identifier to
analyze.
account
Object Yes
User’s FactSet
Account Identifier must have .ACCT or .ACTM extension or
account path OR a
BENCH:prefix.
benchmark.
for creating an account. Vault API runs on accounts stored in Vault
repository so, model accounts created through Model Portfolio API
are not compatible with Vault API.
dates
Object No
Date range(s) and
Supported Date Formats and Frequency Lookup API.
frequency to run
against. Object
takes frequency,
startdate and
enddate.
configid
String
Yes
Vault Configuration
Vault Configuration identifier can be fetched using the Vault
identifier.
Configurations Lookup API.
componentdetail String No
Degree of
Valid values are ‘groups’ and ‘totals’.
granularity to
return in the Vault
component
Response Headers
Header name
Description
X-DataDirect-Request-Key
FactSet’s request key header.
X-FactSet-Api-Request-Key
Key to uniquely identify an Analytics API request. Only available after successful
authentication.
Location
Standard HTTP header. Contains URL to check status of the request.
X-FactSet-Api-RateLimit-Limit
Number of allowed requests for the time window.
FactSet Research Systems Inc.
|
5
X-FactSet-Api-RateLimit-Remaining
Number of requests left for the time window.
X-FactSet-Api-RateLimit-Reset
Number of seconds remaining till rate limit resets.
Returns
HTTP status code
Description
200
Expected response, if the calculation has one unit and is completed with an error.
201
Expected response if the calculation has one unit and is completed in a short span,
returns JSON in the format specified in the Calculation parameters.
202
Expected response, contains the URL in the Location header to check the status of the
request.
400
Invalid POST body.
401
Missing or invalid authentication.
403
User is forbidden access with current credentials.
404
One or more calculation settings were unavailable.
415
Missing/Invalid Content-Type header. Header needs to be set to application/JSON.
429
Rate limit reached. Cancel older requests using Cancel Calculation endpoint or wait for
older requests to finish / expire.
500
Server error. Log the X-DataDirect-Request-Key header to assist in troubleshooting.
503
Request timed out, Retry the request in sometime.
Remarks
• Maximum 50 POST requests allowed in a 5 second window for each API. The same can be verified using the
various Rate-Limit headers available in the API response.
X-FactSet-Api-RateLimit-Limit
- Number of allowed requests for the time window.
X-FactSet-Api-RateLimit-Remaining
- Number of requests left for the time window.
X-FactSet-Api-RateLimit-Reset
- Number of seconds remaining till rate limit resets.
• Maximum 1000 units allowed per request and across all simultaneous requests.
• Any settings in POST body will act as a one-time override over the settings saved in the Vault template.
• Start and end date must be within the configuration’s min and max date range. Refer the Vault Configuration
Settings Lookup API.
• Multi-horizon frequencies are not supported through this endpoint.
FactSet Research Systems Inc. |
6
Caching Remarks
• All results will be cached for 12 hours by default. This means that by default (without sending any cache-control
headers), after the first request successfully completes, all subsequent requests with unchanged request
parameters will return the same results for 12 hours.
• Setting the max-stale=<staleness limit in seconds> allows you to fetch pre-calculated results with any subsequent
POST requests, as long as they were last calculated within the staleness limit.
o Once set, the API will check to see if the stored results are within the staleness limit.
▪ If they are within the limit, then the request will return the cached results, allowing for a quick
response and eliminating unnecessary points accrual.
▪ If the results are not within the limit, a brand-new calculation request will be triggered to get the
latest results.
• To immediately request the latest results, override the cache by setting “max-stale=0” in the Cache-control header
parameter.
• Changes made to the underlying Vault document via the workstation will not trigger a results re-calculation. The
cache-control parameter should be set to “max-stale=0” to immediately request the latest results
• The max cache-control value is “max-stale=43200” (12 hours)
• The cached result period is applied to each individual calculation unit after it completes. It is not applied to the entire
calculation.
Examples
Request:
Headers:
content-type: application/json
Authorization: Basic RkRTX0RFTU9fVVMt******************************
Accept-Encoding: gzip
content-length: 201
content-type: application/json
Body:
{
"data": {
"calc1": {
"componentid": "B0FF076DFF8640B1616462B82BE1F21FBF23E0E9DE62247F4A947B17F81C9A79",
"account": {
"id": "CLIENT:/BISAM/REPOSITORY/QA/SMALL_PORT.ACCT"
},
"dates": {
"startdate": "20180101",
FactSet Research Systems Inc. |
7
"enddate": "20180329",
"frequency": "Monthly"
},
"configid": "12ed7b1a-8ac2-4871-a7bf-2d5da5aaa116"
},
"calc2": {
"componentid": "B75D10A84BBD26C9D0C91E78BC5723A4DE70FFE4192070820B9788E382D17E42",
"account": {
"id": "CLIENT:/BISAM/REPOSITORY/QA/SMALL_PORT.ACCT"
},
"configid": "c1671411-7807-4505-9296-989fe2ffc450"
}
},
"meta": {
"contentorganization": "SimplifiedRow",
"contenttype": "Json"
}
}
Response:
HTTP 202 Accepted
Headers:
a505b0da42/status
x-datadirect-request-key: 60d19db906e6a3cc
x-factset-api-request-key: 60d19db9139ac00b
3.1.2 Create and Update Vault calculation
PUT /analytics/engines/vault/v3/calculations/{id}
Description
This endpoint can be used to either:
• Create a new Vault calculation(s) with a custom id specified in the id path parameter
• Update calculation parameters and run a pre-existing Vault calculation
Like the POST endpoint, the PUT endpoint must be used first, before checking status or cancelling endpoints. A
successful response will contain the URL to check the status of the request. If the X-FactSet-Api-Long-Running-
Deadline header is passed, then this endpoint will return calculation results in the response if the calculation completes
within the specified amount of time.
FactSet Research Systems Inc. |
8
Request Headers
Header name
Description
Authorization
Standard HTTP header. Value needs to use ‘Basic <base64 encoded value>’ format.
Content-Type
Standard HTTP header. Value needs to specify application/JSON (i.e., caller needs to
specify that the body is in JSON format).
X-FactSet-Api-Long-Running-
Long running deadline in seconds when only one unit is passed in the POST body. The
Deadline
endpoint will return calculation results in the response if it completes within the specified
amount of time (rather than return the status polling URL) Max value is 20 seconds.
Cache-Control
Standard HTTP header that holds caching instructions. max-stale is the only supported
directive. It indicates that the client will accept a stale response, the value (in seconds)
denotes the upper time limit for the stale response. Note that all results are cached for
12 hours, to override the default cache and trigger a new request, set max-stale=0.Max
value is 43200 seconds (12 hours). For more information on caching, see the Caching
Remarks section.
Request Body
Like the POST endpoint, the request body is made up of the following 2 objects, “data” which holds calculation
parameters, and “meta” which specifies the response’s content type and formatting.
Object
Required
Description
Format
name
data
Yes
Parent object for the request body
List of calculation parameters
meta
No
Allows users to specify the response
Valid contenttype values are ‘Json’ and ‘Binary’. Default is
format and StachContentOrganization.
‘Json’. Valid contentorganization values are ‘Row’, ‘Column,
‘SimplifiedRow’, and ‘None’. Default is ‘SimplifiedRow’.
Please refer to the STACH v2 documentation here for more
information on STACH v2 format types.
The calculation parameters within the “data” object are outlined below:
Parameter name Data
Required Description
Format
type
componentid
String
Yes
The Vault
Component ID can be fetched using the Vault Components Lookup
component
API.
identifier to
analyze.
FactSet Research Systems Inc.
|
9
account
Object Yes
User’s FactSet
Account Identifier must have .ACCT or .ACTM extension or
account path OR a
BENCH:prefix.
benchmark.
for creating an account. Vault API runs on accounts stored in Vault
repository so, model accounts created through Model Portfolio API
are not compatible with Vault API.
dates
Object No
Date range(s) and
Supported Date Formats and Frequency Lookup API.
frequency to run
against. Object
takes frequency,
startdate and
enddate.
configid
String
Yes
Vault Configuration
Vault Configuration identifier can be fetched using the Vault
identifier.
Configurations Lookup API.
componentdetail String No
Degree of
Valid values are ‘groups’ and ‘totals’.
granularity to
return in the Vault
component
Response Headers
Header name
Description
X-DataDirect-Request-Key
FactSet’s request key header.
X-FactSet-Api-Request-Key
Key to uniquely identify an Analytics API request. Only available after successful
authentication.
Location
Standard HTTP header. Contains URL to check status of the request.
X-FactSet-Api-RateLimit-Limit
Number of allowed requests for the time window.
X-FactSet-Api-RateLimit-Remaining
Number of requests left for the time window.
X-FactSet-Api-RateLimit-Reset
Number of seconds remaining till rate limit resets.
Returns
HTTP status code
Description
200
Expected response if the calculation has one unit and is completed with an error
201
Expected response if the calculation has one unit and is completed in a short span,
returns JSON in the format specified in the Calculation parameters.
202
Expected response, contains the poll URL in the Location header.
FactSet Research Systems Inc.
|
10
400
Invalid calculation parameters.
401
Missing or invalid authentication.
403
User is forbidden access with current credentials.
404
One or more calculation settings were unavailable.
409
Duplicate calculation exists with same parameters.
415
Missing/Invalid Content-Type header. Header needs to be set to application/json.
429
Rate limit reached. Cancel older requests using Cancel Calculation endpoint or wait for
older requests to finish / expire.
500
Server error. Log the X-DataDirect-Request-Key header to assist in troubleshooting.
503
Request timed out. Retry the request in some time.
Examples
Request:
Request Headers:
content-type: application/json
Authorization: Basic RkRTX0RFTU9fVVMt******************************
Accept-Encoding: gzip
Body:
{
"data": {
"calc1": {
"componentid": "B0FF076DFF8640B1616462B82BE1F21FBF23E0E9DE62247F4A947B17F81C9A79",
"account": {
"id": "CLIENT:/BISAM/REPOSITORY/QA/SMALL_PORT.ACCT"
},
"dates": {
"startdate": "20180101",
"enddate": "20180429",
"frequency": "Monthly"
},
"configid": "12ed7b1a-8ac2-4871-a7bf-2d5da5aaa116"
},
"calc2": {
"componentid": "B75D10A84BBD26C9D0C91E78BC5723A4DE70FFE4192070820B9788E382D17E42",
"account": {
"id": "CLIENT:/BISAM/REPOSITORY/QA/SMALL_PORT.ACCT"
FactSet Research Systems Inc. |
11
},
"configid": "c1671411-7807-4505-9296-989fe2ffc450"
}
},
"meta": {
"contentorganization": "SimplifiedRow",
"contenttype": "Json"
}
}
Response:
HTTP 202 Accepted
{
"data": {
"calculationid": "cu",
"status": "Queued",
"units": {
"calc1": {
"status": "Executing"
},
"calc2": {
"status": "Queued"
}
}
}
}
Response Headers:
x-datadirect-request-key: 60d1a45639425f1d
x-factset-api-request-key: 60d1a456362cd0ab
3.1.3 Get Vault Calculation Status By ID
GET /analytics/engines/vault/v3/calculations//{id}/status
Description
This is the endpoint to check on the progress of a previous request that was submitted using Run Multiple Calculations
endpoint. The response body contains status information of the entire request and each individual calculation. If an
individual calculation has finished computing, the result parameter in the response body will contain the result URL.
Otherwise, the calculation is still running, and the X-FactSet-Api-PickUp-Progress header will contain a progress
percentage.
FactSet Research Systems Inc. |
12
Request Headers
Header name
Description
Authorization
Standard HTTP header. Value needs to use ‘Basic <base64 encoded value>’ format.
Path Parameters
Name
Required
Description
id
Yes
From url, provided from the location header in the Create and Run Vault
calculation endpoint
Response Headers
Header name
Description
Content-Encoding
Standard HTTP header. Header value based on Accept-Encoding Request header.
Content-Type
Standard HTTP header.
Transfer-Encoding
Standard HTTP header. Header value will be set to Chunked if Accept-Encoding
header is specified.
X-DataDirect-Request-Key
FactSet’s request key header.
X-FactSet-Api-Request-Key
Key to uniquely identify an Analytics API request. Only available after successful
authentication.
Cache-Control
Standard HTTP header. Header will specify max-age in seconds. Polling can be
adjusted based on the max-age value.
X-FactSet-Api-RateLimit-Limit
Number of allowed requests for the time window.
X-FactSet-Api-RateLimit-
Number of requests left for the time window.
Remaining
X-FactSet-Api-RateLimit-Reset
Number of seconds remaining till rate limit resets.
Returns
HTTP status code
Description
200
Expected response once the calculation is completed. The response body contains status
information of the entire request and each individual calculation.
202
Expected response returned if the calculation is not yet completed. Contains X-FactSet-Api-
PickUp-Progress header with a percentage of progress completed
FactSet Research Systems Inc.
|
13
400
Invalid identifier parameter provided.
401
Missing or invalid authentication.
403
User is forbidden access with current credentials.
404
Calculation was already returned, provided id was not a requested calculation, or the
calculation was cancelled.
500
Server error. Log the X-DataDirect-Request-Key header to assist in troubleshooting.
503
Request timed out. Retry the request in sometime.
Examples
Request:
GET
3/status
Request Headers:
Authorization: Basic RkRTX0RFTU9fVVMt******************************
Response:
HTTP 200 Success
Response Headers:
x-datadirect-request-key: 60d1df1c32679ac9
x-factset-api-request-key: 60d1df1cf955d7f1
Body:
{
"data": {
"calculationid": "f204d270049c49f1b0f307c602a40583",
"status": "Completed",
"units": {
"calc1": {
"status": "Success",
"result":
83/units/calc1/result",
"progress": "100"
},
FactSet Research Systems Inc. |
14
"calc2": {
"status": "Success",
"result":
83/units/calc2/result",
"progress": "100"
}
}
}
}
3.1.4 Get Vault Calculations Result By ID
GET /analytics/engines/vault/v3/calculations/{id}/units/{unitId}/result
Description
This is the endpoint to get the result of a previously requested calculation. If the calculation has finished computing, the
body of the response will contain the requested document in JSON.
Request Headers
Header name
Description
Accept
(Optional) Standard HTTP header. Value can be gzip, compress, deflate, br, identity
and/or
Path Parameters
Name
Required
Description
id
Yes
Calculation id. From url, provided from the location header in the Create and
Run Vault calculation endpoint
unitId
Yes
Unit id. from url, provided from the location header in the Get Vault calculation
status by id endpoint
Response Headers
Header name
Description
Content-Encoding
Standard HTTP header. Header value based on Accept-Encoding Request header.
Content-Type
Standard HTTP header.
FactSet Research Systems Inc.
|
15
Transfer-Encoding
Standard HTTP header. Header value will be set to Chunked if Accept-Encoding
header is specified.
X-DataDirect-Request-Key
FactSet’s request key header.
X-FactSet-Api-Request-Key
Key to uniquely identify an Analytics API request. Only available after successful
authentication.
X-FactSet-Api-RateLimit-Limit
Number of allowed requests for the time window.
X-FactSet-Api-RateLimit-Remaining
Number of requests left for the time window.
X-FactSet-Api-RateLimit-Reset
Number of seconds remaining till rate limit resets.
Returns
HTTP status code
Description
200
Expected response once calculation is completed, returns JSON in the format specified
in the Calculation parameters.
400
Invalid identifier provided.
401
Missing or invalid authentication.
403
User is forbidden access with current credentials.
404
Calculation was already returned, provided id was not a requested calculation, or the
calculation was cancelled
500
Server error. Log the X-DataDirect-Request-Key header to assist in troubleshooting.
503
Request timed out. Retry the request in sometime.
Examples
Request:
GET
3/units/calc1/result
Request Headers:
Authorization: Basic RkRTX0RFTU9fVVMt******************************
Response:
HTTP 200 Success
Response Headers:
FactSet Research Systems Inc. |
16
x-datadirect-request-key: 60d1e110225c7638
x-factset-api-request-key: 60d1e11074a1ed9d
Body:
See a sample SimplifiedRow formatted response here
3.1.5 Get All Calculations
GET /analytics/engines/vault/v3/calculations
Description
This endpoint returns all calculation requests. The data is sorted in descending order by request time and by default one
page will fetch 20 calculations.
Request Headers
Header name
Description
Accept
(Optional) Standard HTTP header. Value can be gzip, compress, deflate, br, identity and/or *
Query Parameters
Name
Required
Type
Description
pageNumber
Yes
Integer
Page number
Response Headers
Header name
Description
Content-Encoding
Standard HTTP header. Header value based on Accept-Encoding Request header.
Content-Type
Standard HTTP header.
Transfer-Encoding
Standard HTTP header. Header value will be set to Chunked if Accept-Encoding header
is specified.
X-DataDirect-Request-Key
FactSet’s request key header.
X-FactSet-Api-Request-Key
Key to uniquely identify an Analytics API request. Only available after successful
authentication.
X-FactSet-Api-RateLimit-Limit
Number of allowed requests for the time window.
X-FactSet-Api-RateLimit-Remaining Number of requests left for the time window.
X-FactSet-Api-RateLimit-Reset
Number of seconds remaining till rate limit resets.
FactSet Research Systems Inc. |
17
Response Body Parameters
Header name
Description
data
Parent object of the response body.
meta
Contains pagination details.
Data object includes following parameters -
Header name
Description
status
Status of the calculation id . E.g. completed, failed, queued, executing etc.
units
Number of units for a calculation request.
requestTime
Time at which the calculation request was made.
lastPollTime
Time at which the calculation was last polled.
Meta object includes following parameters -
Header name
Description
pageNumber
Number of the page requested.
pageSize
Number of requests in a page.
totalPages
Total number of pages at a given time
totalCalculation
Total number of calculations at a given time
nextPage
Following page number
lastPage
Previous page number
Returns
HTTP status code
Description
200
List of calculation requests.
400
Invalid page number.
401
Missing or invalid authentication.
403
User is forbidden with current credentials.
404
No calculation found.
406
Unsupported Accept header. Header needs to be set to application/json.
FactSet Research Systems Inc. |
18
429
Rate limit reached. Wait till the time specified in Retry-After header value to make further
requests.
500
Server error. Log the X-DataDirect-Request-Key header to assist in troubleshooting.
503
Request timed out. Retry the request in sometime.
Examples
Request:
Response:
HTTP 200 OK
Response Headers:
x-datadirect-request-key: 62d7ef371709b08a
x-factset-api-request-key: 62d7ef3755f31322
Body:
{
"data": {
"389a96cbd59f427191a921a8f01fa455": {
"status": "Completed",
"units": 2,
"requestTime": "2022-07-21T15:26:40.349594Z",
"lastPollTime": "2022-07-21T15:26:40.539849Z"
}
},
"meta": {
"pagination": {
"pageNumber": 1,
"pageSize": 20,
"totalPages": 1,
"totalCalculations": 1,
"nextPage": null,
"previousPage": null
}
}
}
FactSet Research Systems Inc. |
19
3.1.6 Get Vault Calculations parameters by ID
GET /analytics/engines/vault/v3/calculations/{id}
Description
This endpoint that returns the calculation parameters passed for a calculation.
Path Parameters
Name
Required
Description
id
Yes
Calculation id. From url, provided from the location header in the Create and
Run Vault calculation endpoint
Response Headers
Header name
Description
Content-Encoding
Standard HTTP header. Header value based on Accept-Encoding Request header.
Content-Type
Standard HTTP header.
Transfer-Encoding
Standard HTTP header. Header value will be set to Chunked if Accept-Encoding
header is specified.
X-DataDirect-Request-Key
FactSet’s request key header.
X-FactSet-Api-Request-Key
Key to uniquely identify an Analytics API request. Only available after successful
authentication.
X-FactSet-Api-RateLimit-Limit
Number of allowed requests for the time window.
X-FactSet-Api-RateLimit-Remaining
Number of requests left for the time window.
X-FactSet-Api-RateLimit-Reset
Number of seconds remaining till rate limit resets.
Returns
HTTP status code
Description
200
Expected response, returns the Vault calculation parameters.
400
Invalid identifier provided.
401
Missing or invalid authentication.
403
User is forbidden access with current credentials.
FactSet Research Systems Inc.
|
20
404
Calculation id not found.
500
Server error. Log the X-DataDirect-Request-Key header to assist in troubleshooting.
503
Request timed out. Retry the request in sometime.
Examples
Request:
0583
Response:
HTTP 200 OK
Response Headers:
x-datadirect-request-key: 60d1e3c90332a52d
x-factset-api-request-key: 60d1e3c9daa5b216
Body:
{
"data": {
"calc1": {
"componentid": "b0ff076dff8640b1616462b82be1f21fbf23e0e9de62247f4a947b17f81c9a79",
"account": {
"id": "client:/bisam/repository/qa/small_port.acct"
},
"dates": {
"startdate": "20180101",
"enddate": "20180329",
"frequency": "monthly"
},
"configid": "12ed7b1a-8ac2-4871-a7bf-2d5da5aaa116",
"componentdetail": null
},
"calc2": {
"componentid": "b75d10a84bbd26c9d0c91e78bc5723a4de70ffe4192070820b9788e382d17e42",
"account": {
"id": "client:/bisam/repository/qa/global.acct"
},
FactSet Research Systems Inc. |
21
"dates": null,
"configid": "c1671411-7807-4505-9296-989fe2ffc450",
"componentdetail": null
}
},
"meta": {
"contentorganization": "simplifiedrow",
"contenttype": "json"
}
}
3.1.7 Cancel Multiple Calculations
DELETE /analytics/engines/vault/v3/calculations/{id}
Description
This endpoint is used to cancel a previously submitted request. Instead of doing a HTTP GET on the status URL, cancel
the request by doing a HTTP DELETE.
Path Parameters
Name
Required
Description
id
Yes
Calculation id. From url, provided from the location header in the Create and
Run Vault calculation endpoint
Request Headers
Header name
Description
Authorization
Standard HTTP header. Value needs to use ‘Basic <base64 encoded value>’ format.
Response Headers
Header name
Description
X-DataDirect-Request-Key
FactSet’s request key header.
X-FactSet-Api-Request-Key
Key to uniquely identify an Analytics API request. Only available after successful
authentication.
Returns
HTTP status code
Description
204
Expected response, request was canceled successfully.
FactSet Research Systems Inc.
|
22
400
Invalid identifier parameter provided.
401
Missing or invalid authentication.
403
User is forbidden access with current credentials.
404
There was no request for the identifier provided, or the request was already canceled for
the provided identifier.
500
Server error. Log the X-DataDirect-Request-Key header to assist in troubleshooting.
503
Request timed out. Retry the request in sometime.
Examples
Request:
02a40583
Headers:
Authorization: Basic RkRTX0RFTU9fVVMt******************************
Response:
HTTP 204 No Content
Headers:
x-datadirect-request-key: 60d1e94c1925398b
x-factset-api-request-key: 60d1e94cfe20063e
3.2 Lookup APIs
3.2.1 Vault Components Lookup
GET /analytics/engines/vault/v3/components?document={documentname}
Description
This endpoint returns a list of components within a Portfolio Insight document. Run Multiple Calculations API expects
component identifiers returned by this endpoint.
Component identifiers are of variable-length and are expected to change. Users should always use this API before calling
Run Multiple Calculations API.
Request Headers
Header name
Description
Authorization
Standard HTTP header. Value needs to use ‘Basic <base64 encoded value>’ format.
FactSet Research Systems Inc. |
23
Accept
(Optional) Standard HTTP header. Value needs to be application/json.
Request Query Parameters
Parameter
Data
Description
Format
name
type
document String Portfolio Insight document
FactSet-root:/document-path. Possible values for FactSet-root are client,
name.
personal, super_client, or pa_documents. Document name must have .PAR
extension
Response Headers
Header name
Description
X-DataDirect-Request-Key
FactSet’s request key header.
X-FactSet-Api-Request-Key
Key to uniquely identify an Analytics API request. Only available after successful
authentication.
Returns
HTTP status code
Description
200
Expected response.
400
Invalid query parameter/value provided.
401
Missing or invalid authentication.
403
User is forbidden access with current credentials.
404
Document not found.
406
Unsupported Accept header. Header needs to be set to application/json.
429
Rate limit reached. Wait till the time specified in Retry-After header value to make further requests.
500
Server error. Log the X-DataDirect-Request-Key header to assist in troubleshooting.
503
Request timed out, Retry the request in sometime.
Examples
Request:
AULT_QA_PI_DEFAULT_LOCKED
Headers:
Authorization: Basic RkRTX0RFTU9fVVMt******************************
FactSet Research Systems Inc.
|
24
Response:
HTTP 200 Success
Headers:
x-datadirect-request-key: 60d2c4661d490582
x-factset-api-request-key: 60d2c466a6e71b04
Body:
{
"B75D10A84BBD26C9D0C91E78BC5723A4DE70FFE4192070820B9788E382D17E42": {
"name": "Performance Attribution",
"category": "Performance / Fixed Income Attribution"
},
"B9F0CA1A272C4F1E0998BFADB53B7D7C046D4EA28D872B3D2533919A263D720D": {
"name": "Attribution Over Time Chart",
"category": "Performance / Fixed Income Attribution"
}
}
3.2.2 Vault Component Settings Lookup
GET /analytics/engines/vault/v3/components/{id}
Description
This endpoint returns settings for a given vault component.
Request Headers
Header name
Description
Authorization
Standard HTTP header. Value needs to use ‘Basic <base64 encoded value>’ format.
Accept
(Optional) Standard HTTP header. Value needs to be application/json.
Response Headers
Header name
Description
X-DataDirect-Request-Key
FactSet’s request key header.
X-FactSet-Api-Request-Key
Key to uniquely identify an Analytics API request. Only available after successful
authentication.
FactSet Research Systems Inc. |
25
Returns
HTTP status code
Description
200
Expected response.
400
Invalid component identifier.
401
Missing or invalid authentication.
403
User is forbidden access with current credentials.
404
Component not found.
406
Unsupported Accept header. Header needs to be set to application/json.
429
Rate limit reached. Wait till the time specified in Retry-After header value to make further
requests.
500
Server error. Log the X-DataDirect-Request-Key header to assist in troubleshooting.
503
Request timed out, Retry the request in sometime.
Examples
Request:
GET
E70FFE4192070820B9788E382D17E42
Headers:
Authorization: Basic RkRTX0RFTU9fVVMt******************************
Response:
HTTP 200 Success
Headers:
x-datadirect-request-key: 60d2c5e035576ee2
x-factset-api-request-key: 60d2c5e053b6b592
Body:
{
"id": "B75D10A84BBD26C9D0C91E78BC5723A4DE70FFE4192070820B9788E382D17E42",
"account": {
"id": "CLIENT:/BISAM/REPOSITORY/QA/GLOBAL.ACCT"
},
"benchmark": {
"id": "MSCI_EM:AC_WORLD_FREE"
FactSet Research Systems Inc. |
26
},
"currencyisocode": "EUR",
"dates": {
"startdate": "20171229",
"enddate": "20180214",
"frequency": "Single"
},
"snapshot": false,
"name": "Performance Attribution",
"category": "Performance / Fixed Income Attribution"
}
3.2.3 Vault Configurations Lookup
GET /analytics/engines/vault/v3/configurations?account={accountname}
Description
This endpoint returns a list of Vault configurations for an account. Run Multiple Calculations API expects configuration
identifiers returned by this endpoint.
Users should always use this API before calling Run Multiple Calculations API.
Request Headers
Header name
Description
Authorization
Standard HTTP header. Value needs to use ‘Basic <base64 encoded value>’ format.
Accept
(Optional) Standard HTTP header. Value needs to be application/json.
Request Query Parameters
Parameter name Data type Description
Format
account
String
User’s FactSet account path.
Account must have .ACCT or .ACTM extension.
Response Headers
Header name
Description
X-DataDirect-Request-Key
FactSet’s request key header.
X-FactSet-Api-Request-Key
Key to uniquely identify an Analytics API request. Only available after successful authentication.
FactSet Research Systems Inc. |
27
Returns
HTTP status code
Description
200
Expected response.
400
Invalid query parameter/value provided.
401
Missing or invalid authentication.
403
User is forbidden access with current credentials.
404
Account not found.
406
Unsupported Accept header. Header needs to be set to application/json.
429
Rate limit reached. Wait till the time specified in Retry-After header value to make further
requests.
500
Server error. Log the X-DataDirect-Request-Key header to assist in troubleshooting.
503
Request timed out, Retry the request in sometime.
Examples
Request:
REPOSITORY%2FQA%2FSMALL_PORT.ACCT
Headers:
Authorization: Basic RkRTX0RFTU9fVVMt******************************
Response:
HTTP 200 Success
Headers:
x-datadirect-request-key: 60d2c7401e28c2ec
x-factset-api-request-key: 60d2c74095195100
Body:
{
"12ed7b1a-8ac2-4871-a7bf-2d5da5aaa116": {
"name": "Asset Type Brinson 3F without Currency"
},
"5c551841-5e6c-496e-8c82-c3487ca0c65f": {
"name": "Market Cap Brinson 3F without Currency"
}
}
FactSet Research Systems Inc. |
28
3.2.4 Vault Configuration Settings Lookup
GET /analytics/engines/vault/v3/configurations/{id}
Description
This endpoint returns settings for a given vault configuration.
Request Headers
Header name
Description
Authorization
Standard HTTP header. Value needs to use ‘Basic <base64 encoded value>’ format.
Accept
(Optional) Standard HTTP header. Value needs to be application/json.
Response Headers
Header name
Description
X-DataDirect-Request-Key
FactSet’s request key header.
X-FactSet-Api-Request-Key
Key to uniquely identify an Analytics API request. Only available after successful
authentication.
Returns
HTTP status code
Description
200
Expected response.
400
Invalid component identifier.
401
Missing or invalid authentication.
403
User is forbidden access with current credentials.
404
Component not found.
406
Unsupported Accept header. Header needs to be set to application/json.
429
Rate limit reached. Wait till the time specified in Retry-After header value to make further
requests
500
Server error. Log the X-DataDirect-Request-Key header to assist in troubleshooting.
503
Request timed out, Retry the request in sometime.
Examples
Request:
0AA104AF602F
FactSet Research Systems Inc. |
29
Headers:
Authorization: Basic RkRTX0RFTU9fVVMt******************************
Response:
HTTP 200 Success
Headers:
x-datadirect-request-key: 60d2c7b037bf7ba5
x-factset-api-request-key: 60d2c7b0abe6b172
Body:
{
"name": "Sector 2F Brinson Without Currency",
"accounts": {
"client:/mac/demo/demo_ps_eq_em_country_alpha.acct": {
"benchmarkCode": "MSCI_EM:EMF",
"benchmarkName": "MSCI Emerging Markets",
"maxEndDate": "20180611",
"minStartDate": "20171231",
"lockingDate": "20180405",
"name": "Demo Emerging Market Country Alpha Portfolio"
},
"client:/mac/demo/demo_eq_eafe_port.acct": {
"benchmarkCode": "MSCI:EAFE",
"benchmarkName": "MSCI EAFE",
"maxEndDate": "20180813",
"minStartDate": "20180329",
"lockingDate": "20180731",
"name": "Demo EAFE Alpha Portfolio"
},
"client:/analytics/midwest_im/4303.acct": {
"benchmarkCode": "RUSSELL:VALUE",
"benchmarkName": "Russell 1000 Value",
"maxEndDate": "20180629",
"minStartDate": "20170629",
"lockingDate": "20180531",
"name": "4303"
}
}
}
FactSet Research Systems Inc. |
30
3.2.5 Account Lookup
GET /analytics/lookups/v3/accounts/{path}
Description
This endpoint returns a list of account and composite files as well as the directories these files can be found under. Account
names from this endpoint can be used in Run Multiple Calculations API. If no path is provided, a list of root level directories
is returned, which can then be passed again to this endpoint to retrieve accounts and sub-directories.
Request Headers
Header name
Description
Authorization
Standard HTTP header. Value needs to use ‘Basic <base64 encoded value>’ format.
Accept
(Optional) Standard HTTP header. Value needs to be application/json.
Response Headers
Header name
Description
X-DataDirect-Request-Key
FactSet’s request key header.
X-FactSet-Api-Request-Key
Key to uniquely identify an Analytics API request. Only available after successful authentication.
Age
Standard HTTP header. Age of cache in seconds.
Returns
HTTP status code
Description
200
Expected response.
400
Invalid query parameter or value provided.
401
Missing or invalid authentication.
403
User is forbidden access with current credentials.
404
Path not found.
406
Unsupported Accept header. Header needs to be set to application/json.
429
Rate limit reached. Wait till the time specified in Retry-After header value to make further requests.
500
Server error. Log the X-DataDirect-Request-Key header to assist in troubleshooting.
503
Request timed out. Retry the request in sometime.
FactSet Research Systems Inc. |
31
Examples
Request:
Headers:
Authorization: Basic RkRTX0RFTU9fVVMt******************************
Response:
HTTP 200 Success
Headers:
x-datadirect-request-key: 564d5a1d49ffluvj
x-factset-api-request-key: 60d2cbd4ffdfa73d
Body:
{
"directories": [
"Client:",
"FactSet:"
]
}
Request:
Headers:
Authorization: Basic RkRTX0RFTU9fVVMt******************************
Response:
HTTP 200 Success
Headers:
x-datadirect-request-key: 564d5a1d49ffluvj
x-factset-api-request-key: 60d2cbd4ffdfa73d
Body:
{
"data": {
"accounts": [
"TEST.ACCT",
"COMPOSITE.ACCT",
],
FactSet Research Systems Inc. |
32
"directories": [
"test1",
"test2"
]
}
}
3.2.6 Frequency Lookup
GET /analytics/engines/vault/v3/frequencies
Description
This endpoint returns a list of supported frequencies.
Request Headers
Header name
Description
Authorization
Standard HTTP header. Value needs to use ‘Basic <base64 encoded value>’ format.
Accept
(Optional) Standard HTTP header. Value needs to be application/json.
Response Headers
Header name
Description
X-DataDirect-Request-Key
FactSet’s request key header.
X-FactSet-Api-Request-Key
Key to uniquely identify an Analytics API request. Only available after successful
authentication.
Returns
HTTP status code
Description
200
Expected response.
401
Missing or invalid authentication.
403
User is forbidden access with current credentials.
406
Unsupported Accept header. Header needs to be set to application/json.
429
Rate limit reached. Wait till the time specified in Retry-After header value to make further
requests.
500
Server error. Log the X-DataDirect-Request-Key header to assist in troubleshooting.
503
Request timed out. Retry the request in sometime.
FactSet Research Systems Inc. |
33
Examples
Request:
Headers:
Authorization: Basic RkRTX0RFTU9fVVMt******************************
Response:
HTTP 200 Success
Headers:
x-datadirect-request-key: fns911nz73wv6hb4
x-factset-api-request-key: m2h184putr0jctn4
Body:
{
"data": {
"Single": {
"name": "Single"
},
"FiscalYearly": {
"name": "Fiscal Yearly"
},
"Annually": {
"name": "Annually"
},
"SemiAnnually": {
"name": "Semi Annually"
},
"Quarterly": {
"name": "Quarterly"
},
"Monthly": {
"name": "Monthly"
},
"Weekly": {
"name": "Weekly"
},
"Daily": {
"name": "Daily"
FactSet Research Systems Inc. |
34
}
}
}
3.2.7 Dates Translation
GET
/analytics/engines/vault/v3/dates?startdate={startdate}&enddate={enddate}&componentid={componentid}&account={acc
ount}
Description
This endpoint converts part or the whole relative date to its absolute format, i.e., YYYYMMDD format. If the date specified
is not a trading day, the API picks the closest trading day prior to the specified date.
Request Headers
Header name
Description
Authorization
Standard HTTP header. Value needs to use ‘Basic <base64 encoded value>’ format.
Accept
(Optional) Standard HTTP header. Value needs to be application/json.
Request Query Parameters
Parameter
Data
Required Description
Format
name
type
Supported Date Formats and Frequency Lookup API.
startdate
String
No
Relative start date.
enddate
String
Yes
Relative end date.
Supported Date Formats and Frequency Lookup API.
componentid String
Yes
The Vault component identifier to
Component identifier can be fetched using the Vault
analyze.
Component Lookup API.
account
String
Yes
User’s FactSet account path.
Account must have .ACCT or .ACTM extension.
Response Headers
Header name
Description
X-DataDirect-Request-Key
FactSet’s request key header.
X-FactSet-Api-Request-Key
Key to uniquely identify an Analytics API request. Only available after successful
authentication.
FactSet Research Systems Inc.
|
35
Returns
HTTP status code
Description
200
Expected response.
400
Invalid query parameter/value provided.
401
Missing or invalid authentication.
403
User is forbidden access with current credentials.
404
Document or account not found.
406
Unsupported Accept header. Header needs to be set to application/json.
429
Rate limit reached. Wait till the time specified in Retry-After header value to make further
requests.
500
Server error. Log the X-DataDirect-Request-Key header to assist in troubleshooting.
503
Request timed out. Retry the request in sometime.
Examples
Request:
3AY&enddate=1AY&componentid=7CF4BCEB46020A5D3C78344108905FF73A4937F5E37CFF6BD97EC29545341935&ac
count=test.acct
Headers:
Authorization: Basic RkRTX0RFTU9fVVMt******************************
Response:
HTTP 200 Success
Headers:
x-datadirect-request-key: e43vazt21fr6ln83
x-factset-api-request-key: 0j2zg6lsxcfqx4vy
Body:
{
"enddate": "20160303"
}
Request:
FactSet Research Systems Inc. |
36
1AY&componentid=7CF4BCEB46020A5D3C78344108905FF73A4937F5E37CFF6BD97EC29545341935&account=test.a
cct
Headers:
Authorization: Basic RkRTX0RFTU9fVVMt******************************
Response:
HTTP 200 Success
Headers:
x-datadirect-request-key: 4cqpdv2nn14ln8gv
x-factset-api-request-key: 6pwnk7iavmt2j434
Body:
{
"startdate": "20160203",
"enddate": "20160303"
}
Supported Date Formats
Absolute Date Formats
Format
Description
Examples
MM/DD/YYYY
A day.
7/11/2016, 1/1/2015, 3/6/2014.
MM/YYYY
A month end.
6/2016, 4/2015, 11/2014, 5/2013.
YYYY/MMF
A fiscal quarter end.
2016/3F, 2015/2F.
YYYY/MMC
A calendar quarter end.
2016/1C, 2015/3C.
YYYY
A fiscal year end.
2016, 2015.
Relative Date Formats
Format
Examples
D
0D is the most recently completed trading day, -1D is one trading day prior.
AW
0AW is the most recently completed trading day, -1AW is the one actual week (7 days) prior to the
most recently completed trading day.
FactSet Research Systems Inc. |
37
W
0W is the last day of the most recently completed trading week (usually Friday), -1W is the last
trading day of the prior week.
AM
0AM is the most recently completed trading day, -1AM is the same day, one actual month prior.
M
0M is the last trading day of the most recent month, -1M is the last trading day of the prior month.
Q
0Q is the last trading day of the company's most recent fiscal quarter, -1Q is the last day of the prior
fiscal quarter.
CQ
0CQ is the last trading day of the most recent calendar quarter (March, June, September, or
December), -1CQ is the last trading day of the prior calendar quarter.
AY
0AY is the most recently completed trading day, -1AY is one actual year (365 days) prior.
Y
0Y is the last trading day of the company's most recent fiscal year, -1Y is the last trading day of the
prior fiscal year.
CY
0CY is the last trading day of the most recent calendar year (the last trading day in December), -
1CY is the last trading day of the prior calendar year.
M/D/Y
M, D, and Y can be zero, negative, or a positive number.
Examples: 0/0/-1 is the day one year ago, 0/-7/0 is the day one week ago, -1/0/0 is the day one
month ago, 12/31/-1 is the day at the end of last year.
Special FactSet Date Identifiers
The user needs to set the following properties in their account (.ACCT/.ACTM file) if they wish to use these identifiers:
Identifier
Definition
INCEPTION
Date the account was created. This typically corresponds to the first day of data in the holdings
portfolio.
ALTERINCEPTION
Alternative date option to define when the portfolio was created. This is helpful in cases where the
inception date isn't the official day the portfolio was created.
TERMINATION
Date the account is terminated.
END_OF_LAST_FISCAL
End of last fiscal year.
4. Troubleshooting
The following steps are recommended to troubleshoot errors from any of the different APIs:
• Calculation specific endpoints (POST, PUT, GET Status, GET Results, GET All Calculations)
o Record the below response headers so that FactSet's API support team can analyze your specific
request/response:
▪ x-factset-api-calculation-instance-id
▪ x-factset-api-calculation-id
▪ x-datadirect-request-key
FactSet Research Systems Inc. |
38
o Record the response body when the response is an error response. All HTTP status codes equal to and
greater than 400 are considered error responses.
o Reach out to your account team with the above information for assistance.
• Lookups endpoints (GET Components, GET Components by id, GET Accounts, GET Groups etc)
o Record the x-datadirect-request-key response header so that FactSet's API support team can analyze
your specific request/response.
o Record the response body when the response is an error response. All HTTP status codes equal to and
greater than 400 are considered error responses.
o Reach out to your account team with the above information for assistance.
5. Version Upgrade
FactSet will support old API versions for a limited time. The actual support time will depend on the API and the release
stage (i.e., beta or production). All breaking changes, functionality additions, and bug fixes across earlier versions will be
documented in the changelog.
FactSet’s API engineering team will work with the clients to ensure smooth transition to newer versions.
6. Appendix: Run Multiple Calculations Request Body Scenarios
Below table lists down some multiple calculation scenarios to help understand the points breakdown.
Request Body
Description
{
No. of Calculations: 1
"data": {
"calc1": {
"componentid":
Calculation 1
"7CF4BCEB46020A5D3C78344108905FF73A4937F5E37CFF6BD97EC29545341935",
No. of Points: 1
"account": {
"id": "CLIENT:/MAC/DEMO/DEMO_PS_EQ_EM_COUNTRY_ALPHA.ACCT"
},
Total
"dates": {
No. of Points: 1
"startdate": "20180501",
"enddate": "20180601",
"frequency": "Monthly"
},
"configid": "e95ef921-b4d4-4bb7-93ba-60eca8e3247a"
}
},
"meta": {
"contentorganization": "SimplifiedRow",
"contenttype": "Json"
}
FactSet Research Systems Inc.
|
39
}
{
No. of Calculations: 2
"data": {
"calc1": {
"componentid":
Calculation 1
"B0FF076DFF8640B1616462B82BE1F21FBF23E0E9DE62247F4A947B17F81C9A79",
No. of Points: 1
"account": {
"id": "CLIENT:/BISAM/REPOSITORY/QA/SMALL_PORT.ACCT"
},
Calculation 2
"dates": {
No. of Points: 1
"startdate": "20180101",
"enddate": "20180329",
Total
"frequency": "Monthly"
},
No. of Points: 2
"configid": "12ed7b1a-8ac2-4871-a7bf-2d5da5aaa116"
},
"calc2": {
"componentid":
"B75D10A84BBD26C9D0C91E78BC5723A4DE70FFE4192070820B9788E382D17E42",
"account": {
"id": "CLIENT:/BISAM/REPOSITORY/QA/SMALL_PORT.ACCT"
},
"configid": "c1671411-7807-4505-9296-989fe2ffc450"
}
},
"meta": {
"contentorganization": "SimplifiedRow",
"contenttype": "Json"
}
}
FactSet Research Systems Inc.
|
40