Leads

The leads endpoint allows you to create new leads in the system and list leads associated with your businesses. Each lead requires specific information about the customer, their location, and additional fields that vary based on the subcategory of the lead. To list leads, you'll need a business ID which you can obtain from the businesses endpoint.

POST/api/leads

Create a lead

Create a new lead in the system. The request requires both standard contact information and subcategory-specific fields.

Required Fields

  • Name
    website_code
    Type
    string
    Description

    The unique code of the website. Obtain this from the websites endpoint. Must be a valid code that exists in the websites table.

  • Name
    subcategory_id
    Type
    string
    Description

    ID of the subcategory this lead belongs to. Get this from the categories endpoint. Must be a valid ID that exists in the subcategories table.

  • Name
    postal_code
    Type
    string
    Description

    Postal code of the customer's address. Must be a valid Dutch postal code format (e.g., 1234AB).

  • Name
    country
    Type
    string
    Description

    Country of the customer's address. Maximum length: 255 characters.

  • Name
    city
    Type
    string
    Description

    City of the customer's address. Maximum length: 255 characters.

  • Name
    street
    Type
    string
    Description

    Street name of the customer's address. Maximum length: 255 characters.

  • Name
    street_number
    Type
    string
    Description

    House/building number of the customer's address. Maximum length: 8 characters.

  • Name
    preferred_date_of_execution
    Type
    string
    Description

    Customer's preferred date for execution. Must be a valid date in YYYY-MM-DD format and must be after today.

  • Name
    description
    Type
    string
    Description

    Additional description or notes for the lead. Maximum length: 1000 characters.

  • Name
    gender
    Type
    string
    Description

    Customer's gender. Must be a valid gender option.

  • Name
    first_name
    Type
    string
    Description

    Customer's first name. Required field.

  • Name
    last_name
    Type
    string
    Description

    Customer's last name. Required field.

  • Name
    email
    Type
    string
    Description

    Customer's email address. Must be a valid email format.

  • Name
    phone
    Type
    string
    Description

    Customer's phone number. Must be exactly 10 numeric digits.

  • Name
    accept_terms
    Type
    boolean
    Description

    Whether the customer has accepted the terms and conditions. Must be accepted (true).

  • Name
    subscribe_to_newsletter
    Type
    boolean
    Description

    Whether the customer wants to subscribe to the newsletter. Must be a boolean value.

  • Name
    fields
    Type
    object
    Description

    The fields object must contain all required fields for the specified subcategory. Use the fields endpoint to get the list of required fields for your subcategory. Required fields for this example include:

    • year_of_construction (required)
    • housing_insulation (required)
    • current_heating_system (required)
    • annual_gas_consumption (required)

Response Types

The API can return three different types of responses:

{
  "completed": true,
  "id": "d18323f00cdb4cb8a967b6f6a2a488",
  "message": "Lead created successfully"
}

Request

POST
/api/leads
curl https://app.offerteadviseur.nl/api/leads \
  -X POST \
  -H "Authorization: Bearer eyJ..." \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "website_code": "1cd440df63f796a1f69da652cd0209",
    "subcategory_id": "1",
    "postal_code": "1234AB",
    "country": "Netherlands",
    "city": "Amsterdam",
    "street": "Zonnestraat",
    "street_number": "123",
    "preferred_date_of_execution": "2024-03-01",
    "description": "Looking for solar panel installation",
    "gender": "M",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "0612345678",
    "accept_terms": true,
    "subscribe_to_newsletter": false,
    "fields": {
      'year_of_construction': 'Tussen 1970-2000',
      'housing_insulation': 'Mijn woning is niet geïsoleerd.',
      'current_heating_system': 'Radiatoren',
      'annual_gas_consumption': 204,
    }
  }'
GET/api/businesses/{business}/leads

List leads

Retrieve a list of leads for a specific business. You can use the business ID you obtained from the businesses endpoint.

Response

{
  "data": [
    {
      "id": 123456,
      "gender": "male",
      "first_name": "John",
      "last_name": "Smith",
      "email": "john.smith@example.com",
      "phone": "0612345678",
      "street_number": "42",
      "postal_code": "1234AB",
      "city": "Amsterdam",
      "description": "I would like to have my stairs renovated and possibly build a cabinet around it.",
      "preferred_date_of_execution": "2025-03-31T22:00:00.000000Z",
      "extra_info": null,
      "subcategory_form_data": [{
        "home_owner": "Ja, ik ben eigenaar"
      },{
        "quality": "Goede prijs-kwaliteitverhouding"
      }],
      "status": "approved",
      "created_at": "2025-01-28T08:02:47.000000Z",
      "website": {
        // ...
      },
      "subcategory": {
        // ...
      }
    }
  ],
  "links": {
    // ...
  },
}

Response Fields

  • Name
    data
    Type
    array
    Description

    Array of lead objects, each containing detailed information about a lead.

  • Name
    data[].id
    Type
    integer
    Description

    Unique identifier for the lead.

  • Name
    data[].gender
    Type
    string
    Description

    Gender of the lead contact person.

  • Name
    data[].first_name
    Type
    string
    Description

    First name of the lead contact person.

  • Name
    data[].last_name
    Type
    string
    Description

    Last name of the lead contact person.

  • Name
    data[].email
    Type
    string
    Description

    Email address of the lead contact person.

  • Name
    data[].phone
    Type
    string
    Description

    Phone number of the lead contact person.

  • Name
    data[].street_number
    Type
    string
    Description

    Street number of the lead's address.

  • Name
    data[].postal_code
    Type
    string
    Description

    Postal code of the lead's address.

  • Name
    data[].city
    Type
    string
    Description

    City of the lead's address.

  • Name
    data[].description
    Type
    string
    Description

    Detailed description of the lead's request.

  • Name
    data[].preferred_date_of_execution
    Type
    string
    Description

    Preferred date for executing the work, in ISO 8601 format.

  • Name
    data[].extra_info
    Type
    string|null
    Description

    Additional information about the lead, if any.

  • Name
    data[].subcategory_form_data
    Type
    array
    Description

    Array of objects containing form data specific to the subcategory.

  • Name
    data[].status
    Type
    string
    Description

    Current status of the lead (e.g., "approved", "new").

  • Name
    data[].created_at
    Type
    string
    Description

    Creation date of the lead in ISO 8601 format.

  • Name
    data[].website
    Type
    object
    Description

    Information about the website where the lead was created.

  • Name
    data[].subcategory
    Type
    object
    Description

    Detailed information about the subcategory, including available form fields.

  • Name
    links
    Type
    object
    Description

    Pagination links for navigating through the results.

  • Name
    meta
    Type
    object
    Description

    Metadata about the pagination, including current page and total results.

Request

GET
/api/businesses/{business}/leads
curl https://app.offerteadviseur.nl/api/businesses/123/leads \
  -H "Authorization: Bearer eyJ..." \
  -H "Accept: application/json"

Was this page helpful?