API Endpoints

The Leadflip REST API provides programmatic access to your leads and entities. All endpoints require API authentication via Bearer token.

Base URL

All API requests use the base URL:

https://www.leadflip.net/api

Include the Authorization: Bearer <your_api_key> header on every request.

Leads

Create a Lead (Intake)

POST /intake

The primary endpoint for creating leads. Accepts flat JSON or form-encoded payloads. Keys are normalized (case-insensitive, spaces/underscores/dashes ignored) and matched against field internal names or labels.

Example:

curl -X POST "https://www.leadflip.net/api/intake" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "entity": "solar_leads",
    "lead_name": "Jane Doe",
    "email": "jane@example.com",
    "status:stage": "New"
  }'

Response 200:

{
  "status": "success",
  "lead_id": "<uuid>",
  "created_at": "<iso8601>"
}

Bulk Create Leads

POST /leads/bulk

Create multiple leads in a single request.

Request:

{
  "entity": "solar_leads",
  "batch": [
    { "lead_name": "A", "email": "a@example.com" },
    { "lead_name": "B", "email": "b@example.com" }
  ],
  "source": "csv_import",
  "note": "Batch import"
}

Response 200:

{
  "status": "success",
  "created": [
    { "lead_id": "<uuid>", "email": "a@example.com" },
    { "lead_id": "<uuid>", "email": "b@example.com" }
  ]
}

Get a Lead

GET /leads/{id}

Retrieve a single lead by its UUID, including field data and recent events.

Response 200:

{
  "lead_id": "<uuid>",
  "entity": "<entity_id>",
  "status_step": "Qualified",
  "fields": {
    "lead_name": "Jane Doe",
    "email": "jane@example.com"
  },
  "events": [
    {
      "type": "lead_status_event",
      "message": "Lead moved to new status",
      "created_at": "2025-09-25T09:41:00+00:00"
    }
  ]
}

Update Lead Fields

PATCH /leads/{id}

Update specific fields on an existing lead.

Request:

{
  "fields": {
    "company": "Acme Inc.",
    "phone": "+1 555 222 3333"
  },
  "note": "Customer called back"
}

Response 200:

{
  "status": "success",
  "lead_id": "<uuid>",
  "updated_fields": ["company", "phone"]
}

Update Lead Status

PATCH /leads/{id}/status

Change a lead's pipeline status. This triggers any automations configured for the target status.

Request:

{
  "status_step": "Qualified"
}

Response 200:

{
  "status": "success",
  "lead_id": "<uuid>",
  "new_status": "Qualified"
}

Entities

List Entities

GET /entities

Returns all Entities in the authenticated account, including their field definitions.

Backward-compatible alias: GET /lead-objects

Response 200:

[
  {
    "id": "<uuid>",
    "label": "Solar Leads",
    "fields": [
      { "key": "lead_name", "type": "text", "required": true },
      { "key": "email", "type": "text", "required": false }
    ]
  }
]

Leads Endpoint Summary

Error Responses

The API returns standard HTTP status codes:

• 200 – Success
• 401 – Unauthorized (missing or invalid API key)
• 404 – Not Found
• 422 – Unprocessable Entity (validation errors)
• 500 – Internal Server Error

Validation error example (422):

{
  "status": "error",
  "message": "Validation error",
  "errors": { "email": ["The email field is required."] }
}

Not found example (404):

{
  "status": "error",
  "message": "Lead not found"
}

Next Steps

• API Authentication – Generate API keys and use Bearer token authentication.