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 object

Create 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 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 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 object

Errors

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

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