Skip to content

Private Security


Endpoints

POST      /private_securities
GET       /private_securities
GET       /private_securities/:id
PUT       /private_securities/:id
DELETE    /private_securities/:id
DELETE    /private_securities?ids=:symbol1,:symbol2

A private security is a proprietary instrument that is not publicly traded. It allows you to define custom securities with their own pricing data, instrument type, and currency for use in portfolio calculations.

Not bound to a workspace

Private securities are scoped to the account, not to a workspace. Every workspace in the account sees the same private securities.

The symbol must match the pattern ^PRIVATE:[A-Z0-9_]*$: the PRIVATE: prefix followed by uppercase letters, digits and underscores, for example PRIVATE:MYSECURITY. It has 9 to 109 characters. A symbol that already exists returns 400 with the message Invalid Argument: symbol: entity already exists.

The private security object

What a private security object looks like?

{
  "symbol": "PRIVATE:MYSECURITY",
  "name": "My Private Security",
  "description": "This is my first private security",
  "type": "PrivateFixedIncome",
  "currency": "USD",
  "tags": ["first", "private", "20210622"],
  "data": {
    "principal": 1000.0,
    "method": "PRIVATE",
    "yield": 4.35,
    "m2m_spread": 0.0,
    "issue_date": "20210713",
    "starting_date": "20210720",
    "expiry_date": "20260713",
    "events": [
      {"date": "20220713", "event_type": "I", "value": 4.35},
      {"date": "20230713", "event_type": "A", "value": 25.0},
      {"date": "20230713", "event_type": "I", "value": 4.35}
    ]
  },
  "created": 1625598288,
  "updated": 1625598288
}
Property Description
symbol string Unique identifier for the private security. Must match ^PRIVATE:[A-Z0-9_]*$, 9 to 109 characters.
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 name of the private security. Up to 200 characters.
description string An arbitrary string attached to the private security. Up to 500 characters.
tags array A list of strings. Up to 32 tags. Use them to find the private security in a list.
type string The type of the private security: PrivateFixedIncome or PrivateCustomIndex.
currency string 3-letter ISO 4217 code for the security's currency.
data object The data of the private security. See The data object.
version string Indicates the private security's current version.

The data object

The API checks only that data is a JSON object and that its compressed size fits the storage limit. It stores data as you send it.

For PrivateFixedIncome, the pricing engine reads these keys:

Key Description
principal float The principal (face value) of the security.
method string The pricing method: PRIVATE, PRE, DI-SPREAD, DI-PERC, SEL or IPCA. Defaults to PRIVATE. Another value makes the calculations fail.
yield float The annual coupon rate, in percent. For example, 4.35 is 4.35% a year.
m2m_spread float The mark-to-market spread, in percent.
issue_date string The issue date, in the format YYYYMMDD.
starting_date string The start date, in the format YYYYMMDD.
expiry_date string The expiry date, in the format YYYYMMDD.
events array The cash-flow schedule. Each event is an object with date (YYYYMMDD), event_type and value (float). See the event types below.

The pricing engine reads three event types and ignores the others:

event_type Meaning value
I Interest payment date. Not used. The engine pays the yield rate on this date (the DI curve for DI-PERC).
A Amortization. The percent of principal paid on this date. For example, 25.0 pays 25%.
V Principal repayment. The amount paid on this date, in the currency of the security.

The API also accepts the type PrivateCustomIndex, but the calculations price only PrivateFixedIncome. For a security priced from your own time series, use a Custom Index.

Create a private security

Creates and then returns the new private security.

To create a new private security, run the following:

curl https://api.everysk.com/v2/private_securities \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
        "symbol": "PRIVATE:MYSECURITY",
        "name": "My Private Security",
        "description": "This is my first private security",
        "type": "PrivateFixedIncome",
        "currency": "USD",
        "tags": ["first", "private", "20210622"],
        "data": {
          "principal": 1000.0,
          "method": "PRIVATE",
          "yield": 4.35,
          "m2m_spread": 0.0,
          "issue_date": "20210713",
          "starting_date": "20210720",
          "expiry_date": "20260713",
          "events": [
            {"date": "20220713", "event_type": "I", "value": 4.35},
            {"date": "20230713", "event_type": "A", "value": 25.0},
            {"date": "20230713", "event_type": "I", "value": 4.35}
          ]
        }
      }' \
  -X POST

The above call returns the following JSON object:

{
  "private_security": {
    "symbol": "PRIVATE:MYSECURITY",
    "name": "My Private Security",
    "description": "This is my first private security",
    "type": "PrivateFixedIncome",
    "currency": "USD",
    "tags": ["first", "private", "20210622"],
    "data": {
      "principal": 1000.0,
      "method": "PRIVATE",
      "yield": 4.35,
      "m2m_spread": 0.0,
      "issue_date": "20210713",
      "starting_date": "20210720",
      "expiry_date": "20260713",
      "events": [
        {"date": "20220713", "event_type": "I", "value": 4.35},
        {"date": "20230713", "event_type": "A", "value": 25.0},
        {"date": "20230713", "event_type": "I", "value": 4.35}
      ]
    },
    "created": 1625598288,
    "updated": 1625598288
  }
}

HTTP Request

POST /private_securities

HTTP Parameters

Parameter Description
symbol string REQUIRED A unique identifier (UID) for the private security. It must match ^PRIVATE:[A-Z0-9_]*$, 9 to 109 characters. A symbol that already exists returns 400.
name string REQUIRED A string to identify the private security besides its symbol. Up to 200 characters.
description string optional, default is "" Provides detailed information about your private security. Up to 500 characters.
tags array optional, default is [] A list of strings. Up to 32 tags.
type string REQUIRED The type of the private security: PrivateFixedIncome or PrivateCustomIndex. Another value returns 400. Only PrivateFixedIncome is priced; see The data object.
currency string optional, default is USD 3-letter ISO 4217 code for the security's currency. Do not send null: it returns 400. Leave the field out to use the default.
data object REQUIRED The data of the private security. See The data object.
with_data boolean optional, default is True When True, the response includes the data of the private security.

List all private securities

Returns a list of private securities you've previously created. The list shows the most recently updated private security first. A name search returns the private securities whose name starts with the text, case-insensitive, sorted A to Z. The list leaves out data unless you send with_data=true.

To list all private securities, run the following:

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

The above call returns the following JSON object:

{
  "private_securities": [
    {
      "symbol": "PRIVATE:MYSECURITY",
      "name": "My Private Security",
      "description": "This is my first private security",
      "type": "PrivateFixedIncome",
      "currency": "USD",
      "tags": ["first", "private", "20210622"],
      "created": 1625598288,
      "updated": 1625598288
    },
    ...
  ],
  "next_page_token": null
}

HTTP Request

GET /private_securities

HTTP Parameters

Parameter Description
query string optional, default is null Request a list of private securities 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.
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_data boolean optional, default is False When True, each private security in the list includes its data.
start, end, date_time, period_field string optional Filter the list by a period. Private securities have no date, so the period applies to updated_on. See Filter by period.

Retrieve a private security

Retrieves the details of an existing private security by supplying its symbol.

To retrieve a private security, run the following:

curl https://api.everysk.com/v2/private_securities/PRIVATE:MYSECURITY \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -G

The above call returns the following JSON object:

{
  "private_security": {
    "symbol": "PRIVATE:MYSECURITY",
    "name": "My Private Security",
    "description": "This is my first private security",
    "type": "PrivateFixedIncome",
    "currency": "USD",
    "tags": ["first", "private", "20210622"],
    "data": {
      "principal": 1000.0,
      "method": "PRIVATE",
      "yield": 4.35,
      "m2m_spread": 0.0,
      "issue_date": "20210713",
      "starting_date": "20210720",
      "expiry_date": "20260713",
      "events": [
        {"date": "20220713", "event_type": "I", "value": 4.35},
        {"date": "20230713", "event_type": "A", "value": 25.0},
        {"date": "20230713", "event_type": "I", "value": 4.35}
      ]
    },
    "created": 1625598288,
    "updated": 1625598288
  }
}

HTTP Request

GET /private_securities/:id

HTTP Parameters

Parameter Description
symbol string REQUIRED A unique identifier (UID) for the private security.

Update a private security

Updates a private security and then returns the updated object. Every field is optional. Only the fields you send change. The other fields keep their current values.

To update a private security, run the following:

curl https://api.everysk.com/v2/private_securities/PRIVATE:MYSECURITY \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
        "name": "My Updated Security",
        "description": "Updated description"
      }' \
  -X PUT

The above call returns the following JSON object:

{
  "private_security": {
    "symbol": "PRIVATE:MYSECURITY",
    "name": "My Updated Security",
    "description": "Updated description",
    "type": "PrivateFixedIncome",
    "currency": "USD",
    "tags": ["first", "private", "20210622"],
    "data": {
      "principal": 1000.0,
      "method": "PRIVATE",
      "yield": 4.35,
      "m2m_spread": 0.0,
      "issue_date": "20210713",
      "starting_date": "20210720",
      "expiry_date": "20260713",
      "events": [
        {"date": "20220713", "event_type": "I", "value": 4.35},
        {"date": "20230713", "event_type": "A", "value": 25.0},
        {"date": "20230713", "event_type": "I", "value": 4.35}
      ]
    },
    "created": 1625598288,
    "updated": 1625668154
  }
}

HTTP Request

PUT /private_securities/:id

HTTP Parameters

Parameter Description
symbol string REQUIRED The symbol of the private security, in the URL path. You cannot change it.
name string optional A string to identify the private security besides its symbol. Up to 200 characters.
description string optional Provides detailed information about your private security. Up to 500 characters.
tags array optional A list of strings. Up to 32 tags. Replaces the current tags.
type string optional The type of the private security: PrivateFixedIncome or PrivateCustomIndex.
currency string optional 3-letter ISO 4217 code for the security's currency. Do not send null: it returns 400.
data object optional The data of the private security. It replaces the current data. See The data object.
with_data boolean optional, default is True When True, the response includes the data of the private security.

Delete a private security

To delete a private security, run the following:

curl https://api.everysk.com/v2/private_securities/PRIVATE:MYSECURITY \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -X DELETE

The above call returns the following JSON object:

{
  "private_security": {
    "deleted": true,
    "symbol": "PRIVATE:MYSECURITY",
    "name": "My Private Security"
  }
}

Permanently deletes a private security. It cannot be undone. Returns an object with the private security's symbol and an attribute specifying whether it was successfully deleted or not.

HTTP Request

DELETE /private_securities/:id

HTTP Parameters

Parameter Description
symbol string REQUIRED A unique identifier (UID) for the private security.

Delete several private securities

To delete several private securities, run the following:

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

The above call returns the following JSON object:

{
  "private_securities": [
    {
      "symbol": "PRIVATE:MYSECURITY",
      "name": "BATCH_DELETE",
      "deleted": true
    },
    {
      "symbol": "PRIVATE:MYBOND",
      "name": "BATCH_DELETE",
      "deleted": true
    }
  ]
}

Permanently deletes several private securities in one request. It cannot be undone. The response has one item for each symbol in ids. deleted is false for a symbol that the API could not delete. A symbol that does not exist also returns deleted: true.

HTTP Request

DELETE /private_securities?ids=:symbol1,:symbol2

HTTP Parameters

Parameter Description
ids string REQUIRED The symbols to delete, separated by commas.