Lead Submission API

Overview

The Lead Submission API enables external systems to submit structured lead data to Marquatica. This includes contact details, product interest, build specifications, and marketing metadata. Leads are saved to the database and optionally forwarded to your brand's CRM webhook.

Endpoint

POST /lead-submission

Authentication

Use the X-API-Token header to authenticate requests:

X-API-Token: your_api_token_here

Request Body

The request body is JSON with the following top-level structure:

{
  "brand": "your_brand",
  "contact_category": "boat_build",
  "send_to_dealer": false,
  "contact": { ... },
  "product": { ... },
  "boat_build": { ... },
  "custom_fields": { ... }
}

Required Fields

The following three fields are required:

brand — Brand slug identifier
contact.contact_email — Valid email address
contact_category — Lead category type

Contact Category Values

The following contact category values are supported:

boat_build
request_quote
contact_dealer
trade_in
test_ride

Other values are accepted but may not receive enhanced handling.

Field Reference

Top-Level Fields

Field	Type	Required	Description
brand	string	Yes	Brand slug (e.g., "your_brand")
contact_category	string	Yes	Lead type category
send_to_dealer	boolean	No	Whether to forward to dealer. Default: false
contact	object	Yes	Contact information (see below)
product	object	No	Product interest details
boat_build	object	No	Boat build/configuration details
custom_fields	object	No	Freeform key-value pairs for UTM params, etc.

Contact Object Fields

Field	Type	Required	Description
contact_email	string	Yes	Email address (validated)
contact_first_name	string	No	First name
contact_last_name	string	No	Last name
contact_phone	string	No	Phone number
contact_external_id	string	No	External system ID
contact_source	string	No	Lead source
contact_country_code	string	No	Two-letter country code
contact_zip_code	string	No	ZIP/postal code
contact_address1	string	No	Street address line 1
contact_address2	string	No	Street address line 2
contact_city	string	No	City
contact_state	string	No	State/province
contact_country	string	No	Country name
contact_latitude	number	No	Latitude coordinate
contact_longitude	number	No	Longitude coordinate
contact_email_optin	boolean	No	Email opt-in status. Default: true
contact_phone_optin	boolean	No	Phone opt-in status. Default: true

Product Object Fields

Field	Type	Required	Description
product_name	string	No	Product/model name
product_year	string	No	Product year

Boat Build Object Fields

Field	Type	Required	Description
boat_build_id	string	No	Build configuration ID
boat_build_unique_id	string	No	Unique build UUID
boat_build_url	string	No	URL to the build configuration
boat_build_image_url	string	No	URL to build image
boat_build_notes	string	No	Notes about the build

Example Request

Here's a complete example using curl:

curl -X POST https://api.marquatica.com/lead-submission \
  -H "Content-Type: application/json" \
  -H "X-API-Token: your_api_token_here" \
  -d '{
    "brand": "your_brand",
    "contact_category": "boat_build",
    "send_to_dealer": false,
    "contact": {
      "contact_external_id": "user_78910",
      "contact_first_name": "Jane",
      "contact_last_name": "Smith",
      "contact_email": "jane.smith@example.com",
      "contact_source": "google",
      "contact_phone": "555-987-6543",
      "contact_country_code": "US",
      "contact_zip_code": "90210",
      "contact_address1": "123 Marina Blvd",
      "contact_address2": "Unit 5",
      "contact_city": "San Diego",
      "contact_state": "CA",
      "contact_country": "USA",
      "contact_latitude": 32.7157,
      "contact_longitude": -117.1611,
      "contact_email_optin": true,
      "contact_phone_optin": true
    },
    "product": {
      "product_name": "Model XYZ",
      "product_year": "2025"
    },
    "boat_build": {
      "boat_build_id": "B12345",
      "boat_build_unique_id": "550e8400-e29b-41d4-a716-446655440000",
      "boat_build_url": "https://example.com/boats/B12345",
      "boat_build_image_url": "https://example.com/images/B12345.jpg",
      "boat_build_notes": "Customer saved this boat"
    },
    "custom_fields": {
      "purchase_timeframe": "3-6 Months",
      "utm_source": "google",
      "utm_campaign": "spring-launch",
      "comment": "Saw the ad on YouTube"
    }
  }'

Success Response

When No Webhook is Configured

If the brand does not have a CRM webhook configured, the lead is saved locally and returns:

{
  "status": "success",
  "message": "Lead saved successfully",
  "lead_id": 42,
  "webhook_forwarded": false,
  "version": "0.1.1"
}

When Webhook is Configured

If a CRM webhook is configured, the response comes directly from the webhook endpoint. Format may vary depending on your CRM system.

The response format depends on whether the brand has a CRM webhook configured. When a webhook is configured, the response is passed through from the CRM system.

Error Response

If the request fails validation, the API returns a 400 Bad Request with error details:

{
  "status": "error",
  "message": "Invalid submission",
  "errors": [
    {
      "field": "contact.contact_email",
      "message": "Email address is required"
    }
  ],
  "version": "0.1.1"
}

Previous Dealer Locator Next Warranty API