Skip to content

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:

curl -G https://api.everysk.com/v2/portfolios \
  --data-urlencode "query=#20210622" \
  --data-urlencode "workspace=main" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

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:

curl https://api.everysk.com/v2/portfolios/filter \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
        "workspace": "main",
        "tags": ["20210622"],
        "start": "20210601",
        "end": "20210630",
        "limit": 100
      }' \
  -X POST

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:

curl "https://api.everysk.com/v2/portfolios/port_V7xU8dwCMnJIuyUPHJPx2ynuz?workspace=main" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -G

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:

curl "https://api.everysk.com/v2/portfolios/port_V7xU8dwCMnJIuyUPHJPx2ynuz?workspace=main" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -X DELETE

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:

curl "https://api.everysk.com/v2/portfolios?ids=port_V7xU8dwCMnJIuyUPHJPx2ynuz,port_EUCUUH8M3GNeopdFvrZ47qGx3" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -X DELETE

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.