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] Get a list of watchlists

GET/v2/watchlists
Returns the list of watchlists registered under the account.

Response

An array of Watchlist object

[POST] Create a watchlist

POST/v2/watchlists
Create a new watchlist with initial set of assets.

Parameters

Body Parameters

name
stringRequired
arbitrary name string, up to 64 characters
symbols
array[string]
set of symbol string

Response

An array of Watchlist object

Errors

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] Get a watchlist

GET/v2/watchlists/{watchlist_id}
Returns a watchlist identified by the ID.

Parameters

Path Parameters

watchlist_id
string<uuid>
Watchlist ID

Response

A Watchlist object

Errors

404 Not found
the requested watchlist is not found

[PUT] Update watchlist

PUT/v2/watchlists/{watchlist_id}
Update the name and/or content of watchlist.

Parameters

Path Parameters

watchlist_id
string<uuid>
Watchlist ID

Body Parameters

name
string
the new watchlist name
string
array[string]
the new list of symbol names to replace the watchlist content

Response

A Watchlist object with updated content

Errors

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

[POST] Add an asset

POST/v2/watchlists/{watchlist_id}
Append an asset for the symbol to the end of watchlist asset list

Parameters

Path Parameters

watchlist_id
string<uuid>
Watchlist ID

Body Parameters

string
array[string]Required
the new list of symbol names to replace the watchlist content

Response

A Watchlist object with updated content

Errors

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

[DELETE] Delete a watchlist

DELETE/v2/watchlists/{watchlist_id}
Delete a watchlist. This is a permantent deletion.

Parameters

Path Parameters

watchlist_id
string<uuid>
Watchlist ID

Response

Errors

404 Not found
the requested watchlist is not found, or one of the symbol is not found in the assets

[DELETE] Remove a symbol from the watchlist

DELETE/v2/watchlists/{watchlist_id}/{symbol}
Delete one entry for an asset by symbol name

Parameters

Path Parameters

watchlist_id
string<uuid>
Watchlist ID
symbol
string
symbol name to remove from the watchlist content

Response

Errors

404 Not found
the requested watchlist is not found, or one of 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

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