Locates

The Locates API allows users to request, manage, and sell stock locates for short selling. This comprehensive guide describes the complete workflow for managing locates through the API, including requesting locates, checking status, accepting quotes, and selling (crediting) locates from inventory.

API Update - December 2025

The GET /v1/api/accounts/{accountId}/locates endpoint has been replaced with two new endpoints:

• GET /v1/api/accounts/{accountId}/locates/inventory - Returns active locate inventory for the current trading day
• GET /v1/api/accounts/{accountId}/locates/history - Returns all open/closed/expired locates for the day

Please update your integrations to use the appropriate new endpoint based on your needs.

---

Workflow

1. Request a Locate

Request a locate for a specific symbol and quantity.

Endpoint

POST /v1/api/accounts/locates/quote

Request Headers

Content-Type: application/json
TZ-API-KEY-ID: {API_KEY}
TZ-API-SECRET-KEY: {API_SECRET}

Request Body

{
  "account": "ACCOUNT_ID",
  "symbol": "AAPL",
  "quantity": 1000,
  "quoteReqID": "Q1701532800000"
}

Request Parameters

Field	Type	Required	Description
account	string	Yes	The trading account ID
symbol	string	Yes	Stock symbol to locate
quantity	integer	Yes	Number of shares to locate
quoteReqID	string	Yes	Unique quote request ID

Response

The endpoint acknowledges the locate request. Status updates will appear in the history.

Example

curl -X POST "https://webapi-dev.tradezero.co/v1/api/accounts/locates/quote" \
  -H "TZ-API-KEY-ID: YOUR_API_KEY" \
  -H "TZ-API-SECRET-KEY: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "ACCOUNT123",
    "symbol": "TSLA",
    "quantity": 500,
    "quoteReqID": "Q1701532800000"
  }'

---

2. Check Locate Status

Retrieve the current status of locate requests and inventory. There are two endpoints available:

• Inventory Endpoint: Returns active locate inventory for the current trading day
• History Endpoint: Returns all open/closed/expired locates for the day

Endpoints

Get Locate Inventory

GET /v1/api/accounts/{accountId}/locates/inventory

Get Locate History

GET /v1/api/accounts/{accountId}/locates/history

Request Headers

TZ-API-KEY-ID: {API_KEY}
TZ-API-SECRET-KEY: {API_SECRET}

Path Parameters

Parameter	Type	Required	Description
accountId	string	Yes	The trading account ID

Response - Inventory Endpoint

Returns active locate inventory for the current trading day:

Field	Type	Description
accountId	string	Account identifier
symbol	string	Ticker symbol for the locate availability
available	number	Number of shares available for locating
sold	number	Number of shares that have been sold
toBeSold	number	Number of shares that are to be sold
unavailable	number	Number of shares currently unavailable for locating
locateType	number	Type of locate (0 = Unknown, 1 = Locate, 2 = Intraday Only, 3 = Pre-Borrow, 4 = Single Use)

{
  "locateInventory": [
    {
      "accountId": "ACCOUNT123",
      "symbol": "AAPL",
      "available": 1000,
      "sold": 0,
      "toBeSold": 0,
      "unavailable": 0,
      "locateType": 1
    }
  ]
}

Response - History Endpoint

Returns all open/closed/expired locates for the day:

Field	Type	Description
accountId	string	Account identifier
symbol	string	Ticker symbol for the locate request
locateShares	number	Number of shares located
filledShares	number	Number of shares that have been filled
locateStatus	number	Locate status (48 = New, 50 = Filled, 52 = Canceled, 54 = Pending, 56 = Rejected, 65 = Offered, 67 = Expired, 81 = Quoting)
locateType	number	Type of locate (0 = Unknown, 1 = Locate, 2 = Intraday Only, 3 = Pre-Borrow, 4 = Single Use)
locatePrice	number	Price at which the locate was quoted
quoteReqId	string	Quote request identifier
preBorrow	boolean	Indicates if the locate is a pre-borrow
locateError	number	Value of 1 indicates an error with the locate request
text	string	Additional information or message related to the locate request
createdDate	string	Date the locate request was created (ISO 8601 format)
updatedDate	string	Date the locate request was last updated (ISO 8601 format)

{
  "locateHistory": [
    {
      "accountId": "ACCOUNT123",
      "symbol": "TSLA",
      "locateShares": 500,
      "filledShares": 0,
      "locateStatus": 65,
      "locateType": 1,
      "locatePrice": 0.003,
      "quoteReqId": "Q1701532800000",
      "preBorrow": false,
      "locateError": 0,
      "text": "",
      "createdDate": "2024-12-02T10:30:00Z",
      "updatedDate": "2024-12-02T10:30:00Z"
    }
  ]
}

Locate Status Codes

Code	Status	Description
48	New	Locate request is new
50	Filled	Locate has been filled
52	Canceled	Locate request was canceled
54	Pending	Locate request is pending
56	Rejected	Locate request was rejected
65	Offered	Quote is offered and available for acceptance
67	Expired	Quote has expired
81	Quoting	Locate is being quoted

Locate Type Codes

The following table shows locate type codes as returned in responses. When making requests (e.g., sell locate), use the corresponding string values shown in the "String Value" column.

Code	Type	String Value	Description
0	Unknown	"Unknown"	Unknown locate type
1	Locate	"Locate"	Standard locate
2	Intraday Only	"IntraDay"	Intraday locate only
3	Pre-Borrow	"PreBorrow"	Pre-borrowed shares
4	Single Use	"SingleUse"	Single use locate

Examples

Get Locate Inventory:

curl -X GET "https://webapi-dev.tradezero.co/v1/api/accounts/ACCOUNT123/locates/inventory" \
  -H "TZ-API-KEY-ID: YOUR_API_KEY" \
  -H "TZ-API-SECRET-KEY: YOUR_API_SECRET"

Get Locate History:

curl -X GET "https://webapi-dev.tradezero.co/v1/api/accounts/ACCOUNT123/locates/history" \
  -H "TZ-API-KEY-ID: YOUR_API_KEY" \
  -H "TZ-API-SECRET-KEY: YOUR_API_SECRET"

---

3. Accept or Cancel Offered Locates

When a locate request has locateStatus = 65 (Offered), you can either accept or cancel it.

Note: Accept is NOT available for locateType = 2 (Intraday Only) locates.

3a. Accept a Locate Quote

Endpoint

POST /v1/api/accounts/locates/accept

Request Headers

Content-Type: application/json
TZ-API-KEY-ID: {API_KEY}
TZ-API-SECRET-KEY: {API_SECRET}

Request Body

{
  "accountId": "ACCOUNT123",
  "quoteReqID": "Q1701532800000"
}

Request Parameters

Field	Type	Required	Description
accountId	string	Yes	The trading account ID
quoteReqID	string	Yes	Quote request ID from the history

Response

Upon successful acceptance, the locate will be moved to your inventory with status changed to Filled (50).

Example

curl -X POST "https://webapi-dev.tradezero.co/v1/api/accounts/locates/accept" \
  -H "TZ-API-KEY-ID: YOUR_API_KEY" \
  -H "TZ-API-SECRET-KEY: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "ACCOUNT123",
    "quoteReqID": "Q1701532800000"
  }'

---

3b. Cancel a Locate Quote

Endpoint

DELETE /v1/api/accounts/locates/cancel/accounts/{accountId}/quoteReqID/{quoteReqID}

Request Headers

TZ-API-KEY-ID: {API_KEY}
TZ-API-SECRET-KEY: {API_SECRET}

Path Parameters

Parameter	Type	Required	Description
accountId	string	Yes	The trading account ID
quoteReqID	string	Yes	Quote request ID to cancel

Response

Upon successful cancellation, the locate status will change to Canceled (52).

Example

curl -X DELETE "https://webapi-dev.tradezero.co/v1/api/accounts/locates/cancel/accounts/ACCOUNT123/quoteReqID/Q1701532800000" \
  -H "TZ-API-KEY-ID: YOUR_API_KEY" \
  -H "TZ-API-SECRET-KEY: YOUR_API_SECRET"

---

4. Sell (Credit) Locates from Inventory

Once a locate is accepted and appears in your inventory with available > 0, you can sell (credit) it.

Endpoint

POST /v1/api/accounts/locates/sell

Request Headers

Content-Type: application/json
TZ-API-KEY-ID: {API_KEY}
TZ-API-SECRET-KEY: {API_SECRET}

Request Body

{
  "account": "ACCOUNT123",
  "symbol": "AAPL",
  "quoteReqID": "Q1701532900000",
  "quantity": 500,
  "locateType": "Locate"
}

Request Parameters

Field	Type	Required	Description
account	string	Yes	The trading account ID
symbol	string	Yes	Stock symbol from inventory
quoteReqID	string	Yes	New unique quote request ID
quantity	integer	Yes	Number of shares to sell (must be ≤ available)
locateType	string	Yes	String value of locate type: "Unknown", "Locate", "IntraDay", "PreBorrow", or "SingleUse"

Important Notes:

• The quoteReqID must be generated fresh at the time of the sell request (not reused from inventory)
• The quantity must not exceed the available quantity in inventory
• After selling, the locate will appear in history and can be canceled before it's filled
• The locateType field is required and must match the type of locate in your inventory

Locate Type Values

Value	Description
Locate	Standard locate (most common)
IntraDay	Intraday locate valid only for the current trading session
PreBorrow	Pre-borrowed shares reserved in advance
SingleUse	Single-use locate that expires after one use
Unknown	Unknown or unspecified locate type

Example

curl -X POST "https://webapi-dev.tradezero.co/v1/api/accounts/locates/sell" \
  -H "TZ-API-KEY-ID: YOUR_API_KEY" \
  -H "TZ-API-SECRET-KEY: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "ACCOUNT123",
    "symbol": "AAPL",
    "quoteReqID": "Q1701532900000",
    "quantity": 500,
    "locateType": "Locate"
  }'

---

5. Cancel a Sold Locate

If you've sold (credited) a locate but it hasn't been filled yet, you can cancel it.

Endpoint

DELETE /v1/api/accounts/locates/cancel/accounts/{accountId}/quoteReqID/{quoteReqID}

Request Headers

TZ-API-KEY-ID: {API_KEY}
TZ-API-SECRET-KEY: {API_SECRET}

Path Parameters

Parameter	Type	Required	Description
accountId	string	Yes	The trading account ID
quoteReqID	string	Yes	Quote request ID from the sell operation

Response

Upon successful cancellation, the locate status will change to Canceled (52) and shares may return to inventory.

Example

curl -X DELETE "https://webapi-dev.tradezero.co/v1/api/accounts/locates/cancel/accounts/ACCOUNT123/quoteReqID/Q1701532900000" \
  -H "TZ-API-KEY-ID: YOUR_API_KEY" \
  -H "TZ-API-SECRET-KEY: YOUR_API_SECRET"

---

Complete Workflow Example

Scenario: Locate 1000 shares of TSLA, accept the quote, sell 500 shares, then cancel

Step 1: Request a locate

curl -X POST "https://webapi-dev.tradezero.co/v1/api/accounts/locates/quote" \
  -H "TZ-API-KEY-ID: YOUR_API_KEY" \
  -H "TZ-API-SECRET-KEY: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "ACCOUNT123",
    "symbol": "TSLA",
    "quantity": 1000,
    "quoteReqID": "Q1701532800000"
  }'

Step 2: Check status (poll until status = 65)

curl -X GET "https://webapi-dev.tradezero.co/v1/api/accounts/ACCOUNT123/locates/history" \
  -H "TZ-API-KEY-ID: YOUR_API_KEY" \
  -H "TZ-API-SECRET-KEY: YOUR_API_SECRET"

Response shows:

{
  "locateHistory": [
    {
      "accountId": "ACCOUNT123",
      "symbol": "TSLA",
      "locateShares": 1000,
      "filledShares": 0,
      "locateStatus": 65,
      "locateType": 1,
      "locatePrice": 0.003,
      "quoteReqId": "Q1701532800000",
      "preBorrow": false,
      "locateError": 0,
      "text": "",
      "createdDate": "2024-12-02T10:00:00Z",
      "updatedDate": "2024-12-02T10:00:00Z"
    }
  ]
}

Step 3: Accept the quote

curl -X POST "https://webapi-dev.tradezero.co/v1/api/accounts/locates/accept" \
  -H "TZ-API-KEY-ID: YOUR_API_KEY" \
  -H "TZ-API-SECRET-KEY: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "ACCOUNT123",
    "quoteReqID": "Q1701532800000"
  }'

Step 4: Verify it's in inventory

curl -X GET "https://webapi-dev.tradezero.co/v1/api/accounts/ACCOUNT123/locates/inventory" \
  -H "TZ-API-KEY-ID: YOUR_API_KEY" \
  -H "TZ-API-SECRET-KEY: YOUR_API_SECRET"

Response shows:

{
  "locateInventory": [
    {
      "accountId": "ACCOUNT123",
      "symbol": "TSLA",
      "available": 1000,
      "sold": 0,
      "toBeSold": 0,
      "unavailable": 0,
      "locateType": 1
    }
  ]
}

Step 5: Sell (credit) 500 shares

curl -X POST "https://webapi-dev.tradezero.co/v1/api/accounts/locates/sell" \
  -H "TZ-API-KEY-ID: YOUR_API_KEY" \
  -H "TZ-API-SECRET-KEY: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "ACCOUNT123",
    "symbol": "TSLA",
    "quoteReqID": "Q1701533000000",
    "quantity": 500,
    "locateType": "Locate"
  }'

Step 6: Cancel the sell before it's filled

curl -X DELETE "https://webapi-dev.tradezero.co/v1/api/accounts/locates/cancel/accounts/ACCOUNT123/quoteReqID/Q1701533000000" \
  -H "TZ-API-KEY-ID: YOUR_API_KEY" \
  -H "TZ-API-SECRET-KEY: YOUR_API_SECRET"

---

Best Practices

1. Quote Request IDs: Always generate unique quoteReqID values.

2. Polling: Poll the /v1/api/accounts/{accountId}/locates/history endpoint regularly (every 2-5 seconds) to check for status updates, or use /v1/api/accounts/{accountId}/locates/inventory to check your current inventory

3. Status Monitoring: Only attempt to accept quotes with status 65 (Offered)

4. Inventory Management: Verify available quantity in inventory before attempting to sell

5. Error Handling: Implement proper error handling for all API calls, especially:

   • Insufficient inventory
   • Expired quotes
   • Already filled/canceled quotes
   • Invalid quote request IDs

6. Cancellation Timing: Cancel operations should be performed before the locate is filled (status changes to 50)