Lead Post Webhook API

Overview

The Lead Post Webhook API accepts one JSON lead per request. TECOBI uses the supplied contact data to create a lead or link the request to an existing lead, then applies supported metadata, assignment, appointment, and comments fields.

Before you begin: Request an active client API key from your TECOBI representative. Keep the key server-side and never expose it in browser JavaScript or a public repository.

Bulk arrays are not supported. Send each lead as a separate request.

Endpoint

POST /api/v4/webhooks/lead-post/
Content-Type: application/json
x-tecobi-api-key: <client-api-key>

Authentication

Include the active client’s API key in the x-tecobi-api-key request header.

Payload requirements

The request body must be a JSON object. At least one of these contact values must be present for TECOBI to create or link a CRM lead:

• phone_number
• phone
• customData.phone_number
• email
• customData.email

If no phone or email is supplied, the endpoint can still return 201 Created, but no CRM lead is created.

Unknown fields are retained in the raw webhook payload, but they do not affect lead creation unless they are listed in this reference.

Request examples

Minimal request

{
  "first_name": "Jane",
  "last_name": "Customer",
  "phone_number": "15551234567",
  "email": "jane@example.com",
  "classification": "Sales"
}

Complete request

{
  "lead_id": "abc-123",
  "service": 5579,
  "language_code": "en",
  "classification": "Sales",
  "first_name": "Jane",
  "last_name": "Customer",
  "phone_number": "15551234567",
  "email": "jane@example.com",
  "company": "Acme Co",
  "address_1": "123 Main St",
  "address_2": "Suite 4",
  "city": "Denver",
  "state": "Colorado",
  "zip_code": "80202",
  "assigned_to": "salesperson@exampledealer.com",
  "sales_manager_email": "manager@exampledealer.com",
  "appointment_time": "2026-08-12T15:00:00-06:00",
  "appointment_notes": "Wants to test drive",
  "appointment_location": "Showroom",
  "comments": {
    "Vehicle": "F-150",
    "Budget": "$45k"
  }
}

cURL request

curl --request POST \
  --url 'https://<tecobi-api-origin>/api/v4/webhooks/lead-post/' \
  --header 'Content-Type: application/json' \
  --header 'x-tecobi-api-key: <client-api-key>' \
  --data '{
    "first_name": "Jane",
    "last_name": "Customer",
    "phone_number": "15551234567",
    "email": "jane@example.com",
    "classification": "Sales"
  }'

Use the API origin supplied with your TECOBI client credentials.

Field reference

Lead identity

Contact information

At least one phone or email field is required for a lead to be created or linked.

Lead metadata

Assignment and roles

Each role accepts the email of an active user on the client. Send it at the top level or inside customData with the same key. An unmatched email does not fail the request; TECOBI creates an internal warning note.

Address and company

Appointments

Appointment fields can be sent at the top level or inside customData with the same key.

Notes and comments

Comments are normalized as follows:

• Object values become key: value lines.
• Array values become one line per non-empty item.
• String values are retained as text.
• Pipe-and-colon strings such as Color: Red|Trim: XLT become separate key: value lines.

Nested custom data

customData must be a JSON object. It provides fallback values for selected fields. Unknown nested keys remain in the raw payload but are ignored during lead creation.

Supported keys are phone_number, email, first_name, last_name, Service, all assignment and role keys, all appointment keys, and inquiry_details.

Lead processing behavior

Phone leads

TECOBI removes common punctuation and normalizes US phone values toward +1 format. Leads are matched by client and normalized number. Existing matching leads are reactivated to an active, fresh status when applicable.

Email-only leads

When no phone is supplied, TECOBI attempts to match an existing client lead by normalized email and compatible first and last name. If no match is found, it creates a new web lead.

New-lead defaults

Responses

Success

HTTP/1.1 201 Created
Content-Type: application/json

{}

The success body is always an empty JSON object and does not include the created or matched lead ID.

Missing API key

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "message": "x-tecobi-api-key header is required."
}

Invalid API key

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "message": "x-tecobi-api-key is not valid."
}

Implementation notes

• A valid request can return 201 Created without creating a CRM lead when no phone or email is supplied.
• Unknown fields are stored in the raw webhook payload but ignored by lead creation.
• Invalid role emails and invalid appointment times create internal warnings instead of failing the request.
• Lead creation is attempted synchronously during the request.
• Send exactly one lead per request.