Detect Competitors

Detect Deal Competitors

curl --request POST \
  --url https://api.example.com/deals/{deal_id}/competitors/detect \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "force_refresh": false
}
'

import requests

url = "https://api.example.com/deals/{deal_id}/competitors/detect"

payload = { "force_refresh": False }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({force_refresh: false})
};

fetch('https://api.example.com/deals/{deal_id}/competitors/detect', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/deals/{deal_id}/competitors/detect",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'force_refresh' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/deals/{deal_id}/competitors/detect"

	payload := strings.NewReader("{\n  \"force_refresh\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/deals/{deal_id}/competitors/detect")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"force_refresh\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/deals/{deal_id}/competitors/detect")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"force_refresh\": false\n}"

response = http.request(request)
puts response.read_body

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

POST

deals

{deal_id}

competitors

detect

Detect Deal Competitors

curl --request POST \
  --url https://api.example.com/deals/{deal_id}/competitors/detect \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "force_refresh": false
}
'

import requests

url = "https://api.example.com/deals/{deal_id}/competitors/detect"

payload = { "force_refresh": False }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({force_refresh: false})
};

fetch('https://api.example.com/deals/{deal_id}/competitors/detect', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/deals/{deal_id}/competitors/detect",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'force_refresh' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/deals/{deal_id}/competitors/detect"

	payload := strings.NewReader("{\n  \"force_refresh\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/deals/{deal_id}/competitors/detect")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"force_refresh\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/deals/{deal_id}/competitors/detect")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"force_refresh\": false\n}"

response = http.request(request)
puts response.read_body

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Gated by the ai.deal_competitors config feature flag — a 403 names the flag when disabled. This is a separate flag from the ai.competitive_intelligence flag that gates the full brief endpoints below. The cheap sibling of the full brief — just names, no analysis. Requires the deal to have a linked account with a non-empty name. Runs a 4-step cascade (Perplexity → Exa fallback if fewer than 3 hits → LLM merge/dedup → pure LLM inference if nothing was found) and replaces the deal’s deal_competitors rows with the result.

Auth

Requires a CRM manage scope and an active organization on the token. Any *:manage scope qualifies — in practice contacts:manage, deals:manage, companies:manage, or activities:manage.

Response

Field	Type	Description
`success`	`boolean`
`skipped`	`boolean`	`true` if existing competitors were returned without re-running detection (when `force_refresh` is `false` and competitors already exist).
`competitors`	`string[]`	Competitor names.
`source`	`string \| null`	`perplexity` \| `exa` \| `inference`.
`count`	`integer`

Errors

Status	Cause
`400`	Deal has no linked account, or the account has no name.
`403`	`ai.deal_competitors` feature disabled.
`404`	Deal not found.
`502`	The entire detection cascade returned nothing (no API keys configured, or all providers failed).

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

deal_id

string

required

The deal's id.

Body

application/json

force_refresh

boolean

default:false

Re-run detection even if competitors are already recorded on the deal.

Response

Successful Response

Contacts

Deals

Accounts

Activities

Tags

Files

Folders

Notifications

Reports

PATs

Integrations

AI

Analytics Assistant

Feedback

Customer Intelligence

Outreach

AnyCard

AnyCard Events

AnyCard Share Links

Public Media

Account Readiness

Service Health

Auth

Response

Errors

Authorizations

Path Parameters

Body

Response

​Auth

​Response

​Errors

Authorizations

Path Parameters

Body

Response

Auth

Response

Errors