# Recapture API

#### Uploading Customer lists <a href="#uploading-customer-lists" id="uploading-customer-lists"></a>

The main purpose of the Recapture API is to facilitate the automated upload of new Customers.

Customer lists are often very long, so the Recapture API allows you to queue Customer uploads without immediately processing every Customer in the list. There is an endpoint to queue the upload, and separate endpoints to check the status of the upload, and cancel it, if necessary.

**Upload a list of Customers**

A `POST` request to `https://api.autograb.com.au/v2/recapture/upload?region={REGION}` will initiate a new queued Customer list upload.

The request body has the following parameters:

* `name`: A name to assign to the upload, for personal reference
* `enable_rego_lookups`: When rego lookups are enabled, if the registration plate (and state, if in Australia) is provided, but no VIN is provided for a Customer, we will perform a VIN lookup (at additional cost to you) and save the VIN along with the Customer. When a Customer includes a VIN number, we can cross-reference the VIN with new vehicle listings posted in the future, and use this to verify that the car being sold is definitely the same car that you are tracking.
* `monitor_start_date`: An optional default date from which Customers in this upload should start being monitored. Applied to any Customer that does not specify its own `monitor_start_date`.
* `monitor_end_date`: An optional default date after which Customers in this upload should stop being monitored. Applied to any Customer that does not specify its own `monitor_end_date`.
* `customers`: An array of the Customers that you want to upload. Customers can have any of the following properties, but everything is optional (however, at least a rego OR a vin is necessary for tracking purposes):
  * `rego`: The registration plate of the Customer's vehicle
  * `state`: The registration state of the vehicle, if applicable
  * `vin`: The Vehicle Identification Number corresponding to the Customer's vehicle
  * `external_id`: An optional identifier from your own system to associate with this Customer, for your reference.
  * `sale_date`: The date that the vehicle was sold to the Customer, if applicable. For reference only.
  * `monitor_start_date`: If provided, overrides the upload-level `monitor_start_date` for this specific Customer.
  * `monitor_end_date`: If provided, overrides the upload-level `monitor_end_date` for this specific Customer.
  * `additional_fields`: A map of any other properties that should be saved along with the Customer.

If you try to upload an empty list, you will receive a `You must upload at least one customer` error.

**Example**

To perform an example request:

```bash
curl -XPOST -H 'ApiKey: {API_KEY}' \
    -H "Content-Type: application/json" \
    -d '{
        "name": "June 2022 New Customers",
        "enable_rego_lookups": false,
        "monitor_start_date": "2022-06-01",
        "monitor_end_date": "2023-06-01",
        "customers": [
            {
                "rego": "ZEN407",
                "state": "VIC",
                "external_id": "CUST-4821",
                "sale_date": "2022-06-15",
                "additional_fields": {
                    "market_source": "dealer_crm",
                    "customer_type": "vip"
                }
            }
        ]
    }' 'https://api.autograb.com.au/v2/recapture/upload?region={REGION}'
```

This endpoint returns a `202 Accepted` response. An example response payload is:

```json
{
  "success": true,
  "upload": {
    "id": "99aa2d8e-348b-4321-beeb-f2fa67bab3eb",
    "created_at": "2022-07-21T08:07:16.580Z",
    "enable_rego_lookups": false,
    "name": "June 2022 New Customers",
    "total_uploaded_customers": 1,
    "total_processed_customers": 0,
    "total_errors": 0
  }
}
```

**Check upload status**

Once you've queued a Customer upload, you may want to check on the upload progress. Sending a `GET` request to `/v2/recapture/upload/{UPLOAD_ID}?region={REGION}` will return information about the upload, including the progress and the number of errors.

The key properties to check the upload progress are `total_uploaded_customers` and `total_processed_customers`. Creating a new Customer consists of two steps - uploading and processing - and these two counters reflect the progress made for each of these steps.

Once `total_processed_customers` is equal to `total_uploaded_customers`, the upload is complete. If there are any unexpected errors during the upload, `total_errors` will increase to signify this, but `total_processed_customers` is inclusive of errors.

**Example**

To perform an example request:

```bash
curl "https://api.autograb.com.au/v2/recapture/upload/{UPLOAD_ID}?region={REGION}" \
     -H 'ApiKey: {API_KEY}'
```

An example response payload is:

```json
{
  "success": true,
  "upload": {
    "id": "80230301-9d26-45d7-85d6-fbb8c519c014",
    "created_at": "2022-07-16T06:22:05.289Z",
    "enable_rego_lookups": false,
    "name": "August 2022 New Customers",
    "total_uploaded_customers": 1000,
    "total_processed_customers": 800,
    "total_errors": 0
  }
}
```

**Cancel an upload**

If you queue a Customer upload and later change your mind, you can cancel the upload, stopping the creation of any more Customers.

The response payload will include the details of the deleted upload.

**Example**

To perform an example request:

```bash
curl -XDELETE "https://api.autograb.com.au/v2/recapture/upload/{UPLOAD_ID}?region={REGION}" \
     -H 'ApiKey: {API_KEY}'
```

An example response payload is:

```json
{
  "success": true,
  "upload": {
    "id": "80230301-9d26-45d7-85d6-fbb8c519c014",
    "created_at": "2022-07-16T06:22:05.289Z",
    "enable_rego_lookups": false,
    "name": "August 2022 New Customers",
    "total_uploaded_customers": 1000,
    "total_processed_customers": 850,
    "total_errors": 0
  }
}
```

#### Managing Customers <a href="#managing-customers" id="managing-customers"></a>

Once you have uploaded a Customer list, you are able to use the Recapture API to view your newly uploaded Customers, as well as create, edit and delete individual Customer.

**Get a list of all Customers**

You can use the `/v2/recapture/customers?region={REGION}` endpoint to retrieve a list of all your Customers.

This list is paginated, and you can move between pages using the `offset` and `limit` query parameters. The `limit` is capped at 500.

If you want to get Customers associated with a specific upload, you can pass the unique Upload ID to the `upload_id` query parameter.

The response includes a `total` field with the overall count of Customers matching the query, which is useful for paginating through large lists.

**Example**

To perform an example request:

```bash
curl "https://api.autograb.com.au/v2/recapture/customers?region={REGION}&limit=100&offset=0" \
     -H 'ApiKey: {API_KEY}'
```

An example response payload is:

```json
{
  "success": true,
  "total": 2,
  "customers": [
    {
      "id": "000005cb-6d2f-49bc-a5a3-b596ede9202b",
      "last_updated": "2022-07-21T05:41:02.941Z",
      "rego": "ABC123",
      "state": "VIC",
      "vin": "1N4AL11D16N337720",
      "external_id": "CUST-4821",
      "sale_date": "2022-01-07T00:00:00.000Z",
      "monitor_start_date": "2022-06-01T00:00:00.000Z",
      "monitor_end_date": "2023-06-01T00:00:00.000Z",
      "vehicle_title": "2019 Toyota Camry Ascent",
      "sightings": [
        {
          "at": "2022-08-15T14:23:01.000Z",
          "lead_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "listing_url": "https://www.carsales.com.au/cars/details/OAG-AD-123456/",
          "listing_title": "2019 Toyota Camry Ascent Sport",
          "listing_price": 28500,
          "seller_type": "private"
        }
      ],
      "additional_fields": {
        "market_source": "dealer_crm",
        "customer_type": "vip"
      }
    },
    {
      "id": "0000993c-f21a-445e-9829-21786098df16",
      "last_updated": "2022-07-21T05:45:05.174Z",
      "rego": "DEF456",
      "state": "NSW",
      "vin": "4T1BE46K28U742135",
      "external_id": "CUST-7964",
      "sale_date": "2020-03-31T00:00:00.000Z",
      "monitor_start_date": null,
      "monitor_end_date": null,
      "vehicle_title": "2017 Mazda 3 Maxx",
      "sightings": [],
      "additional_fields": {
        "market_source": "dealer_crm",
        "customer_type": "vip"
      }
    }
  ]
}
```

**Create an individual Customer**

You can create a single Customer directly using the `PUT` method on the `/v2/recapture/customers?region={REGION}` endpoint.

The request body has two parameters:

* `enable_rego_lookups`: When enabled, if a registration plate is provided but no VIN, we will perform a VIN lookup (at additional cost). Defaults to `false`.
* `customer`: An object with the Customer's details. At least a `rego` or a `vin` must be provided.
  * `rego`: The registration plate of the Customer's vehicle
  * `state`: The registration state of the vehicle, if applicable
  * `vin`: The Vehicle Identification Number corresponding to the Customer's vehicle
  * `external_id`: An optional identifier from your own system to associate with this Customer, for your reference
  * `sale_date`: The date that the vehicle was sold to the Customer, if applicable
  * `monitor_start_date`: If provided, the date from which this Customer should start being monitored
  * `monitor_end_date`: If provided, the date after which this Customer should stop being monitored
  * `additional_fields`: A map of any other properties to save with the Customer

If neither `rego` nor `vin` is provided, you will receive a `Missing required properties` error.

**Example**

To perform an example request:

```bash
curl -XPUT -H 'ApiKey: {API_KEY}' \
    -H "Content-Type: application/json" \
    -d '{
        "enable_rego_lookups": true,
        "customer": {
            "rego": "ZEN407",
            "state": "VIC",
            "external_id": "CUST-4821",
            "sale_date": "2022-06-01",
            "monitor_start_date": "2022-06-01",
            "monitor_end_date": "2023-06-01",
            "additional_fields": {
                "market_source": "dealer_crm",
                "customer_type": "vip"
            }
        }
    }' 'https://api.autograb.com.au/v2/recapture/customers?region={REGION}'
```

An example response payload is:

```json
{
  "success": true,
  "customer": {
    "id": "0000c339-1fb4-4d15-9b46-6509f2c5a2a4",
    "last_updated": "2022-07-21T02:27:03.543Z",
    "rego": "ZEN407",
    "state": "VIC",
    "vin": "1N4AL11D16N337720",
    "external_id": "CUST-4821",
    "sale_date": "2022-06-01T00:00:00.000Z",
    "monitor_start_date": "2022-06-01T00:00:00.000Z",
    "monitor_end_date": "2023-06-01T00:00:00.000Z",
    "vehicle_title": "2019 Toyota Camry Ascent",
    "sightings": [],
    "additional_fields": {
      "market_source": "dealer_crm",
      "customer_type": "vip"
    }
  }
}
```

**Get an individual Customer**

You can get individual Customer details using the `GET` method on `/v2/recapture/customers/{CUSTOMER_ID}?region={REGION}`.

Trying to lookup an invalid Customer ID returns the `Invalid Customer ID` error, and trying to look up a Customer that you don't have access to returns a `You don't have permission to access that customer` error.

**Example**

To perform an example request:

```bash
curl "https://api.autograb.com.au/v2/recapture/customers/{CUSTOMER_ID}?region={REGION}" \
     -H 'ApiKey: {API_KEY}'
```

An example response payload is:

```json
{
  "success": true,
  "customer": {
    "id": "0000c339-1fb4-4d15-9b46-6509f2c5a2a4",
    "last_updated": "2022-07-21T02:27:03.543Z",
    "rego": "1EW2WA",
    "state": "VIC",
    "vin": "1N4AL11D16N337720",
    "external_id": "CUST-4821",
    "sale_date": "2020-07-18T00:00:00.000Z",
    "monitor_start_date": "2022-06-01T00:00:00.000Z",
    "monitor_end_date": "2023-06-01T00:00:00.000Z",
    "vehicle_title": "2019 Toyota Camry Ascent",
    "sightings": [
      {
        "at": "2022-08-15T14:23:01.000Z",
        "lead_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "listing_url": "https://www.carsales.com.au/cars/details/OAG-AD-123456/",
        "listing_title": "2019 Toyota Camry Ascent Sport",
        "listing_price": 28500,
        "seller_type": "private"
      }
    ],
    "additional_fields": {
      "market_source": "dealer_crm",
      "customer_type": "vip"
    }
  }
}
```

**Update an individual Customer**

If you need to make changes to an individual Customer's details, you can use the `PATCH` method on the `/v2/recapture/customers/{CUSTOMER_ID}?region={REGION}` endpoint.

Only the fields that you specify in the request body will be affected, and providing an empty value (`""`) or `null` will clear the field where applicable.

The response payload will include the updated Customer object.

You can update any of the following Customer properties: `external_id`, `sale_date`, `monitor_start_date`, `monitor_end_date`, `additional_fields`

`sale_date`, `monitor_start_date`, and `monitor_end_date` must be valid date strings if provided.

**Example**

To perform an example request:

```bash
curl -XPATCH -H 'ApiKey: {API_KEY}' \
    -H "Content-Type: application/json" \
    -d '{
        "external_id": "CUST-5673",
        "sale_date": "2022-06-15",
        "monitor_start_date": "2022-06-01",
        "monitor_end_date": "2023-06-01",
        "additional_fields": {
            "market_source": "dealer_crm",
            "customer_type": "vip"
        }
    }' 'https://api.autograb.com.au/v2/recapture/customers/{CUSTOMER_ID}?region={REGION}'
```

An example response payload is:

```json
{
  "success": true,
  "customer": {
    "id": "0000c339-1fb4-4d15-9b46-6509f2c5a2a4",
    "last_updated": "2022-07-21T02:27:03.543Z",
    "rego": "1EW2WA",
    "state": "VIC",
    "vin": "1N4AL11D16N337720",
    "external_id": "CUST-5673",
    "sale_date": "2022-06-15T00:00:00.000Z",
    "monitor_start_date": "2022-06-01T00:00:00.000Z",
    "monitor_end_date": "2023-06-01T00:00:00.000Z",
    "vehicle_title": "2019 Toyota Camry Ascent",
    "sightings": [
      {
        "at": "2022-08-15T14:23:01.000Z",
        "lead_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "listing_url": "https://www.carsales.com.au/cars/details/OAG-AD-123456/",
        "listing_title": "2019 Toyota Camry Ascent Sport",
        "listing_price": 28500,
        "seller_type": "private"
      }
    ],
    "additional_fields": {
      "market_source": "dealer_crm",
      "customer_type": "vip"
    }
  }
}
```

**Delete an individual Customer**

You can delete an individual Customer by using the `DELETE` method on the `/v2/recapture/customers/{CUSTOMER_ID}?region={REGION}` endpoint.

The response payload includes the details of the Customer that was deleted.

The same error messages apply as with the Get Customer endpoint.

**Example**

To perform an example request:

```bash
curl -XDELETE "https://api.autograb.com.au/v2/recapture/customers/{CUSTOMER_ID}?region={REGION}" \
     -H 'ApiKey: {API_KEY}'
```

An example response payload is:

```json
{
  "success": true,
  "customer": {
    "id": "0000c339-1fb4-4d15-9b46-6509f2c5a2a4",
    "last_updated": "2022-07-21T02:27:03.543Z",
    "rego": "1EW2WA",
    "state": "VIC",
    "vin": "1N4AL11D16N337720",
    "external_id": "CUST-4821",
    "sale_date": "2020-07-18T00:00:00.000Z",
    "monitor_start_date": "2022-06-01T00:00:00.000Z",
    "monitor_end_date": "2023-06-01T00:00:00.000Z",
    "vehicle_title": "2019 Toyota Camry Ascent",
    "sightings": [
      {
        "at": "2022-08-15T14:23:01.000Z",
        "lead_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "listing_url": "https://www.carsales.com.au/cars/details/OAG-AD-123456/",
        "listing_title": "2019 Toyota Camry Ascent Sport",
        "listing_price": 28500,
        "seller_type": "private"
      }
    ],
    "additional_fields": {
      "market_source": "dealer_crm",
      "customer_type": "vip"
    }
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://devhub.autograb.com/customer-recapture/recapture-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.