Skip to content
Contact

Lead fields

This page lists exactly what a lead event carries. The same fields are the columns of the Excel template. The machine-readable version is in the API reference.

The envelope

Section titled “The envelope”

Every request body has three members, as Standard Webhooks defines.

Member Meaning
type One of lead.new, lead.update, lead.withdraw, lead.delete
timestamp When the event happened, in ISO 8601 format. It stays the same on every retry
data The lead fields, using the exact template names

data.record_action must match type.

type data.record_action data.request_type When to send
lead.new new absent A first enquiry
lead.update update absent Any later change to the lead
lead.withdraw withdraw withdraw_consent or restriction The customer withdraws consent or asks to restrict processing
lead.delete delete erasure The customer asks for erasure

MarsX ignores extra top-level members of the envelope. Extra members inside data are not allowed.

Examples

Section titled “Examples”

These three events are one lead, in order: lead.new (revision 1), lead.update (revision 2) and lead.withdraw (revision 3). Each event after the first carries a higher source_revision and the time of its own change.

A new lead, revision 1:

lead.new
{
  "type": "lead.new",
  "timestamp": "2026-10-01T09:15:00+07:00",
  "data": {
    "partner_lead_id": "SRC-TEST-0001",
    "partner_customer_id": "SRC-CUST-TEST-0001",
    "source_revision": 1,
    "record_action": "new",
    "created_at": "2026-10-01T09:15:00+07:00",
    "updated_at": "2026-10-01T09:15:00+07:00",
    "customer_name": "Contoh Pelanggan",
    "phone": "+6280000000001",
    "email": "contoh.pelanggan@contoh.example",
    "model_interest": "Model A",
    "purchase_timeframe": "3 bulan ke depan",
    "test_drive_requested": "N",
    "enquiry_notes": "Ingin meminta penawaran untuk Model A.",
    "customer_province": "Jawa Barat",
    "customer_city": "Kota Bandung",
    "source_channel": "chat",
    "campaign": "campaign-test",
    "utm_source": "example",
    "utm_medium": "chat",
    "utm_campaign": "campaign-test",
    "session_id": "SESSION-TEST-0001",
    "consent_reference": "CONSENT-TEST-0001",
    "contact_consent": "yes",
    "consent_time": "2026-10-01T09:14:40+07:00",
    "notice_version": "NOTICE-TEST-1",
    "consent_purpose": "sales_follow_up",
    "ai_intent_label": "ingin_penawaran",
    "ai_summary": "Pelanggan meminta penawaran Model A."
  }
}

A lead from an advertising lead form says which platform it came from. It can also say that the customer confirmed the phone number:

lead.new from a Meta lead form
{
  "type": "lead.new",
  "timestamp": "2026-10-01T10:05:00+07:00",
  "data": {
    "partner_lead_id": "META-TEST-0003",
    "source_revision": 1,
    "record_action": "new",
    "created_at": "2026-10-01T10:04:30+07:00",
    "updated_at": "2026-10-01T10:05:00+07:00",
    "customer_name": "Contoh Pelanggan Dua",
    "phone": "+6280000000002",
    "phone_verified": true,
    "model_interest": "Model A",
    "purchase_timeframe": "Bulan ini",
    "customer_province": "Jawa Barat",
    "customer_city": "Kota Bandung",
    "source_channel": "meta_lead_form",
    "campaign": "campaign-test",
    "ad_id": "AD-TEST-0001",
    "ad_creative_id": "CREATIVE-TEST-0001",
    "consent_reference": "CONSENT-TEST-0003",
    "contact_consent": "yes",
    "consent_time": "2026-10-01T10:04:20+07:00",
    "notice_version": "NOTICE-TEST-1",
    "consent_purpose": "sales_follow_up"
  }
}

A change to that lead is revision 2. It carries the full current state, a higher source_revision and the time of the change:

lead.update
{
  "type": "lead.update",
  "timestamp": "2026-10-01T11:40:00+07:00",
  "data": {
    "partner_lead_id": "SRC-TEST-0001",
    "source_revision": 2,
    "record_action": "update",
    "created_at": "2026-10-01T09:15:00+07:00",
    "updated_at": "2026-10-01T11:40:00+07:00",
    "customer_name": "Contoh Pelanggan",
    "phone": "+6280000000001",
    "email": "contoh.pelanggan@contoh.example",
    "model_interest": "Model B",
    "purchase_timeframe": "1 bulan ke depan",
    "test_drive_requested": "Y",
    "customer_province": "Jawa Barat",
    "customer_city": "Kota Bandung",
    "source_channel": "chat",
    "contact_consent": "yes",
    "consent_reference": "CONSENT-TEST-0001",
    "consent_time": "2026-10-01T09:14:40+07:00",
    "notice_version": "NOTICE-TEST-1",
    "consent_purpose": "sales_follow_up"
  }
}

The withdrawal is revision 3. It carries identity and privacy request fields only, with its own source_revision and updated_at:

lead.withdraw
{
  "type": "lead.withdraw",
  "timestamp": "2026-10-04T15:00:00+07:00",
  "data": {
    "partner_lead_id": "SRC-TEST-0001",
    "source_revision": 3,
    "record_action": "withdraw",
    "created_at": "2026-10-01T09:15:00+07:00",
    "updated_at": "2026-10-04T15:00:00+07:00",
    "request_type": "withdraw_consent",
    "request_time": "2026-10-04T14:59:30+07:00",
    "request_reference": "PRIV-TEST-0001"
  }
}

The smallest valid lead.new leaves out the revision, the time of the change, the model and the city. MarsX uses revision 1 and created_at, and marks the lead incomplete:

lead.new, required fields only
{
  "type": "lead.new",
  "timestamp": "2026-10-01T10:30:00+07:00",
  "data": {
    "partner_lead_id": "SRC-TEST-0004",
    "record_action": "new",
    "created_at": "2026-10-01T10:29:30+07:00",
    "customer_name": "Contoh Pelanggan Tiga",
    "phone": "+6280000000003",
    "source_channel": "website_form",
    "contact_consent": "yes",
    "consent_time": "2026-10-01T10:29:20+07:00"
  }
}

Fields and required fields by action

Section titled “Fields and required fields by action”

These are the 36 columns of the Leads sheet in the template, with the same names. On the sheet, each name is the key in row 2, below a plain English title, and the columns are in the order a person fills them. The order below follows the contract. In JSON, leave out a field that is empty. MarsX treats an empty string as absent. For lead.update, a missing field means the field is now empty, because data holds the full current state and not a difference.

Every date-time carries an explicit offset from UTC, for example +07:00. MarsX stores the instant and shows it in WIB.

Key: R required. O optional. R* at least one of phone or email. D may be left out on lead.new, where MarsX applies a default, and is required on the other events. A accepted when empty: MarsX marks the lead incomplete and does not set it aside. no must be absent.

Section Field Format new or update withdraw or delete
A. Identity partner_lead_id Matches ^[A-Za-z0-9._-]{1,64}$. Never reused. For ad lead forms, the platform’s own lead ID R R
partner_customer_id Text. Your own customer ID O O
source_revision Whole number. Goes up with every change. On lead.new, a missing value means 1 D (R on update) R
record_action new, update, withdraw, delete R R
created_at ISO 8601 date-time with offset. When the customer made the enquiry R R
updated_at ISO 8601 date-time with offset. When this revision was made. On lead.new, a missing value means created_at D (R on update) R
B. Customer customer_name Text R no
phone Text starting +628 R* no
email An email address (RFC 5322 mailbox) R* no
phone_verified true if the customer confirmed phone, for example by a one-time code from the ad platform, and false if not. Leave it out, or send null, when unknown. In the template: a dropdown with Yes and No, and a blank cell for unknown O no
C. Interest model_interest A model from the template’s Lists sheet, or not_specified A no
purchase_timeframe Bulan ini, 1 bulan ke depan, 3 bulan ke depan, Belum tahu O no
test_drive_requested Y or N O no
enquiry_notes Text, at most 500 characters. The customer’s own request only O no
D. Location customer_province A province from the Lists sheet O no
customer_city Text. Kota or Kabupaten A no
preferred_dealer_code A dealer code from the MarsX dealer list, for example D0001 (see dropdown labels). Blank goes to triage. MarsX sets aside a code that is not on the list O no
E. Source source_channel One of meta_lead_form, tiktok_lead_form, google_lead_form, other_ad_lead_form, chat, website_form, marketplace, other R no
campaign, utm_source, utm_medium, utm_campaign Text O no
ad_click_id The ad platform’s click ID. For attribution only, never the lead ID O no
ad_id, ad_creative_id The platform’s ad and creative IDs O no
session_id Your own session reference O no
F. Consent contact_consent The customer agreed to be contacted. The only accepted value is yes. Any other value, or none, sets the event aside R no
consent_time ISO 8601 date-time with offset. When the customer agreed to be contacted R no
consent_reference A reference to your record of the actual consent, if you have one. Not a yes or no value O no
notice_version The privacy notice wording the customer saw, if you have it O no
consent_purpose For example sales_follow_up. Recorded for each purpose O no
G. AI values ai_intent_label Your derived label. Never decides access or routing O no
ai_summary Short. Stored apart from customer facts O no
H. Privacy request request_type withdraw_consent, erasure, restriction no R
request_time ISO 8601 date-time with offset no R
request_reference Matches ^[A-Za-z0-9._-]{1,64}$. Your reference for the request no R

What blocks a lead. A lead.new or lead.update is set aside only when it lacks partner_lead_id, record_action, created_at, customer_name, a phone or an email, source_channel, contact_consent with the value yes, or consent_time. A lead.update also needs source_revision and updated_at. A lead.withdraw or lead.delete needs its own source_revision and updated_at, and the privacy request fields. MarsX still applies a withdrawal or deletion whose revision is older than the stored one.

Defaults, for lead.new only. A missing source_revision means 1. A missing updated_at means the value of created_at. For a change, always send a higher source_revision and the time of the change in updated_at.

Accepted but marked incomplete. model_interest (the value not_specified is allowed) and customer_city are not required. MarsX accepts the lead and marks it incomplete. A lead with no model, no city and no preferred dealer goes to a MarsX triage queue instead of being set aside.

Optional, send them if you have them. consent_reference, notice_version and consent_purpose, and every other field marked O.

Notes

Section titled “Notes”
  • The Lists sheet of the template holds the model, province, source channel, consent purpose and preferred dealer values. MarsX maintains it and changes it by written notice with 30 days lead time.
  • A removal event carries no customer contact, interest or profile fields.
  • The File info sheet of the template does not apply to automatic sending. Each automatic sending event carries partner_lead_id and source_revision instead.
  • source_revision decides the order of events. Arrival order, webhook-id and webhook-timestamp do not. It must go up with every change to a lead and must never be reused for different content.

Never send

Section titled “Never send”
  • KTP or family-card numbers, income, financing documents, full chat transcripts, or AI guesses about affordability or location.
  • Status, assignment, follow-up, test drives, sales or SPK numbers. Dealers record these in MarsX Dashboard.