Portfolio¶
Endpoints
POST /portfolios
POST /portfolios/filter
GET /portfolios
GET /portfolios/:id
PUT /portfolios/:id
DELETE /portfolios/:id
DELETE /portfolios?ids=:id1,:id2
A portfolio is a collection of financial investments like stocks, bonds, derivatives, commodities, cash, and cash equivalents. Each security can be traded in a specific local currency. The portfolio has a base currency that is required to reflect each FX risk.
The portfolio object¶
What a portfolio object looks like?
{
"updated": 1625680032,
"description": "This is my first portfolio",
"created": 1625680032,
"tags": [
"first",
"portfolio",
"20210622"
],
"securities": [
{
"status": "OK",
"cost_price": null,
"fx_rate": null,
"unrealized_pl_in_base": null,
"exchange": "XNAS",
"symbol": "AAPL",
"multiplier": null,
"label": null,
"currency": "USD",
"market_price": null,
"unrealized_pl": null,
"isin": null,
"extra_data": null,
"id": "id1",
"quantity": 1000.0,
"name": "Apple Inc"
},
...
],
"date": "20210622",
"workspace": "main",
"nlv": null,
"base_currency": "USD",
"id": "port_V7xU8dwCMnJIuyUPHJPx2ynuz",
"name": "My First Portfolio"
}
| Property | Description |
|---|---|
id string |
Unique identifier (UID) for the portfolio. |
created float |
Time at which the object was created. Measured in seconds since the Unix epoch. |
updated float |
Time at which the object was updated. Measured in seconds since the Unix epoch. |
name string |
The portfolio's name. Up to 200 characters. |
description string |
An arbitrary string attached to the portfolio. Up to 500 characters. |
tags array |
A list of strings. Up to 32 tags. Use them to find the portfolio in a list. |
date string date |
Portfolio date in the format: YYYYMMDD. The Portfolio Date is important because it instructs the API to use the market conditions and security prices prevailing on that date. In order to run the portfolio using the market conditions prevailing today, use null. |
date_time string |
The portfolio date with a time. |
base_currency string |
3-letter ISO 4217 code for currency. Portfolios can have their base currency changed via the API call. To see all supported currencies click here. |
nlv float |
The net liquidating value of the portfolio (also called NAV). When not supplied by user, the API will calculate the net liquidating value of all the cash securities. Securities traded on margin are assumed to have NLV zero. Supplying a NLV effectively reconciles the margin. |
securities array |
It is an array of objects to describe the securities in the portfolio. Each object represents a security with a unique id, symbol, quantity and label. Up to 40000 securities. For more details click here. |
workspace string |
The workspace where the portfolio was generated. |
link_uid string |
An identifier you choose to link the portfolio to related entities. Several entities can share it. |
level string |
A free text of up to 32 characters. |
version string |
Indicates the portfolio's current version. |
Create a portfolio¶
To create a new portfolio, run the following:
curl https://api.everysk.com/v2/portfolios \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-d '{
"name": "My First Portfolio",
"tags": [
"first",
"portfolio",
"20210622"
],
"securities": [
{
"id": "id1",
"symbol": "AAPL",
"quantity": 1000.0
},
{
"id": "id2",
"symbol": "SIE:XETR",
"quantity": 750.0
}
],
"workspace": "main"
}' \
-X POST
The above call returns the following JSON object:
{
"portfolio": {
"updated": 1625680032,
"description": "",
"created": 1625680032,
"tags": [
"first",
"portfolio",
"20210622"
],
"securities": [
{
"status": "OK",
"cost_price": null,
"fx_rate": null,
"unrealized_pl_in_base": null,
"exchange": "XNAS",
"symbol": "AAPL",
"multiplier": null,
"label": null,
"currency": "USD",
"market_price": null,
"unrealized_pl": null,
"isin": null,
"extra_data": null,
"id": "id1",
"quantity": 1000.0,
"name": "Apple Inc"
},
...
],
"date": "20210622",
"workspace": "main",
"nlv": null,
"base_currency": "USD",
"id": "port_V7xU8dwCMnJIuyUPHJPx2ynuz",
"name": "My First Portfolio"
}
}
Creates and then returns the new portfolio.
HTTP Request
POST /portfolios
HTTP Parameters
| Parameter | Description |
|---|---|
name string |
REQUIRED A mnemonic string to identify a portfolio, besides the portfolio's unique id. Up to 200 characters. |
description string |
optional, default is "" Provides detailed information about your portfolio. Up to 500 characters. |
tags array |
optional, default is [] A list of strings. Up to 32 tags. |
date string date |
optional, default is null (today) Portfolio date in the format: YYYYMMDD. The Portfolio Date is important because it instructs the API to use the market conditions and security prices prevailing on that date. Therefore, historical portfolios will be calculated without look ahead. In order to run the portfolio using market conditions prevailing today, use null. |
base_currency string |
optional, default is USD 3-letter ISO 4217 code for currency. Portfolios can have their base currency changed via the API call. Do not send null: it returns 400. Leave the field out to use the default. To see all supported currencies click here. |
nlv float |
optional, default is null (calculated) The net liquidating value of the portfolio (also called NAV). When not supplied by user, the API will calculate the net liquidating value of all the cash securities. Securities traded on margin are assumed to have NLV zero. Supplying a NLV effectively reconciles the margin. |
securities array |
REQUIRED It is an array of objects to describe the securities in the portfolio. Each object represents a security, which requires a unique id, symbol, quantity. Up to 40000 securities. For more details click here. |
with_securities boolean |
optional, default is True When True, the securities inside the generated portfolio will be returned in the api response. |
workspace string |
optional, default is main The workspace where the API creates the portfolio. Send it in the JSON body. |
link_uid string |
optional, default is null An identifier you choose to link the portfolio to related entities. Several entities can share it. |
List all portfolios¶
To list all portfolios, run the following:
The above call returns the following JSON object:
{
"portfolios": [
{
"updated": 1625064158,
"description": "",
"created": 1625064158,
"tags": [
"first",
"portfolio",
"20210622"
],
"date": "20210622",
"workspace": "main",
"nlv": null,
"base_currency": "USD",
"id": "port_EUCUUH8M3GNeopdFvrZ47qGx3",
"name": "My First Portfolio"
},
...
],
"next_page_token": null
}
Returns a list of portfolios you’ve previously created. The list shows the most recently updated portfolio first. A name search returns the portfolios whose name starts with the text, case-insensitive, sorted A to Z. The list leaves out securities unless you send with_securities=true.
HTTP Request
GET /portfolios
HTTP Parameters
| Parameter | Description |
|---|---|
query string |
optional, default is null Request a list of portfolios filtering it by name or tag. When using a tag to perform a query, each term must include a hashtag prefix. (e.g: query="#april #sample") See Filter with query. |
workspace string |
optional, default is main The workspace to list. |
page_size integer |
optional, default is 10 Set the number of objects that will be listed per page, between 1 and 10000. |
page_token string |
optional, default is null The next_page_token from the previous response. See the pagination guide. |
with_securities boolean |
optional, default is False When True, each portfolio in the list includes its securities. |
start, end, date_time, period_field string |
optional Filter the list by a period. See Filter by period. |
Filter portfolios¶
To filter portfolios, run the following:
The above call returns the following JSON object:
{
"portfolios": [
{
"updated": 1625064158,
"description": "",
"created": 1625064158,
"tags": ["first", "portfolio", "20210622"],
"date": "20210622",
"workspace": "main",
"nlv": null,
"base_currency": "USD",
"id": "port_EUCUUH8M3GNeopdFvrZ47qGx3",
"name": "My First Portfolio"
},
...
]
}
Returns the portfolios of one workspace that match every filter you send, up to limit. The response has no next_page_token.
HTTP Request
POST /portfolios/filter
HTTP Parameters
| Parameter | Description |
|---|---|
workspace string |
REQUIRED The workspace to search. Without it, the API returns 400. |
tags array |
optional, default is [] A list of strings. Returns the portfolios that have every one of these tags. |
link_uid string |
optional, default is null Returns the portfolios with this link_uid. |
start string |
optional, default is null Returns the portfolios from this day onward, in the format YYYYMMDD. |
end string |
optional, default is null Returns the portfolios up to this day, in the format YYYYMMDD. |
date_time string |
optional, default is null Returns the portfolios of one day, in the format YYYYMMDD. It replaces start and end. |
period_field string |
optional, default is date The property that start, end and date_time filter: date or updated_on. |
limit integer |
optional, default is 1 The maximum number of portfolios to return, between 1 and 10000. |
with_securities boolean |
optional, default is False When True, each item includes its securities. |
Retrieve a portfolio¶
To retrieve a portfolio, run the following:
The above call returns the following JSON object:
{
"portfolio": {
"updated": 1625680032,
"description": "",
"created": 1625680032,
"tags": [
"first",
"portfolio",
"20210622"
],
"securities": [
{
"status": "OK",
"cost_price": null,
"fx_rate": null,
"unrealized_pl_in_base": null,
"exchange": "XNAS",
"symbol": "AAPL",
"multiplier": null,
"label": null,
"currency": "USD",
"market_price": null,
"unrealized_pl": null,
"isin": null,
"extra_data": null,
"id": "id1",
"quantity": 1000.0,
"name": "Apple Inc"
},
...
],
"date": "20210622",
"workspace": "main",
"nlv": null,
"base_currency": "USD",
"id": "port_V7xU8dwCMnJIuyUPHJPx2ynuz",
"name": "My First Portfolio"
}
}
Retrieves the details of an existing portfolio by supplying the portfolio's id.
HTTP Request
GET /portfolios/:id
HTTP Parameters
| Parameter | Description |
|---|---|
id string |
REQUIRED A unique identifier (UID) for a portfolio. A portfolio's id will always look like this: port_V7xU8dwCMnJIuyUPHJPx2ynuz |
workspace string |
optional The workspace of the object. If you send it and the object is in another workspace, the API returns 403. |
Update a portfolio¶
To update a portfolio, run the following:
curl https://api.everysk.com/v2/portfolios/port_V7xU8dwCMnJIuyUPHJPx2ynuz \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-d '{
"name": "New Portfolio Name",
"description": "New Portfolio Description",
"securities": [
{
"id": "id3",
"symbol": "NFLX",
"quantity": 500.0
}
]
}' \
-X PUT
The above call returns the following JSON object:
{
"portfolio": {
"updated": 1625680366,
"description": "New Portfolio Description",
"created": 1625680032,
"tags": ["first", "portfolio", "20210622"],
"securities": [
{
"status": "OK",
"cost_price": null,
"fx_rate": null,
"unrealized_pl_in_base": null,
"exchange": "XNAS",
"symbol": "NFLX",
"multiplier": null,
"label": null,
"currency": "USD",
"market_price": null,
"unrealized_pl": null,
"isin": null,
"extra_data": null,
"id": "id3",
"quantity": 500.0,
"name": "NetFlix Inc"
}
],
"date": "20210622",
"workspace": "main",
"nlv": null,
"base_currency": "USD",
"id": "port_V7xU8dwCMnJIuyUPHJPx2ynuz",
"name": "New Portfolio Name"
}
}
Updates a portfolio and then returns the updated portfolio. Only the fields you send change. The other fields keep their current values.
HTTP Request
PUT /portfolios/:id
HTTP Parameters
| Parameter | Description |
|---|---|
id string |
REQUIRED A unique identifier (UID) for a portfolio. |
name string |
optional A string to identify a portfolio besides the portfolio's id. Up to 200 characters. |
description string |
optional Use this field to provide detailed information about your portfolio. Up to 500 characters. |
tags array |
optional A list of strings. Up to 32 tags. Replaces the current tags. |
date string date |
optional Portfolio date in the format: YYYYMMDD. |
base_currency string |
optional 3-letter ISO 4217 code for currency. Entering a currency here changes the base currency of the portfolio. Do not send null: it returns 400. To see all supported currencies click here. |
nlv float |
optional The net liquidating value of the portfolio (also called NAV). |
securities array |
optional It is an array of objects to describe the securities in the portfolio. Each object represents a security with a unique id, symbol, quantity and label. The list replaces the current securities. Up to 40000 securities. For more details click here. |
workspace string |
optional Moves the object to this workspace. Leave it out to keep the current workspace. |
link_uid string |
optional An identifier you choose to link the portfolio to related entities. |
with_securities boolean |
optional, default is True When True, the response includes the securities of the portfolio. |
Delete a portfolio¶
To delete a portfolio, run the following:
The above call returns the following JSON object:
{
"portfolio": {
"deleted": true,
"id": "port_V7xU8dwCMnJIuyUPHJPx2ynuz",
"name": "My First Portfolio"
}
}
Permanently deletes a portfolio. It cannot be undone. Returns an object with the portfolio's id and an attribute specifying whether the portfolio was successfully deleted or not.
HTTP Request
DELETE /portfolios/:id
HTTP Parameters
| Parameter | Description |
|---|---|
id string |
REQUIRED The portfolio's unique identifier. |
workspace string |
optional The workspace of the object. If you send it and the object is in another workspace, the API returns 403. |
Delete several portfolios¶
To delete several portfolios, run the following:
The above call returns the following JSON object:
{
"portfolios": [
{
"id": "port_V7xU8dwCMnJIuyUPHJPx2ynuz",
"name": "BATCH_DELETE",
"deleted": true
},
{
"id": "port_EUCUUH8M3GNeopdFvrZ47qGx3",
"name": "BATCH_DELETE",
"deleted": true
}
]
}
Permanently deletes several portfolios in one request. It cannot be undone. The response has one item for each id in ids. deleted is false for an id that the API could not delete. An id that does not exist also returns deleted: true. A bulk delete does not check workspace.
HTTP Request
DELETE /portfolios?ids=:id1,:id2
HTTP Parameters
| Parameter | Description |
|---|---|
ids string |
REQUIRED The ids to delete, separated by commas. |