Customer Recapture

The Customer Recapture API allows you to upload, view and delete Customer Recapture customers.

This API requires authentication 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 (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 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

• state: The registration state of the vehicle, if applicable

• 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:

curl -XPOST -H 'ApiKey: {API_KEY}' \
    -H "Content-type: application/json" \
    -d '{
        "name": "June 2022 New Customers",
        "enable_rego_lookups": false,
        "customers": [
            {
                "rego": "ZEN407",
                "state": "VIC",
                "client_name": "Maya",
                "expiry_date": "2023-05-01"
            }
        ]
    }' 'https://api.autograb.com.au/v2/recapture/upload?region=nz'

An example response payload is:

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

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:

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

An example response payload is:

{
    "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:

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

An example response payload is:

{
    "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:

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

An example response payload is:

{
    "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:

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

An example response payload is:

{
    "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:

curl -XPATCH -H 'ApiKey: {API_KEY}' \
    -H "Content-type: application/json" -d '{
        "mobile_number": "[phone]",
    }' 'https://api.autograb.com.au/v2/recapture/customers/{CUSTOMER_ID}?region=nz'

An example response payload is:

{
    "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": "[phone]",
        "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:

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

An example response payload is:

{
    "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": {}
    }
}