CRM / Contacts API 🟡 BETA

Contact, account, lead, opportunity, and deal management with full pipeline visibility

Base URL

/api/crm

Authentication

All endpoints require a valid session token via Authorization: Bearer <token> header.

Contacts

List Contacts

GET /api/crm/contacts

Returns all contacts with optional filtering.

Response:

{
  "contacts": [
    {
      "id": "contact_001",
      "name": "João Silva",
      "email": "joao@example.com",
      "phone": "+5511999999999",
      "company": "Acme Corp",
      "account_id": "acc_001",
      "role": "CTO",
      "tags": ["vip", "enterprise"],
      "created_at": "2026-01-15T10:00:00Z",
      "last_activity_at": "2026-06-04T10:00:00Z"
    }
  ],
  "total": 150,
  "page": 1
}

Create Contact

POST /api/crm/contacts

Creates a new contact record.

Response:

{
  "id": "contact_002",
  "name": "Ana Costa",
  "email": "ana@startup.com",
  "phone": "+5511888888888",
  "company": "Startup Inc",
  "account_id": null,
  "role": "CEO",
  "tags": [],
  "created_at": "2026-06-04T10:00:00Z"
}

Get Contact

GET /api/crm/contacts/:id

Returns full details of a contact.

Response:

{
  "id": "contact_001",
  "name": "João Silva",
  "email": "joao@example.com",
  "phone": "+5511999999999",
  "company": "Acme Corp",
  "account_id": "acc_001",
  "role": "CTO",
  "tags": ["vip", "enterprise"],
  "custom_fields": {
    "linkedin": "https://linkedin.com/in/joaosilva",
    "budget_range": "50k-100k"
  },
  "activities": [
    {
      "id": "act_001",
      "type": "email",
      "subject": "Proposta comercial",
      "date": "2026-06-03T14:00:00Z"
    }
  ],
  "notes": "Decisor principal para ferramentas de TI",
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-06-04T10:00:00Z"
}

Update Contact

PUT /api/crm/contacts/:id

Updates an existing contact.

Response:

{
  "id": "contact_001",
  "name": "João Silva",
  "updated_at": "2026-06-04T10:15:00Z"
}

Delete Contact

DELETE /api/crm/contacts/:id

Deletes a contact record.

Response:

{
  "deleted": true,
  "id": "contact_002"
}

Accounts

List Accounts

GET /api/crm/accounts

Returns all accounts.

Response:

{
  "accounts": [
    {
      "id": "acc_001",
      "name": "Acme Corp",
      "industry": "Technology",
      "size": "enterprise",
      "website": "https://acme.com",
      "revenue": 5000000,
      "contacts_count": 12,
      "active_deals": 3,
      "created_at": "2026-01-10T10:00:00Z"
    }
  ],
  "total": 45
}

Create Account

POST /api/crm/accounts

Creates a new account.

Response:

{
  "id": "acc_002",
  "name": "Startup Inc",
  "industry": "SaaS",
  "size": "startup",
  "website": "https://startup.com",
  "created_at": "2026-06-04T10:00:00Z"
}

Get Account

GET /api/crm/accounts/:id

Returns account details including linked contacts and deals.

Response:

{
  "id": "acc_001",
  "name": "Acme Corp",
  "industry": "Technology",
  "size": "enterprise",
  "website": "https://acme.com",
  "revenue": 5000000,
  "contacts": [
    { "id": "contact_001", "name": "João Silva", "role": "CTO" },
    { "id": "contact_003", "name": "Maria Lima", "role": "VP Sales" }
  ],
  "deals": [
    { "id": "deal_001", "name": "Enterprise License", "value": 120000, "stage": "proposal" }
  ],
  "total_deal_value": 120000,
  "created_at": "2026-01-10T10:00:00Z"
}

Delete Account

DELETE /api/crm/accounts/:id

Deletes an account. Contacts are unlinked, not deleted.

Response:

{
  "deleted": true,
  "id": "acc_002",
  "unlinked_contacts": 3
}

Leads

List Leads

GET /api/crm/leads

Returns all leads with optional filtering.

Response:

{
  "leads": [
    {
      "id": "lead_001",
      "name": "Pedro Almeida",
      "email": "pedro@enterprise.com",
      "company": "Enterprise Ltd",
      "stage": "qualified",
      "source": "website",
      "score": 85,
      "owner": {
        "id": "agent_001",
        "name": "Maria Santos"
      },
      "estimated_value": 50000,
      "created_at": "2026-06-01T10:00:00Z",
      "last_activity_at": "2026-06-03T14:00:00Z"
    }
  ],
  "total": 32
}

Create Lead

POST /api/crm/leads

Creates a new lead.

Response:

{
  "id": "lead_002",
  "name": "Fernanda Rocha",
  "company": "Tech Solutions",
  "stage": "new",
  "source": "campaign",
  "score": 45,
  "created_at": "2026-06-04T10:00:00Z"
}

Get Lead

GET /api/crm/leads/:id

Returns lead details.

Response:

{
  "id": "lead_001",
  "name": "Pedro Almeida",
  "email": "pedro@enterprise.com",
  "company": "Enterprise Ltd",
  "stage": "qualified",
  "source": "website",
  "score": 85,
  "owner": { "id": "agent_001", "name": "Maria Santos" },
  "estimated_value": 50000,
  "activities": [
    { "type": "form_submission", "date": "2026-06-01T10:00:00Z", "details": "Demo request" },
    { "type": "call", "date": "2026-06-02T14:00:00Z", "details": "Qualification call completed" }
  ],
  "score_history": [45, 60, 85],
  "created_at": "2026-06-01T10:00:00Z"
}

Update Lead

PUT /api/crm/leads/:id

Updates lead information.

Response:

{
  "id": "lead_001",
  "name": "Pedro Almeida",
  "updated_at": "2026-06-04T10:15:00Z"
}

Delete Lead

DELETE /api/crm/leads/:id

Deletes a lead.

Response:

{
  "deleted": true,
  "id": "lead_002"
}

Update Lead Stage

PUT /api/crm/leads/:id/stage

Moves a lead to a different pipeline stage.

Response:

{
  "id": "lead_001",
  "previous_stage": "qualified",
  "current_stage": "proposal",
  "moved_at": "2026-06-04T10:20:00Z"
}

Convert Lead

POST /api/crm/leads/:id/convert

Converts a lead into a contact, account, and/or opportunity.

Response:

{
  "lead_id": "lead_001",
  "converted": true,
  "contact_id": "contact_010",
  "account_id": "acc_010",
  "opportunity_id": "opp_010",
  "converted_at": "2026-06-04T10:30:00Z"
}

Opportunities

List Opportunities

GET /api/crm/opportunities

Returns all opportunities.

Response:

{
  "opportunities": [
    {
      "id": "opp_001",
      "name": "Enterprise License Acme",
      "value": 120000,
      "stage": "proposal",
      "probability": 70,
      "account_id": "acc_001",
      "account_name": "Acme Corp",
      "owner": { "id": "agent_001", "name": "Maria Santos" },
      "expected_close_date": "2026-07-15T00:00:00Z",
      "created_at": "2026-06-01T10:00:00Z"
    }
  ],
  "total": 18,
  "total_value": 850000,
  "weighted_value": 595000
}

Create Opportunity

POST /api/crm/opportunities

Creates a new opportunity.

Response:

{
  "id": "opp_002",
  "name": "SaaS Subscription Startup",
  "value": 24000,
  "stage": "qualification",
  "probability": 30,
  "expected_close_date": "2026-08-01T00:00:00Z",
  "created_at": "2026-06-04T10:00:00Z"
}

Get Opportunity

GET /api/crm/opportunities/:id

Returns opportunity details.

Response:

{
  "id": "opp_001",
  "name": "Enterprise License Acme",
  "value": 120000,
  "stage": "proposal",
  "probability": 70,
  "account": { "id": "acc_001", "name": "Acme Corp" },
  "owner": { "id": "agent_001", "name": "Maria Santos" },
  "expected_close_date": "2026-07-15T00:00:00Z",
  "contacts": [
    { "id": "contact_001", "name": "João Silva", "role": "Decision Maker" }
  ],
  "activities": [
    { "type": "meeting", "date": "2026-06-03T14:00:00Z", "summary": "Demo apresentada" }
  ],
  "stage_history": [
    { "stage": "qualification", "entered_at": "2026-06-01T10:00:00Z" },
    { "stage": "proposal", "entered_at": "2026-06-03T16:00:00Z" }
  ],
  "created_at": "2026-06-01T10:00:00Z"
}

Update Opportunity

PUT /api/crm/opportunities/:id

Updates opportunity details.

Response:

{
  "id": "opp_001",
  "value": 135000,
  "probability": 80,
  "updated_at": "2026-06-04T10:15:00Z"
}

Delete Opportunity

DELETE /api/crm/opportunities/:id

Deletes an opportunity.

Response:

{
  "deleted": true,
  "id": "opp_002"
}

Close Opportunity

POST /api/crm/opportunities/:id/close

Marks an opportunity as won or lost.

Response:

{
  "id": "opp_001",
  "stage": "won",
  "actual_value": 135000,
  "closed_at": "2026-06-04T10:30:00Z",
  "won": true,
  "cycle_days": 45
}

Deals

List Deals

GET /api/crm/deals

Returns all deals (closed-won opportunities with financial details).

Response:

{
  "deals": [
    {
      "id": "deal_001",
      "opportunity_id": "opp_001",
      "name": "Enterprise License Acme",
      "value": 135000,
      "status": "completed",
      "account_name": "Acme Corp",
      "closed_at": "2026-06-04T10:30:00Z",
      "payment_terms": "Net 30",
      "invoice_id": "INV-2026-001"
    }
  ],
  "total": 28,
  "total_value": 1250000
}

Create Deal

POST /api/crm/deals

Creates a new deal record.

Response:

{
  "id": "deal_002",
  "opportunity_id": "opp_002",
  "value": 24000,
  "status": "pending",
  "created_at": "2026-06-04T10:00:00Z"
}

Get Deal

GET /api/crm/deals/:id

Returns deal details.

Response:

{
  "id": "deal_001",
  "opportunity": {
    "id": "opp_001",
    "name": "Enterprise License Acme",
    "account_name": "Acme Corp"
  },
  "value": 135000,
  "status": "completed",
  "payment_terms": "Net 30",
  "invoice_id": "INV-2026-001",
  "closed_at": "2026-06-04T10:30:00Z"
}

Update Deal

PUT /api/crm/deals/:id

Updates deal details.

Response:

{
  "id": "deal_001",
  "value": 140000,
  "updated_at": "2026-06-04T10:15:00Z"
}

Delete Deal

DELETE /api/crm/deals/:id

Deletes a deal.

Response:

{
  "deleted": true,
  "id": "deal_002"
}

Activities

List Activities

GET /api/crm/activities

Returns all activities across CRM records.

Response:

{
  "activities": [
    {
      "id": "act_001",
      "type": "call",
      "subject": "Qualification call",
      "contact_id": "contact_001",
      "contact_name": "João Silva",
      "account_name": "Acme Corp",
      "owner_id": "agent_001",
      "duration_seconds": 900,
      "outcome": "interested",
      "scheduled_at": "2026-06-03T14:00:00Z",
      "completed_at": "2026-06-03T14:15:00Z"
    }
  ],
  "total": 89
}

Create Activity

POST /api/crm/activities

Creates a new activity.

Response:

{
  "id": "act_002",
  "type": "meeting",
  "subject": "Demo técnica",
  "contact_id": "contact_001",
  "scheduled_at": "2026-06-05T10:00:00Z",
  "created_at": "2026-06-04T10:00:00Z"
}

Pipeline

Get Pipeline Stages

GET /api/crm/pipeline/stages

Returns the configured pipeline stages.

Response:

{
  "stages": [
    { "id": "stage_001", "name": "qualification", "order": 1, "probability": 10, "color": "#6B7280" },
    { "id": "stage_002", "name": "needs_analysis", "order": 2, "probability": 25, "color": "#3B82F6" },
    { "id": "stage_003", "name": "proposal", "order": 3, "probability": 50, "color": "#8B5CF6" },
    { "id": "stage_004", "name": "negotiation", "order": 4, "probability": 75, "color": "#F59E0B" },
    { "id": "stage_005", "name": "closed_won", "order": 5, "probability": 100, "color": "#10B981" },
    { "id": "stage_006", "name": "closed_lost", "order": 6, "probability": 0, "color": "#EF4444" }
  ]
}

Statistics

Get CRM Statistics

GET /api/crm/stats

Returns aggregated CRM statistics.

Response:

{
  "period": "month",
  "contacts": {
    "total": 150,
    "new_this_period": 23,
    "by_source": {
      "website": 8,
      "referral": 10,
      "campaign": 5
    }
  },
  "leads": {
    "total": 32,
    "new_this_period": 12,
    "converted": 8,
    "conversion_rate": 0.25,
    "average_score": 65
  },
  "opportunities": {
    "total": 18,
    "total_value": 850000,
    "weighted_value": 595000,
    "won": 5,
    "won_value": 320000,
    "lost": 3,
    "lost_value": 95000,
    "win_rate": 0.625,
    "average_cycle_days": 42
  },
  "pipeline": {
    "by_stage": [
      { "stage": "qualification", "count": 5, "value": 175000 },
      { "stage": "proposal", "count": 6, "value": 420000 },
      { "stage": "negotiation", "count": 4, "value": 250000 }
    ]
  }
}

External Sync

List Sync Accounts

GET /api/crm/sync/accounts

Returns accounts configured for external system synchronization.

Response:

{
  "sync_accounts": [
    {
      "id": "sync_001",
      "provider": "salesforce",
      "name": "Salesforce Production",
      "status": "active",
      "last_sync_at": "2026-06-04T06:00:00Z",
      "records_synced": 1250,
      "error_count": 0
    }
  ]
}

Create Sync Account

POST /api/crm/sync/accounts

Creates a new external system sync configuration.

Response:

{
  "id": "sync_002",
  "provider": "hubspot",
  "name": "Hubspot CRM",
  "status": "active",
  "sync_direction": "bidirectional",
  "created_at": "2026-06-04T10:00:00Z"
}

Get Sync Account

GET /api/crm/sync/accounts/:id

Returns sync account details.

Response:

{
  "id": "sync_001",
  "provider": "salesforce",
  "name": "Salesforce Production",
  "status": "active",
  "sync_direction": "bidirectional",
  "last_sync_at": "2026-06-04T06:00:00Z",
  "next_sync_at": "2026-06-04T12:00:00Z",
  "records_synced": 1250,
  "error_count": 0,
  "field_mappings": {
    "email": "Email",
    "phone": "Phone",
    "company": "Account.Name"
  }
}

Delete Sync Account

DELETE /api/crm/sync/accounts/:id

Deletes a sync account and stops synchronization.

Response:

{
  "deleted": true,
  "id": "sync_002",
  "pending_syncs_cancelled": 3
}

Trigger Manual Sync

POST /api/crm/sync/accounts/:id/sync

Triggers an immediate sync for the specified account.

Response:

{
  "sync_id": "sync_run_001",
  "sync_account_id": "sync_001",
  "status": "started",
  "direction": "bidirectional",
  "started_at": "2026-06-04T10:00:00Z",
  "estimated_duration_seconds": 120
}

See Also

• Contacts API — user management and authentication
• Sheets API — spreadsheet operations for bulk data
• Tasks API — task management linked to CRM activities
• Analytics API — reporting and dashboards