# Customer Recapture
The Customer Recapture API allows you to upload, view and delete Customer Recapture customers.
This API requires [authentication](https://docs.autograb.com.au/guide/auth/) and an appropriate license attached to it.
### Uploading Customer Lists
The main purpose of the Customer Recapture API is to facilitate the automated upload of new Recapture customers.
Customer lists are often very long, so the Customer 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=nz` will initiate a new queued customer list upload.
The request body has three key parameters:
* `name`: A name to assign to the upload, for personal reference
* `enable_rego_lookups`: When rego lookups are enabled if the registration plate 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 record 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.
* `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
* `vin`: The Vehicle Identification Number corresponding to the customer's vehicle
* `client_name`: The name of the customer/client, for reference purposes
* `mobile_number`: The customer's phone number. This is used for reference purposes, as well as to find other listings that the same customer has posted online.
* `sale_date`: The date that the vehicle was sold to the customer, if applicable. For reference only.
* `expiry_date`: If provided, the customer will be automatically deleted from our system on this date. This may be useful for insurance clients where the customer is no longer of interest after a policy ends, for instance.
* `additional_fields`: A map of any other properties that should be saved along with the customer record.
If you try to upload an empty list, you will receive a `You must upload at least one customer record` 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,
"customers": [
{
"rego": "ZEN407",
"client_name": "Maya",
"expiry_date": "2023-05-01"
}
]
}' 'https://api.autograb.com.au/v2/recapture/upload?region=nz'
```
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
}
}
```
You can explore this request further in the [API Playground](https://docs.autograb.com.au/api).
#### 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=nz` 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 Recapture 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=nz" \
-H 'ApiKey: {API_KEY}'
```
An example response payload is:
```bash
{
"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 customer records.
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=nz" \
-H 'ApiKey: {API_KEY}'
```
An example response payload is:
```bash
{
"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
}
}
```
### Viewing and updating customers
Once you have uploaded a customer list, you are able to use the Customer Recapture API to view your newly uploaded customers, as well as edit and delete individual customer records.
#### Get a list of all customers
You can use the `/v2/recapture/customers?region={REGION}` endpoint to retrieve a list of all your Recapture customers.
This list is paginated, and you can move between pages using the `offset` and `limit` query parameters.
If you want to get customer records associated with a specific upload, you can pass the unique Upload ID to the `upload_id` query parameter.
**Example**
To perform an example request:
```bash
curl -XDELETE "https://api.autograb.com.au/v2/recapture/customers/{UPLOAD_ID}?region=nz&limit=100&offset=0" \
-H 'ApiKey: {API_KEY}'
```
An example response payload is:
```bash
{
"success": true,
"customers": [
{
"id": "000005cb-6d2f-49bc-a5a3-b596ede9202b",
"last_updated": "2022-07-21T05:41:02.941Z",
"rego": null,
"state": 'VIC',
"vin": '1N4AL11D16N337720',
"client_name": "Jack",
"mobile_number": null,
"sale_date": "2022-01-07T00:00:00.000Z",
"expiry_date": null,
"vehicle_title": null,
"sightings": [],
"additional_fields": {}
},
{
"id": "0000993c-f21a-445e-9829-21786098df16",
"last_updated": "2022-07-21T05:45:05.174Z",
"rego": null,
"state": 'NSW',
"vin": '4T1BE46K28U742135',
"client_name": "Jeffery",
"mobile_number": null,
"sale_date": "2020-03-31T00:00:00.000Z",
"expiry_date": null,
"vehicle_title": null,
"sightings": [],
"additional_fields": {}
}
]
}
```
#### Get an individual customer's records
You can get individual customer details using the `GET` method on `/v2/recapture/customers/${CUSTOMER_ID}?region=nz`.
Trying to look up 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 an `You don't have permission to access that customer` error. If you try to look for a customer that exists in a different region than the one specified in the request, you will receive an `Incorrect Region` error.
**Example**
To perform an example request:
```bash
curl "https://api.autograb.com.au/v2/recapture/customers/{CUSTOMER_ID}?region=nz" \
-H 'ApiKey: {API_KEY}'
```
An example response payload is:
```bash
{
"success": true,
"customer": {
"id": "0000c339-1fb4-4d15-9b46-6509f2c5a2a4",
"last_updated": "2022-07-21T02:27:03.543Z",
"rego": '1EW2WA',
"state": null,
"vin": null,
"client_name": "Johnny",
"mobile_number": null,
"sale_date": "2020-07-18T00:00:00.000Z",
"expiry_date": null,
"vehicle_title": null,
"sightings": [],
"additional_fields": {}
}
}
```
#### Update an individual customer record
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=nz` endpoint.
Only the fields that you specify in the request body will be affected, and providing an empty value (`""`) will set the field to null where applicable.
The response payload will include the updated customer object.
You can update any of the following customer properties: - `client_name` - `mobile_number` - `sale_date` - `expiry_date`
**Example**
To perform an example request:
```bash
curl -XPATCH -H 'ApiKey: {API_KEY}' \
-H "Content-type: application/json" -d '{
"mobile_number": "+64 111 222 333",
}' 'https://api.autograb.com.au/v2/recapture/customers/{CUSTOMER_ID}?region=nz'
```
An example response payload is:
```bash
{
"success": true,
"customer": {
"id": "0000c339-1fb4-4d15-9b46-6509f2c5a2a4",
"last_updated": "2022-07-21T02:27:03.543Z",
"state": null,
"vin": null,
"client_name": "Johnny",
"mobile_number": "+64 111 222 333",
"sale_date": "2020-07-18T00:00:00.000Z",
"expiry_date": null,
"vehicle_title": null,
"sightings": [],
"additional_fields": {}
}
}
```
#### Delete a customer
You can delete an individual customer by using the `DELETE` method on the `/v2/recapture/customers/{CUSTOMER_ID}?region=nz` endpoint.
The response payload includes the details of the customer that was deleted, and there is no way to retrieve the customer other than manually re-creating it.
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=nz" \
-H 'ApiKey: {API_KEY}'
```
An example response payload is:
```bash
{
"success": true,
"customer": {
"id": "0000c339-1fb4-4d15-9b46-6509f2c5a2a4",
"last_updated": "2022-07-21T02:27:03.543Z",
"rego": '1EW2WA',
"state": null,
"vin": null,
"client_name": "Johnny",
"mobile_number": null,
"sale_date": "2020-07-18T00:00:00.000Z",
"expiry_date": null,
"vehicle_title": null,
"sightings": [],
"additional_fields": {}
}
}
```