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

A 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

symbols

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

symbol

stringRequired

the symbol name to add to the watchlist

Response

A Watchlist object with updated content

Errors

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

DELETE/v2/watchlists/{watchlist_id}

Delete a watchlist. This is a permanent deletion.

Parameters

Path Parameters

watchlist_id

string<uuid>

Watchlist ID

Response

Errors

404 Not found

the requested watchlist is not found

[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 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

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