# Push leads


# 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](/api-docs).

```json
{
  "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.

```json
{
  "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](/developers/testing)).