Get Locate

GET/v1/accounts/{account_id}/locates/{id}

Beta — this endpoint may change before general availability.

Fetch one locate by id, matched against the locate request id, locate id, and client request id, across all days in force.

Path ParametersExpand Collapse

account_id: number

id: string

ReturnsExpand Collapse

data: Locate { account_id, client_request_id, effective_date, 9 more }

A locate request joined with the locate granted for it, if any.

account_id: number

Account the locate is booked to.

formatint64

client_request_id: string

Caller-assigned id of the locate request.

effective_date: string

New York calendar date the locate is in force for.

formatdate

instrument_id: string

Instrument id.

formatuuid

locate_request_id: string

Engine-assigned locate request id.

formatuuid

requested_quantity: number

Number of shares requested.

formatint64

status: LocateStatus

Presented status of the locate.

One of the following:

"REQUESTED"

"ACCEPTED"

"REJECTED"

"EXPIRED"

locate_id: optional string

Engine-assigned locate id; set once the locate is granted. When a null/undefined value is observed, it indicates it does not apply.

formatuuid

quantity: optional number

Number of shares granted; set once the locate is granted. When a null/undefined value is observed, it indicates it does not apply.

formatint64

related_order_id: optional string

Client order id the request relates to, if any. When a null/undefined value is observed, it indicates it does not apply.

formatuuid

reserved_quantity: optional number

Number of granted shares reserved. When a null/undefined value is observed, it indicates it does not apply.

formatint64

used_quantity: optional number

Number of granted shares already used. When a null/undefined value is observed, it indicates it does not apply.

formatint64

Get Locate

curl https://api.clearstreet.com/v1/accounts/$ACCOUNT_ID/locates/$ID \
    -H "Authorization: Bearer $API_KEY"

{
  "metadata": {
    "request_id": "request_id",
    "next_page_token": "U3RhaW5sZXNzIHJvY2tz",
    "page_number": 1,
    "previous_page_token": "U3RhaW5sZXNzIHJvY2tz",
    "total_items": 42,
    "total_pages": 5
  },
  "error": {
    "code": 400,
    "message": "Order quantity must be greater than zero",
    "details": [
      {
        "foo": "bar"
      }
    ]
  },
  "data": {
    "account_id": 0,
    "client_request_id": "client_request_id",
    "effective_date": "2019-12-27",
    "instrument_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "locate_request_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "requested_quantity": 0,
    "status": "REQUESTED",
    "locate_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "quantity": 0,
    "related_order_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "reserved_quantity": 0,
    "used_quantity": 0
  }
}

Returns Examples

{
  "metadata": {
    "request_id": "request_id",
    "next_page_token": "U3RhaW5sZXNzIHJvY2tz",
    "page_number": 1,
    "previous_page_token": "U3RhaW5sZXNzIHJvY2tz",
    "total_items": 42,
    "total_pages": 5
  },
  "error": {
    "code": 400,
    "message": "Order quantity must be greater than zero",
    "details": [
      {
        "foo": "bar"
      }
    ]
  },
  "data": {
    "account_id": 0,
    "client_request_id": "client_request_id",
    "effective_date": "2019-12-27",
    "instrument_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "locate_request_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "requested_quantity": 0,
    "status": "REQUESTED",
    "locate_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "quantity": 0,
    "related_order_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "reserved_quantity": 0,
    "used_quantity": 0
  }
}