AutoUncle CoDriver

Push leads

POST /api/v1/leads sends one lead: a customer's inquiry about a car, a trade-in, a test drive or anything else. AutoUncle CoDriver reads it, finds or creates the customer and the opportunity, and starts following up.

The request

Required:

  • lead_source_id: an active lead source of type API in the organization (src_…).
  • email or phone: at least one way to reach the customer. Send email: null for a phone-only lead.
  • At least one more field: name, message, desired_vehicles, trade_in_vehicles, budget…

Send what you know as structured fields and the customer's own words in message. Every field is in the LeadCreateRequest schema.

{
  "lead_source_id": "src_019535d9-3df7-79fb-b466-fa907fa17f9e",
  "email": "anna@example.com",
  "phone": "+4512345678",
  "name": "Anna Jensen",
  "message": "Is the Golf still for sale? I'd like a test drive on Saturday.",
  "desired_vehicles": [
    { "brand": "Volkswagen", "car_model": "Golf", "year": 2022, "stock_id": "S-1042",
      "reference_url": "https://dealer.example.com/cars/s-1042" }
  ],
  "trade_in_vehicles": [
    { "brand": "Toyota", "car_model": "Yaris", "year": 2016, "mileage": "120000 km" }
  ],
  "external_reference": { "system": "my-crm", "id": "4711", "url": "https://crm.example.com/leads/4711" },
  "test": true
}

The response

202 Accepted: the lead is queued and exists within seconds.

{
  "success": true,
  "lead_id": "led_019a1b2c-3d4e-7f5a-8b6c-7d8e9f0a1b2c",
  "correlation_id": "crr_a1b2c3d4e5f6a7b8c9d0e1f2",
  "status_url": "https://codriver.autouncle.com/api/v1/leads/led_019a1b2c-3d4e-7f5a-8b6c-7d8e9f0a1b2c",
  "message": "Lead accepted and queued for processing"
}

Fields AutoUncle CoDriver doesn't know come back in warnings; they are ignored.

Retry safely: Idempotency-Key

Network calls fail. Send a unique Idempotency-Key (a UUID) with each lead and reuse it when you retry the same lead:

  • the same key and the same body replay the first response, with Idempotent-Replayed: true;
  • the same key with a different body is 422 idempotency_key_reused;
  • a retry while the first request is still running is 409 idempotency_key_in_progress: wait a second.

Keys are kept 24 hours, per API client.

Tie leads to your records: external_reference

external_reference is your own record: system (a stable name for your system, such as my-crm) and id (its ID there), optionally a url. It is unique per organization:

  • pushing the same reference again answers 200 with duplicate: true and the lead AutoUncle CoDriver already created, so a record is never sent twice;
  • you can find the opportunity for your record with GET /api/v1/opportunities?external_reference_system=my-crm&external_reference_id=4711.

A reference without a valid system and id doesn't block the lead: it is accepted without the reference, and warnings carries invalid_external_reference with what was wrong.

Test leads

"test": true (or a Test client) labels the lead as test data: it never counts in reports, and events about it carry "test": true. Otherwise it is processed in full, like any other lead: AutoUncle CoDriver writes to the customer, delivers to the dealer's CRM and notifies sales reps. To test without anything leaving AutoUncle CoDriver, use a sandbox organization, which is in safe mode (see Testing).

View this page as Markdown