Customer Recapture
The Customer Recapture API allows you to upload, view and delete Customer Recapture customers.
This API requires authentication and 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=au
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 referenceenable_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 vehiclestate
: The registration state of the vehicle, if applicablevin
: The Vehicle Identification Number corresponding to the customer's vehicleclient_name
: The name of the customer/client, for reference purposesmobile_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.
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=au
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:
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:
An example response payload is:
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:
An example response payload is:
Get an individual customer's records
You can get individual customer details using the GET
method on /v2/recapture/customers/${CUSTOMER_ID}?region=au
.
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. If you try to lookup a customer that exists in a different region to the one specified in the request, you will receive an Incorrect Region
error.
Example
To perform an example request:
An example response payload is:
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=au
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:
Delete a customer
You can delete an individual customer by using the DELETE
method on the /v2/recapture/customers/{CUSTOMER_ID}?region=au
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:
Last updated