Creating leads

Overview

With the Flixer API you can send leads from your website straight into Flixer. A lead can contain:

Customer details - The customer’s contact information (required)
Work item details - A description of the requested work (required)
Address details - Where the job needs to be carried out (optional)

Address details are optional. This means you can also create leads that only contain name/email/phone, such as with Meta/Facebook Lead Ads and the CSV import. An address is only created when street, postalCode, and city are all provided; a partial address is ignored.

Endpoint

POST https://api.flixerpro.io/v1/api/leads

Required scope: leads:write

Request fields

Address (optional)

The full address is optional. If you want to attach an address, provide street, postalCode, and city together — otherwise the address is ignored and the lead gets addressId: null.

Field	Type	Required	Example
`street`	string	Conditional¹	`"Keizersgracht"`
`streetNumber`	string	No	`"123"`
`streetNumberAddition`	string	No	`"A"`
`postalCode`	string	Conditional¹	`"1015 CJ"`
`city`	string	Conditional¹	`"Amsterdam"`
`country`	string	No	`"Nederland"`

¹ Only required if you want to create an address: street, postalCode, and city are all three needed or none at all.

Customer (required)

Field	Type	Required	Example
`customerName`	string	Yes	`"Jan de Vries"`
`firstName`	string	No	`"Jan"`
`lastName`	string	No	`"de Vries"`
`email`	string	No	`"[email protected]"`
`phone`	string	No	`"+31612345678"`
`companyName`	string	No	`"De Vries B.V."`

If companyName is filled in, the customer is registered as a business customer.

Work item (required)

Field	Type	Required	Example
`title`	string	Yes	`"Lekkage badkamer"`
`description`	string	No	`"Waterdruppels op het plafond"`
`category`	string	No	`"Loodgieter"`
`priority`	enum	No	`"medium"`
`budgetQuote`	string	No	`"€500 - €1000"`
`notes`	string	No	`"Graag snel contact"`

Priority values: low, medium, high, urgent (default: medium)

Lead without an address

Do you only have name/email/phone (such as with Meta/Facebook Lead Ads or a CSV import)? Then simply leave out the address fields. The lead is created with addressId: null.

cURL

curl -X POST "https://api.flixerpro.io/v1/api/leads" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customerName": "Jan de Vries",
    "email": "[email protected]",
    "phone": "+31612345678",
    "title": "Lekkage badkamer"
  }'

Full example

curl -X POST "https://api.flixerpro.io/v1/api/leads" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "street": "Keizersgracht",
    "streetNumber": "123",
    "streetNumberAddition": "A",
    "postalCode": "1015 CJ",
    "city": "Amsterdam",
    "country": "Nederland",
    "customerName": "Jan de Vries",
    "firstName": "Jan",
    "lastName": "de Vries",
    "email": "[email protected]",
    "phone": "+31612345678",
    "title": "Lekkage badkamer",
    "description": "Klant meldt waterschade aan het plafond in de badkamer. Vermoedelijk komt het van de bovenverdieping.",
    "category": "Loodgieter",
    "priority": "high",
    "budgetQuote": "€500 - €1000",
    "notes": "Graag zo snel mogelijk contact opnemen"
  }'

async function createLead(formData) {
  const response = await fetch("https://api.flixerpro.io/v1/api/leads", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.FLIXER_API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      // Address
      street: formData.street,
      streetNumber: formData.streetNumber,
      postalCode: formData.postalCode,
      city: formData.city,
      // Customer
      customerName: `${formData.firstName} ${formData.lastName}`,
      firstName: formData.firstName,
      lastName: formData.lastName,
      email: formData.email,
      phone: formData.phone,
      // Work item
      title: formData.subject,
      description: formData.message,
      category: formData.category
    })
  });

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return response.json();
}

import requests
import os

def create_lead(form_data):
    response = requests.post(
        "https://api.flixerpro.io/v1/api/leads",
        headers={
            "X-API-Key": os.environ["FLIXER_API_KEY"],
            "Content-Type": "application/json"
        },
        json={
            # Address
            "street": form_data["street"],
            "streetNumber": form_data["street_number"],
            "postalCode": form_data["postal_code"],
            "city": form_data["city"],
            # Customer
            "customerName": f"{form_data['first_name']} {form_data['last_name']}",
            "firstName": form_data["first_name"],
            "lastName": form_data["last_name"],
            "email": form_data["email"],
            "phone": form_data["phone"],
            # Work item
            "title": form_data["subject"],
            "description": form_data["message"],
            "category": form_data.get("category")
        }
    )

    response.raise_for_status()
    return response.json()

Response

On success you receive the created lead:

{
  "id": "WKIabc123def456ghi789",
  "brandId": "BRDabc123...",
  "customerId": "CUSabc123...",
  "addressId": "ADRabc123...",
  "title": "Lekkage badkamer",
  "description": "Klant meldt waterschade aan het plafond...",
  "status": "request",
  "priority": "high",
  "source": "web",
  "receivedAt": "2026-03-27T10:30:00.000Z",
  "createdAt": "2026-03-27T10:30:00.000Z"
}

The response contains the full work item object. In addition to the fields above, fields such as category, budgetQuote, notes, estimatedCost, finalCost, tags, scheduledStart/scheduledEnd, updatedAt, createdBy, and updatedBy are also returned (empty/null if they do not apply). If no (complete) address was provided, addressId is null.

Store the id of the created lead if you want to look up its status later.

Error handling

HTTP Status	Meaning
`201 Created`	Lead created successfully
`400 Bad Request`	Validation error — a required field (`customerName`, `title`) is missing or a value does not meet the rules
`401 Unauthorized`	API key is missing or invalid
`403 Forbidden`	Key does not have the `leads:write` scope

The request is validated server-side. Missing required fields (customerName, title) or invalid values are rejected with a 400 Bad Request; the message field in the response describes what went wrong.

async function createLeadWithErrorHandling(formData) {
  try {
    const response = await fetch("https://api.flixerpro.io/v1/api/leads", {
      method: "POST",
      headers: {
        "X-API-Key": process.env.FLIXER_API_KEY,
        "Content-Type": "application/json"
      },
      body: JSON.stringify(formData)
    });

    if (response.status === 401) {
      console.error("Invalid API key");
      return { success: false, error: "auth_error" };
    }

    if (response.status === 403) {
      console.error("Key lacks the leads:write scope");
      return { success: false, error: "scope_error" };
    }

    if (response.status === 400) {
      const body = await response.json();
      console.error("Validation error:", body.message);
      return { success: false, error: "validation_error" };
    }

    if (!response.ok) {
      console.error("Unexpected error:", response.status);
      return { success: false, error: "server_error" };
    }

    const lead = await response.json();
    return { success: true, lead };
  } catch (error) {
    console.error("Network error:", error);
    return { success: false, error: "network_error" };
  }
}

See Error handling for all error codes.

Getting started

Guides

Reference

Overview

Endpoint

Request fields

Address (optional)

Customer (required)

Work item (required)

Lead without an address

Full example

Response

Error handling

​Overview

​Endpoint

​Request fields

​Address (optional)

​Customer (required)

​Work item (required)

​Lead without an address

​Full example

​Response

​Error handling

Overview

Endpoint

Request fields

Address (optional)

Customer (required)

Work item (required)

Lead without an address

Full example

Response

Error handling