Create Lead

Purpose

Creates a new lead in Sodtrack for a given service.

The lead is created with customer information, required qualifying questions (dynamic form field values tied to the service’s lead form), and optional provider assignment and dynamic forms (additional info). Address is optional only for in-store services; for non in-store services, a valid location input is required (see Address and coordinates in Business Rules).

When address is sent without coordinates, Sodtrack may attempt to geocode it automatically (when auto-geocoding is enabled for external integration). For services that are not in-store, the lead creation requires a valid location input: coordinates, address text, or zip code; otherwise the request fails with REQUIRES_ADDRESS_OR_ZIP_CODE (see Address and coordinates in Business Rules).

Provider assignment and dynamic form snapshots are applied after the lead is created; failures in those steps do not fail the request—the lead is still returned.

Field Definitions

🧍 Customer

🏠 Address

If coordinates are not provided but address.address is sent, Sodtrack may attempt to geocode the address automatically if its part of your active features.
If the service is not in-store and the request has no coordinates, no address text, and no zip code, the request fails with REQUIRES_ADDRESS_OR_ZIP_CODE.

📋 Lead context

🧩 Qualifying questions

Each fieldReference must correspond to a dynamic field of the lead form associated with the request’s service. Invalid or mismatched references cause the request to fail with INVALID_QUALIFYING_QUESTION_WITH_ID_REFERENCE.

📄 Dynamic forms (additional info)

👷 Provider assignment

Example Request (with address and provider assignment)

{
  "customer": {
    "name": "María",
    "lastName": "García",
    "phoneNumber": "+56912345678",
    "email": "maria.garcia@example.com",
    "reference": "CUST-EXT-001"
  },
  "address": {
    "address": "Av. Providencia 1234, Santiago",
    "extraInfo": "Depto 501",
    "coordinate": {
      "lat": -33.4372,
      "lng": -70.6506
    },
    "zipCode": "7500000"
  },
  "salesChannelId": 1,
  "serviceId": 42,
  "reference": "LEAD-EXT-200",
  "qualifyingQuestions": [
    {
      "fieldReference": "1",
      "value": "high"
    }
  ],
  "providerAssignment": {
    "type": "direct",
    "provider": {
      "type": "providerId",
      "value": 10
    }
  }
}

Example Request (with zip_code)

{
  "customer": {
    "name": "María",
    "lastName": "García",
    "phoneNumber": "+56912345678",
    "email": "maria.garcia@example.com",
    "reference": "CUST-EXT-001"
  },
  "address": {
    "zipCode": "7500000"
  },
  "salesChannelId": 1,
  "serviceId": 42,
  "reference": "LEAD-EXT-201",
  "qualifyingQuestions": [
    {
      "fieldReference": "1",
      "value": "high"
    }
  ]
}

Example Request (minimal)

{
  "customer": {
    "name": "Juan Pérez"
  },
  "salesChannelId": 1,
  "serviceId": 42,
  "qualifyingQuestions": [
    {
      "fieldReference": "1",
      "value": "high"
    }
  ]
}

Response Example

{
  "id": 1001,
  "customer_id": 502
}

Response Fields

Error Responses

Business Rules & Constraints

Service and sales channel

• serviceId must identify an existing Sodtrack service that has an associated lead form. Otherwise the request fails with INVALID_SERVICE.

• salesChannelId must identify an existing sales channel. Otherwise the request fails with INVALID_SALES_CHANNEL.

• For in-store services, Sodtrack uses the sales channel address and the request address can be omitted.

• For non in-store services, a valid location input is required: coordinates, address text, or zip code.

Address and coordinates

• When address is sent with coordinate****: The system validate those to be valid coordinates. Otherwise the request fails with INVALID_LATITUDE_OR_LONGITUDE.

• When address is sent with address (street) but no coordinates: Sodtrack may attempt to geocode the address automatically when enabled for external integration. If geocoding succeeds, coordinates are filled in; if it fails, they remain missing.

• When the service is not an in-store service: The lead creation step requires at least one valid location input: coordinates (address.coordinate), address text (address.address), or zip code (address.zip_code). If none of these are provided, the request fails with REQUIRES_ADDRESS_OR_ZIP_CODE.

Qualifying questions

• Each element in qualifyingQuestions must have a fieldReference that matches a dynamic field of the lead form associated with the request’s service.

• If a fieldReference does not exist or belongs to a different form, the request fails with INVALID_QUALIFYING_QUESTION_WITH_ID_REFERENCE (including the invalid reference or a message that the field is not associated with the service’s lead form).

• The array can be empty if the lead form has no required qualifying fields.

Provider assignment and dynamic forms

• Provider assignment and dynamic form snapshots are applied after the lead is created.

• Failures during provider assignment or dynamic form creation are logged but do not cause the endpoint to return an error; the response still returns the created lead (id and customer_id).

• For direct provider assignment, provider with type and value must be provided; for automatic, no provider object is needed.

Lead reference

• reference is an optional external identifier stored with the lead. This endpoint does not enforce uniqueness on reference.

Data and format

• All timestamps follow the ISO 8601 format (UTC) where applicable.

• Customer and address data are stored as provided; identification country should be ISO 3166-1 alpha-2 where applicable.