Watchlist #
The watchlist API provides CRUD operation for the account’s watchlist.
An account can have multiple watchlists and each is uniquely identified by id
but can also be addressed by user-defined name
. Each watchlist is an ordered
list of assets.
Get a list of watchlists
GET /v2/watchlists
Returns the list of watchlists registered under the account.
Response
An array of Watchlist objectCreate a watchlist
POST /v2/watchlists
Create a new watchlist with initial set of assets.
Parameters
Body Parameters
Attribute | Type | Requirement | Description |
---|---|---|---|
name |
string | Required |
arbitrary name string, up to 64 characters |
symbols |
array[string] | Optional |
set of symbol string |
Response
A Watchlist objectErrors
404 Not found
one of the symbol is not found in the assets
422 Unprocessable
watchlist name is not unique, or some parameters are not valid
Get a watchlist
GET /v2/watchlists/{watchlist_id}
Returns a watchlist identified by the ID.
Parameters
Path Parameters
Attribute | Type | Requirement | Description |
---|---|---|---|
watchlist_id |
string<uuid> | Optional |
Watchlist ID |
Response
A Watchlist objectErrors
404 Not found
the requested watchlist is not found
Update watchlist
PUT /v2/watchlists/{watchlist_id}
Update the name and/or content of watchlist.
Parameters
Path Parameters
Attribute | Type | Requirement | Description |
---|---|---|---|
watchlist_id |
string<uuid> | Optional |
Watchlist ID |
Body Parameters
Attribute | Type | Requirement | Description |
---|---|---|---|
name |
string | Optional |
the new watchlist name |
symbols |
array[string] | Optional |
the new list of symbol names to replace the watchlist content |
Response
A Watchlist object with updated contentErrors
404 Not found
the requested watchlist is not found, or one of the symbol is not found in the assets
422 Unprocessable
some parameters are not valid
Add an asset
POST /v2/watchlists/{watchlist_id}
Append an asset for the symbol to the end of watchlist asset list
Parameters
Path Parameters
Attribute | Type | Requirement | Description |
---|---|---|---|
watchlist_id |
string<uuid> | Optional |
Watchlist ID |
Body Parameters
Attribute | Type | Requirement | Description |
---|---|---|---|
symbol |
string | Required |
the symbol name to add to the watchlist |
Response
A Watchlist object with updated contentErrors
404 Not found
the requested watchlist is not found, or the symbol is not found in the assets
422 Unprocessable
some parameters are not valid
Delete a watchlist
DELETE /v2/watchlists/{watchlist_id}
Delete a watchlist. This is a permanent deletion.
Parameters
Path Parameters
Attribute | Type | Requirement | Description |
---|---|---|---|
watchlist_id |
string<uuid> | Optional |
Watchlist ID |
Response
Errors
404 Not found
the requested watchlist is not found
Remove a symbol from the watchlist
DELETE /v2/watchlists/{watchlist_id}/{symbol}
Delete one entry for an asset by symbol name
Parameters
Path Parameters
Attribute | Type | Requirement | Description |
---|---|---|---|
watchlist_id |
string<uuid> | Optional |
Watchlist ID |
symbol |
string | Optional |
symbol name to remove from the watchlist content |
Response
Errors
404 Not found
the requested watchlist is not found, or the symbol is not found in the assets
Endpoints for Watchlist name #
You can also call GET, PUT, POST and DELETE with watchlist name with another endpoint /v2/watchlists:by_name
and query parameter name=<watchlist_name>
, instead of /v2/watchlists/{watchlist_id}
endpoints.
Watchlist Entity #
Example #
{
"account_id": "1d5493c9-ea39-4377-aa94-340734c368ae",
"assets": [
{
"class": "us_equity",
"easy_to_borrow": true,
"exchange": "ARCA",
"id": "b28f4066-5c6d-479b-a2af-85dc1a8f16fb",
"marginable": true,
"shortable": true,
"status": "active",
"symbol": "SPY",
"tradable": true
},
{
"class": "us_equity",
"easy_to_borrow": false,
"exchange": "NASDAQ",
"id": "f801f835-bfe6-4a9d-a6b1-ccbb84bfd75f",
"marginable": true,
"shortable": false,
"status": "active",
"symbol": "AMZN",
"tradable": true
}
],
"created_at": "2019-10-30T07:54:42.981322Z",
"id": "fb306e55-16d3-4118-8c3d-c1615fcd4c03",
"name": "Monday List",
"updated_at": "2019-10-30T07:54:42.981322Z"
}
Properties #
Attribute | Type | Description |
---|---|---|
id |
string<uuid> | watchlist id |
created_at |
string<timestamp> | |
updated_at |
string<timestamp> | |
name |
string | user-defined watchlist name (up to 64 characters) |
account_id |
string<uuid> | account ID |
assets |
array of Asset objects | the content of this watchlist, in the order as registered by the client |