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.
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.
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:
An example response payload is:
You can explore this request further in the API Playground.
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:
An example response payload is:
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:
An example response payload is:
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.
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:
An example response payload is:
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:
An example response payload is:
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:
An example response payload is:
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:
An example response payload is: