Skip to main content
GET
https://api.debtstack.ai
/
v1
/
bonds
/
resolve
Resolve Bond
curl --request GET \
  --url https://api.debtstack.ai/v1/bonds/resolve
{
  "data": {
    "query": "<string>",
    "matches": [
      {}
    ],
    "exact_match": true,
    "suggestions": [
      {}
    ]
  }
}

​
Overview

Resolve bond identifiers (CUSIP, ISIN) or free-text descriptions to structured bond data. Useful for looking up bonds by CUSIP or matching user queries to specific instruments.

​
Request

​
q
string
Free-text search query.Example: RIG 8% 2027
​
cusip
string
Exact CUSIP lookup.Example: 893830AK8
​
isin
string
Exact ISIN lookup.Example: US893830AK85
​
ticker
string
Filter by company ticker.Example: RIG
​
coupon
number
Filter by coupon rate (%).Example: 8.0
​
maturity_year
integer
Filter by maturity year.Example: 2027
​
match_mode
string
default:"fuzzy"
Match mode: exact or fuzzy
​
limit
integer
default:"5"
Maximum number of matches.

​
Response

​
data
object

​
Examples

​
Free-Text Query

curl "https://api.debtstack.ai/v1/bonds/resolve?q=RIG%208%25%202027" \
  -H "X-API-Key: ds_xxxxx"

​
Response

{
  "data": {
    "query": "RIG 8% 2027",
    "matches": [
      {
        "confidence": 0.95,
        "bond": {
          "id": "uuid-123",
          "name": "8.00% Senior Notes due 2027",
          "cusip": "893830AK8",
          "isin": "US893830AK85",
          "company_ticker": "RIG",
          "company_name": "Transocean Ltd.",
          "coupon_rate": 8.0,
          "maturity_date": "2027-02-01",
          "seniority": "senior_unsecured",
          "outstanding": 68810000000
        }
      }
    ],
    "exact_match": false,
    "suggestions": []
  }
}

​
CUSIP Lookup

curl "https://api.debtstack.ai/v1/bonds/resolve?cusip=893830AK8" \
  -H "X-API-Key: ds_xxxxx"
Response: 
{
  "data": {
    "query": "893830AK8",
    "matches": [
      {
        "confidence": 1.0,
        "bond": {
          "id": "uuid-123",
          "name": "8.00% Senior Notes due 2027",
          "cusip": "893830AK8",
          "isin": "US893830AK85",
          "company_ticker": "RIG",
          "company_name": "Transocean Ltd.",
          "coupon_rate": 8.0,
          "maturity_date": "2027-02-01",
          "seniority": "senior_unsecured",
          "issuer": {
            "name": "Transocean International Limited",
            "entity_type": "finco"
          },
          "guarantor_count": 5,
          "outstanding": 68810000000
        }
      }
    ],
    "exact_match": true
  }
}

​
Handling Fuzzy Matches

When the query is ambiguous, multiple matches may be returned: 
curl "https://api.debtstack.ai/v1/bonds/resolve?q=AAPL%205%25" \
  -H "X-API-Key: ds_xxxxx"
Response: 
{
  "data": {
    "query": "AAPL 5%",
    "matches": [
      {
        "confidence": 0.85,
        "bond": {
          "name": "4.65% Notes due 2046",
          "cusip": "037833CP8",
          "coupon_rate": 4.65,
          "maturity_date": "2046-02-23"
        }
      },
      {
        "confidence": 0.80,
        "bond": {
          "name": "4.50% Notes due 2036",
          "cusip": "037833CQ6",
          "coupon_rate": 4.50,
          "maturity_date": "2036-02-23"
        }
      }
    ],
    "exact_match": false,
    "suggestions": [
      "Be more specific with maturity year"
    ]
  }
}

​
Use Cases

​
Map User Input to CUSIP

def get_cusip(query):
    """Convert user query to CUSIP."""
    response = requests.get(
        f"{BASE_URL}/bonds/resolve",
        params={"q": query, "limit": 1},
        headers={"X-API-Key": API_KEY}
    )

    matches = response.json()["data"]["matches"]
    if matches and matches[0]["confidence"] > 0.8:
        return matches[0]["bond"]["cusip"]
    return None

# Usage
cusip = get_cusip("RIG 8% 2027")
print(cusip)  # "893830AK8"

​
Validate CUSIP

def validate_cusip(cusip):
    """Check if CUSIP exists in database."""
    response = requests.get(
        f"{BASE_URL}/bonds/resolve",
        params={"cusip": cusip},
        headers={"X-API-Key": API_KEY}
    )

    return response.json()["data"]["exact_match"]

# Usage
is_valid = validate_cusip("893830AK8")
print(is_valid)  # True