Leads API

Leads endpoints

Base URL: https://api.web.aivapad.io/api/external/v1

Use these endpoints to keep your lead pipeline updated in real time from websites, forms, and external tools.

Required scopes:

• leads:read for visibility and reporting operations
• leads:write for capture and lifecycle update operations

Lead response shape:

{
  "_id": "8a4f5f27-8db8-4343-8fb8-4cc7f9ef57f4",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "phone": "+1 (800) 123-4567",
  "source": "Landing Page",
  "status": "new",
  "score": 50,
  "lastContact": "2026-04-06T20:33:50.414Z",
  "notes": "Interested in enterprise onboarding",
  "tenant": "tenant_123",
  "createdBy": "api-token",
  "createdAt": "2026-04-06T20:33:50.414Z",
  "updatedAt": "2026-04-06T20:33:50.414Z"
}

1) List leads

GET /leads

curl -X GET "https://api.web.aivapad.io/api/external/v1/leads" \
  -H "Authorization: Bearer aiva_YOUR_TOKEN_HERE"

Successful response (200):

[
  {
    "_id": "8a4f5f27-8db8-4343-8fb8-4cc7f9ef57f4",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "status": "new",
    "score": 50,
    "lastContact": "2026-04-06T20:33:50.414Z",
    "source": "Landing Page",
    "createdAt": "2026-04-06T20:33:50.414Z",
    "updatedAt": "2026-04-06T20:33:50.414Z"
  }
]

2) Create a lead

POST /leads

Minimum validation:

• name is required
• at least one of email or phone is required

curl -X POST "https://api.web.aivapad.io/api/external/v1/leads" \
  -H "Authorization: Bearer aiva_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+1 (800) 123-4567",
    "source": "Landing Page",
    "status": "new",
    "score": 80,
    "notes": "Requested a pricing callback"
  }'

Successful response (201): full created lead object.

Validation error (400) example:

{
  "success": false,
  "error": "Nome é obrigatório. Email ou Telefone também são necessários."
}

3) Update lead status

PUT /leads/:id/status

Use this endpoint for fast stage progression in your sales flow.

curl -X PUT "https://api.web.aivapad.io/api/external/v1/leads/8a4f5f27-8db8-4343-8fb8-4cc7f9ef57f4/status" \
  -H "Authorization: Bearer aiva_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "qualified"
  }'

Successful response (200): full updated lead object.

4) Update a lead (full or partial fields)

PUT /leads/:id

Use this endpoint when you need to update multiple lead fields in a single request.

curl -X PUT "https://api.web.aivapad.io/api/external/v1/leads/8a4f5f27-8db8-4343-8fb8-4cc7f9ef57f4" \
  -H "Authorization: Bearer aiva_YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane.smith@example.com",
    "phone": "+1 (800) 123-4567",
    "source": "Partner Referral",
    "status": "proposal",
    "score": 92,
    "notes": "Decision expected this week"
  }'

Successful response (200): full updated lead object.

5) Delete a lead

DELETE /leads/:id

curl -X DELETE "https://api.web.aivapad.io/api/external/v1/leads/8a4f5f27-8db8-4343-8fb8-4cc7f9ef57f4" \
  -H "Authorization: Bearer aiva_YOUR_TOKEN_HERE"

Successful response (200):

{
  "success": true
}

Error reference

Common errors across leads endpoints:

• 403 Forbidden:
  • token missing/invalid/expired
  • token permission does not include required access
  • token is not mapped to an active account context
• 404 Not Found: lead ID does not exist in your tenant
• 400 Bad Request: invalid payload or missing required fields
• 500 Internal Server Error: unexpected server-side failure (primarily on list endpoint)