Developers › API reference › Reference data

GET `/api/v1/securities/{id}`

One security, with its user-defined fields.

Scope reference:read
ETag
operationId referenceSecurity

The token needs the scope reference:read, and the person or service account behind it needs the matching privileges and account permissions, exactly as on the screens. See Scopes.

ETag. The answer carries an ETag header. Keep it: changing this resource needs If-Match with that value.

Request

GET /api/v1/securities/{id}

Path parameters

Name	Description	Example
`id`	The id of the securitie.	`3`

Headers

Header	Required	Value
`Authorization`	yes	`Bearer <token>`: an OAuth access token (`vat_…`) or a personal access token (`vpt_…`). Get a token

Examples

Keep the token in an environment variable (VESTORIS_TOKEN), never in the script.

curl

curl "https://vestoris.com/api/v1/securities/3" \
  -H "Authorization: Bearer $VESTORIS_TOKEN"

Python (requests)

import os, requests

r = requests.get(
    "https://vestoris.com/api/v1/securities/3",
    headers={
        "Authorization": f"Bearer {os.environ['VESTORIS_TOKEN']}",
    },
    timeout=30,
)
r.raise_for_status()  # errors are application/problem+json with a stable "code"
print(r.json())

JavaScript (fetch)

const res = await fetch("https://vestoris.com/api/v1/securities/3", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.VESTORIS_TOKEN}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.code}: ${data.detail}`); // problem+json
console.log(data);

Response

200 OK, application/json: Security. With an ETag header. Rate-limit headers: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.

Response fields

Field	Type	Description
`id`	id (string)	The record's id (a string of digits).
`symbol`	string	Ticker symbol.
`name`	string	The security's name.
`isin`	string or null	ISIN (check digit validated).
`cusip`	string or null	CUSIP (check digit validated).
`sedol`	string or null	SEDOL.
`figi`	string or null	FIGI.
`sec_type`	string	Security type (common, etf, adr…).
`sector`	string	Sector.
`industry`	string	Industry.
`issuer`	string	The issuer's name.
`issuer_code`	string or null	The issuer's code.
`country`	string	Country (ISO 3166 alpha-2).
`asset_class`	string	Asset class, e.g. "Equity".
`market_cap_bucket`	string	Market-cap bucket (mega, large, mid, small).
`currency`	string	Currency (ISO 4217).
`exchange`	string	Exchange code.
`avg_daily_volume`	decimal string or null	Average daily volume in shares (used by liquidity rules).
`esg_flags`	list of string	ESG flags used by exclusion lists.
`active`	boolean	Whether it is in use.
`user_defined`	object	User-defined field values by field name.
`created_at`	date-time or null	When it was created.

Example response

HTTP/1.1 200 OK
Content-Type: application/json
ETag: "3f1a9c0e5b7d2a4c8e6f0b1d3a5c7e9f"

{
    "id": "1042",
    "symbol": "AAPL",
    "name": "Apple Inc.",
    "isin": "US0378331005",
    "cusip": "037833100",
    "sedol": "2046251",
    "figi": "BBG000B9XRY4",
    "sec_type": "common",
    "sector": "Information Technology",
    "industry": "Consumer Electronics",
    "issuer": "Apple Inc.",
    "issuer_code": "AAPL",
    "country": "US",
    "asset_class": "Equity",
    "market_cap_bucket": "mega",
    "currency": "USD",
    "exchange": "XNAS",
    "avg_daily_volume": "58000000",
    "esg_flags": [],
    "active": true,
    "user_defined": {
        "Internal rating": "A"
    },
    "created_at": "2026-10-27T14:30:00Z"
}

Example values. Your values depend on your firm's data; prices, orders and fills are simulated.

Status codes and errors

Errors are application/problem+json (RFC 9457) with a stable code to program against; the detail says what to fix. See Errors.

Status	When	Problem codes
200	Success
400	The request is malformed	`invalid_request`
401	No token, or it is invalid or expired	`invalid_token`
403	The token lacks the scope, or the person or service account behind it lacks the privilege or account permission	`insufficient_scope` `forbidden` `ip_not_allowed`
404	Not found, or not visible to you (the API never confirms what you may not see)	`not_found`
429	Rate limited: wait for Retry-After seconds	`rate_limited`

{
    "type": "https://vestoris.com/developers/errors#validation_failed",
    "title": "Validation failed",
    "status": 422,
    "detail": "Quantity must be greater than zero.",
    "code": "validation_failed",
    "instance": "/api/v1/securities/3"
}

On the screens

The same thing in the app is explained in:

Securities and prices