Boomerang API

Look up warm-introduction paths to any account or contact from your own tools. One HTTP call returns who in your network (employees, executives, investors, board members, customer champions and partners) knows the target, how strong each relationship is, and the context behind it.

Quickstart

1. API access is included on the Team and Company plans. A workspace owner creates a key in Boomerang under Workspace → API keys (app.getboomerang.ai/rudy/workspace/api-keys). The key is shown once; store it securely.
2. Check the key:

   curl https://api.getboomerang.ai/v1/me \
     -H "Authorization: Bearer $BOOMERANG_API_KEY"

3. Look up warm paths into an account:

   curl https://api.getboomerang.ai/v1/relationships/account \
     -H "Authorization: Bearer $BOOMERANG_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"domain": "acme.com", "limit": 5}'

Base URL: https://api.getboomerang.ai/v1. All requests and responses are JSON. Field names are snake_case.

Authentication

Send your key as a bearer token:

Authorization: Bearer bmr_...

The X-API-Key: bmr_... header is also accepted. Keys are scoped to one workspace, can be revoked at any time from the same settings page, and only see that workspace's relationship graph.

You can pass your own X-Request-Id (up to 64 characters) to correlate calls; every lookup response echoes it, or a generated one, in the X-Request-Id header.

POST /v1/relationships/account

Warm paths into a company. Send one identifier; if you send several, the first one present in this order is used:

Optional, for both lookup endpoints:

{"domain": "acme.com", "limit": 5}

POST /v1/relationships/contact

Warm paths to a person. Send one identifier; resolution order:

{"linkedin_url": "https://www.linkedin.com/in/jane-doe", "company_domain": "acme.com"}

Lookups only cover accounts and contacts that exist in your Boomerang workspace (synced from your CRM or added in Boomerang). An unknown target returns matched: false with resolution: "NOT_IN_WORKSPACE" and is free.

Response format

Both lookup endpoints return the same envelope. summary is flat on purpose, so tools that map one value per column (like Clay) can read it directly, including the top five paths as top_path_N_* keys.

{
  "matched": true,
  "resolution": "RESOLVED",
  "credits_charged": 1,
  "credits_remaining": 2481,
  "credit_outcome": "CHARGED",
  "account": { "id": "8f0c…", "name": "Acme", "domain": "acme.com", "industry": "Software", "employee_size": "1001-5000" },
  "summary": {
    "path_count": 7,
    "returned_count": 5,
    "connector_count": 4,
    "best_strength": "STRONG",
    "best_strength_label": "Strong",
    "path_types": ["WORK_OVERLAP", "INVESTOR"],
    "top_path_1_connector_name": "Sam Lee",
    "top_path_1_connector_email": "sam@yourco.com",
    "top_path_1_connector_category": "EMPLOYEE",
    "top_path_1_types": "WORK_OVERLAP",
    "top_path_1_strength": "STRONG",
    "top_path_1_score": 0.86,
    "top_path_1_target_contact": "Jane Doe",
    "top_path_1_target_title": "VP Sales",
    "top_path_1_via": "Globex"
  },
  "paths": [
    {
      "relationship_id": "c1d2…",
      "connector": { "name": "Sam Lee", "email": "sam@yourco.com", "category": "EMPLOYEE" },
      "target_contact": { "name": "Jane Doe", "title": "VP Sales", "linkedin_url": "https://www.linkedin.com/in/jane-doe" },
      "target_account": { "name": "Acme", "domain": "acme.com" },
      "path_types": ["WORK_OVERLAP"],
      "strength": "STRONG",
      "strength_label": "Strong",
      "score": 0.86,
      "summary": "Worked together at Globex",
      "contact_currently_at_account": true,
      "context": {
        "overlap_companies": ["Globex"],
        "overlap_start": "2019-02",
        "overlap_end": "2022-06",
        "contact_current_title": "VP Sales",
        "contact_current_company": "Acme"
      },
      "intro_request": { "state": "REQUESTED", "requester_name": "Alex Kim", "created_at": "2026-09-30T14:02:11Z" },
      "updated_at": "2026-10-01T08:15:00Z"
    }
  ]
}

Values above are illustrative. Fields without a value are omitted.

GET /v1/me

Free. Confirms the key works and shows the plan and credit balance.

{
  "workspace_id": "…",
  "api_key_prefix": "bmr_ab12",
  "plan": "GROWTH_MONTHLY",
  "credits_included": 2500,
  "credits_used": 19,
  "credits_remaining": 2481,
  "unlimited": false,
  "allow_overage": false,
  "overage_cents_per_credit": 10,
  "period_start": "2026-10-01T00:00:00Z",
  "period_end": "2026-11-01T00:00:00Z",
  "endpoints": ["/v1/relationships/account", "/v1/relationships/contact", "/v1/usage"]
}

GET /v1/usage

Free. Current-period usage broken down by endpoint: calls, matched calls and credits charged.

Credits

• A lookup costs 1 credit only when it returns at least one relationship.
• Misses, targets not in your workspace, errors, and repeat lookups of the same target within 7 days are free.
• Team plans include 2,500 credits per billing period and Company plans 10,000; Enterprise is unlimited or custom. Your exact allowance is in GET /v1/me.
• When credits run out, lookups return 402 credits_exhausted unless overage is enabled for your workspace.

Rate limits

• 60 requests per minute per API key, plus a daily ceiling sized from your plan's allowance.
• 600 requests per minute per IP address, and 30 failed authentication attempts per minute per IP.
• Exceeding a limit returns 429 rate_limited with a Retry-After header (seconds).

Errors

Errors return a JSON body: {"error": "<code>", "message": "<details>"}.

Using the API from Clay

1. In Clay, add an HTTP API enrichment column.
2. Create an HTTP API (Headers) account with header Authorization = Bearer <your key>.
3. Method POST, URL https://api.getboomerang.ai/v1/relationships/account (or /contact), body for example {"domain": "/Company Domain"} or {"linkedin_url": "/LinkedIn Profile"}, mapping your table's columns.
4. Under fields to return, pick matched, summary.path_count, summary.best_strength_label and the summary.top_path_1_* fields you want as columns.

Rows with no relationship cost nothing, and re-running a table within 7 days doesn't charge again for the same targets.

Support

Questions or higher limits: support@getboomerang.ai. Boomerang is also available to AI assistants through our MCP server at https://mcp.getboomerang.ai/.