Criar Oportunidade

POST /external/v1/opportunities

Cria uma nova oportunidade/lead. Um contato e criado (ou casado por e-mail) e vinculado a oportunidade automaticamente. Se nenhum owner_user_id for fornecido, a oportunidade e atribuida automaticamente pelas regras de rodizio da sua conta.

Retry seguro

Envie um header Idempotency-Key para tornar retries seguros — uma requisicao repetida com a mesma chave repete a resposta original em vez de criar um duplicado.

Autenticacao

Requer permissao opportunities:write.

Corpo da Requisicao

Campo	Tipo	Obrigatorio	Descricao
name	string	Sim	Nome completo do lead (tambem usado como titulo da oportunidade)
title	string	Nao	Cargo/posicao do contato
company	string	Nao	Empresa
location	string	Nao	Localizacao
headline	string	Nao	Headline do contato
profile_url	string	Nao	URL do perfil (LinkedIn/etc.)
profile_picture	string	Nao	URL da foto de perfil
email	string	Nao	E-mail (usado para casar um contato existente)
phone	string	Nao	Telefone
score	number	Nao	Score do lead (padrao: 0)
notes	string	Nao	Notas adicionais
campaign_id	string	Nao	Associar a uma campanha
owner_user_id	string	Nao	Atribuir a um vendedor especifico
sector_id	string	Nao	Atribuir a um setor/time
pipeline_id	string	Nao	Pipeline alvo
stage_id	string	Nao	Etapa alvo
source	string	Nao	Origem do lead: linkedin, google_maps, list, paid_traffic, other (padrao: other)

Acoes opcionais

Disparam efeitos colaterais apos a oportunidade ser criada. Sao nao-bloqueantes — se uma falhar, a oportunidade ainda e criada e a falha e reportada no objeto actions da resposta.

Campo	Tipo	Obrigatorio	Descricao
activate_agent_id	string	Nao	Ativa um agente de IA WhatsApp no contato (inicia uma conversa WhatsApp e roda o workflow do agente). O contato precisa ter phone. Sobrescreve o agente de entrada configurado no pipeline (veja a nota abaixo).
agent_channel_account_id	string	Nao	De qual canal WhatsApp conectado enviar. So necessario se a conta tiver mais de um canal WhatsApp.
enroll_in_flow_id	string	Nao	Inscreve o contato em um email flow ativo
send_template_email_id	string	Nao	Envia um email de template avulso ao contato (o contato precisa ter email)
email_sender_id	string	Nao	Remetente para send_template_email_id (padrao: o sender default da conta)

Ativacao de agente e so WhatsApp

activate_agent_id suporta apenas agentes WhatsApp (agent_type = 'whatsapp'). Passar um agente LinkedIn/email/outro retorna activated: false com um erro explicativo em actions.agent. Agentes LinkedIn rodam via campanha (convite → aceite), nao por ativacao direta.

Agente de entrada do pipeline (default)

Um pipeline pode ter um agente de entrada padrao (Configuracoes da Pipeline → Geral). Quando definido, esse agente e ativado automaticamente para todo contato adicionado ao pipeline — inclusive via este endpoint, mesmo sem passar activate_agent_id. A precedencia e: activate_agent_id explicito > agente de entrada do pipeline > nenhum. Ou seja, so envie activate_agent_id quando quiser sobrescrever o default do pipeline.

O numero de WhatsApp de onde o agente envia e configurado no proprio agente (cada agente ativo e vinculado ao seu numero). Precedencia do canal: agent_channel_account_id explicito > numero configurado no agente > unico numero conectado da conta (automatico).

Requisicao

cURL

curl --request POST \
  --url "https://app.getraze.com/external/v1/opportunities" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: YOUR_API_KEY" \
  --data '{
    "name": "Jane Smith",
    "title": "CTO",
    "company": "Tech Corp",
    "email": "jane@company.com",
    "source": "paid_traffic",
    "score": 70,
    "pipeline_id": "pipe_01",
    "stage_id": "stg_new",
    "notes": "Inbound do Google Ads"
  }'

Node.js

const axios = require('axios');

const response = await axios.post(
  'https://app.getraze.com/external/v1/opportunities',
  {
    name: 'Jane Smith',
    title: 'CTO',
    company: 'Tech Corp',
    email: 'jane@company.com',
    source: 'paid_traffic',
    score: 70,
    pipeline_id: 'pipe_01',
    stage_id: 'stg_new',
    notes: 'Inbound do Google Ads'
  },
  {
    headers: {
      'X-API-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  }
);

console.log(response.data);

Python

import requests

response = requests.post(
    'https://app.getraze.com/external/v1/opportunities',
    headers={
        'X-API-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Jane Smith',
        'title': 'CTO',
        'company': 'Tech Corp',
        'email': 'jane@company.com',
        'source': 'paid_traffic',
        'score': 70,
        'pipeline_id': 'pipe_01',
        'stage_id': 'stg_new',
        'notes': 'Inbound do Google Ads'
    }
)

print(response.json())

Resposta

{
  "success": true,
  "data": {
    "id": "opp_xyz789abc123",
    "title": "Jane Smith",
    "score": 70,
    "source": "paid_traffic",
    "notes": "Inbound do Google Ads",
    "pipeline_id": "pipe_01",
    "stage_id": "stg_new",
    "campaign_id": null,
    "owner_user_id": "usr_123",
    "contact_id": "cnt_new001",
    "contact_name": "Jane Smith",
    "contact_email": "jane@company.com",
    "contact_phone": null,
    "contact_company": "Tech Corp",
    "contact_title": "CTO",
    "campaign_name": null,
    "owner_user_name": "Maria Silva",
    "owner_user_email": "maria@acme.com",
    "created_at": "2026-01-25T09:00:00Z",
    "updated_at": "2026-01-25T09:00:00Z"
  }
}

Com acoes opcionais

Quando voce passa activate_agent_id, enroll_in_flow_id e/ou send_template_email_id, a resposta inclui um objeto actions reportando o resultado de cada uma (a oportunidade e criada de qualquer forma):

{
  "success": true,
  "data": { "id": "opp_xyz789abc123", "...": "..." },
  "actions": {
    "agent": { "activated": true, "conversation_id": "conv_55", "workflow_started": true },
    "flow":  { "enrolled": true, "enrollment_id": "enr_12", "status": "active" },
    "email": { "sent": true, "email_id": "re_abc123" }
  }
}

Em caso de falha, cada acao reporta seu proprio erro sem derrubar a requisicao, ex.:

"actions": {
  "agent": { "activated": false, "error": "Contact has no phone number for WhatsApp" }
}

Erros

Status	Codigo	Descricao
400	VALIDATION_ERROR	name ausente, ou campaign_id nao pertence a sua conta

Acoes opcionais nunca produzem erro de topo — reportam sucesso/falha dentro de actions.