Skip to main content
POST
/
api
/
v2
/
competitor
/
create
Create Competitor
curl --request POST \
  --url https://app.octavehq.com/api/v2/competitor/create \
  --header 'Content-Type: application/json' \
  --header 'api_key: <api-key>' \
  --data '
{
  "name": "Salesforce",
  "internalName": "SFDC - The CRM Giant",
  "description": "Leading CRM platform with strong enterprise presence",
  "howTheyPosition": [
    "Positions as the all-in-one CRM for enterprises.",
    "Frames AI as the core differentiator across every product line."
  ],
  "ourKeyDifferentiators": [
    "Native event-driven sync with Postgres CDC.",
    "Built-in SOC2 audit reporting at no extra cost."
  ],
  "competitorStrengths": [
    "Market leader",
    "Strong brand recognition",
    "Enterprise customer base"
  ],
  "competitorWeaknesses": [
    "Complex implementation",
    "High cost",
    "Poor customer support"
  ],
  "reasonsWeWin": [
    "Better pricing",
    "Easier implementation",
    "Superior customer support"
  ],
  "reasonsWeLose": [
    "Existing Salesforce-heavy stack with deep org-wide adoption.",
    "Procurement preference for the incumbent vendor."
  ],
  "customFields": [
    {
      "title": "<string>",
      "value": [
        "<string>"
      ]
    }
  ],
  "primaryOfferingOId": "o_123456",
  "linkingStrategy": {
    "mode": "ALL"
  }
}
'
{
  "_metadata": {
    "requestId": "requestId",
    "timestamp": "2021-01-01T00:00:00.000Z",
    "usage": 0,
    "message": "message"
  },
  "data": {
    "oId": "<string>",
    "createdAt": "<string>",
    "updatedAt": "<string>",
    "name": "<string>",
    "internalName": "<string>",
    "description": "<string>",
    "deletedAt": "<string>",
    "archivedAt": "<string>",
    "active": true,
    "data": {
      "howTheyPosition": [
        "<string>"
      ],
      "ourKeyDifferentiators": [
        "<string>"
      ],
      "competitorStrengths": [
        "<string>"
      ],
      "competitorWeaknesses": [
        "<string>"
      ],
      "reasonsWeWin": [
        "<string>"
      ],
      "reasonsWeLose": [
        "<string>"
      ],
      "customFields": [
        {
          "title": "<string>",
          "value": [
            "<string>"
          ]
        }
      ]
    },
    "user": {
      "oId": "<string>",
      "firstName": "John",
      "lastName": "Doe"
    },
    "workspace": {
      "oId": "<string>"
    }
  }
}

Authorizations

api_key
string
header
required

Body

application/json

Competitor creation input

name
string
required

The external name of the competitor

Minimum string length: 1
Example:

"Salesforce"

internalName
string

The internal name of the competitor

Example:

"SFDC - The CRM Giant"

description
string

A description of the competitor

Example:

"Leading CRM platform with strong enterprise presence"

howTheyPosition
string[]

How the competitor positions themselves: their narrative, messaging, and market story — the pitch they take to market.

Example:
[
"Positions as the all-in-one CRM for enterprises.",
"Frames AI as the core differentiator across every product line."
]
ourKeyDifferentiators
string[]

Concrete, observable, tactical points of differentiation we lead with against this competitor.

Example:
[
"Native event-driven sync with Postgres CDC.",
"Built-in SOC2 audit reporting at no extra cost."
]
competitorStrengths
string[]

Where this competitor genuinely excels.

Example:
[
"Market leader",
"Strong brand recognition",
"Enterprise customer base"
]
competitorWeaknesses
string[]

Where this competitor falls short.

Example:
[
"Complex implementation",
"High cost",
"Poor customer support"
]
reasonsWeWin
string[]

Key reasons why customers choose your solution over this competitor

Example:
[
"Better pricing",
"Easier implementation",
"Superior customer support"
]
reasonsWeLose
string[]

The deal-level dynamics for why customers might choose them when both are evaluated.

Example:
[
"Existing Salesforce-heavy stack with deep org-wide adoption.",
"Procurement preference for the incumbent vendor."
]
customFields
object[]

Custom fields for additional competitor information

primaryOfferingOId
string

Primary Offering to use as context when creating competitors. If not provided, the primary company attached to the Workspace will be used.

Example:

"o_123456"

linkingStrategy
object

Strategy for linking this competitor to offerings (products/services)

Response

Competitor created successfully

_metadata
object
required
data
object
required