How to submit payments for impound vehicles

Fundamentally submitting a payment for an impound vehicle consists of 3 steps:

Finding the correct vehicle
finding its fees/total to the user and eligibility for release
Creating the receipt & payment

Finding the correct vehicle is done by calling the /impound/lookup endpoint with a payload containing either

Partial or full VIN
License plate number & License state
Date + vehicle details

You’ll also need to send along your region code, and the statuses you’re interested in. In this case the status you’re interested in is “STORED”. Here is an example looking for vehicle in the test region of IMP-TS, in the stored status, with a particular license and license state

curl --location 'https://staging-api.autoreturn.net/api-web/api/impound/lookup' \
--header 'Content-Type: application/json' \
--data '{
"regionCode": "IMP-TS",
"impoundStatus": [
"STORED"
],
"vehicleLookupData": {
"license": "KK00001",
"licenseStateCode": "NC"
},
"start": 0,
"limit": 50
}'

Here is an example of looking up by VIN

curl --location 'https://staging-api.autoreturn.net/api-web/api/impound/lookup' \
--header 'Content-Type: application/json' \
--data '{
"regionCode": "IMP-TS",
"impoundStatus": [
"STORED"
],
"vehicleLookupData": {
"VIN": "2P4GP2539YR506044"
},
"start": 0,
"limit": 50
}'

Looking up by vehicle details is more complicated, since you need our list of makes, models and colors.

You can get these lists by calling /api-web/api/refdata/{regionCode}/colors
/api-web/api/refdata/{regionCode}/makes

and once you have the make, you can request all models for that make using

/api-web/api/refdata/{regionCode}/models/by-make/{makeCode}

Once the user has selected a value for these they should select a date, then you can send those to us, for example.

curl --location 'https://staging-api.autoreturn.net/api-web/api/impound/lookup' \
--header 'Content-Type: application/json' \
--data '{
"regionCode": "IMP-TS",
"impoundStatus": [
"STORED"
],
"vehicleLookupData": {
"makeId": 148,
"modelId": 2307
},
"dateFrom": "2023-01-09T00:00:00",
"dateTo": "2023-01-10T00:00:00",
"start": 0,
"limit": 50
}
'

Note that the limit is very important here, as you could end up returning many vehicles if you allow the user to select something very broad, like all toyotas towed in January.

[
    {
        "id": 1067632,
        "status": "STORED",
        "version": 6,
        "region": {
            "id": 8000,
            "privateRegion": false,
            "standardRegion": true,
            "managedRegion": true,
            "code": "IMP-TS",
            "name": "Impound Test Region",
            "state": "CA",
            "center": {
                "lat": 37.766,
                "lon": -122.428
            },
            "zoneId": "America/Los_Angeles",
            "serverTimeOffset": 0,
            "topRight": {
                "lat": 37.832,
                "lon": -122.355
            },
            "bottomLeft": {
                "lat": 37.668,
                "lon": -122.529
            }
        },
        "make": {
            "id": 148,
            "code": "AIR",
            "name": "AIR",
            "active": true,
            "motorcycle": false
        },
        "model": {
            "id": 2307,
            "makeId": 148,
            "name": "CITY BIKE DA DONNA",
            "code": "CITY BIKE DA DONNA",
            "active": true,
            "motorcycle": false
        },
        "color": {
            "id": 1,
            "name": "BLACK",
            "code": "BLCK",
            "active": true
        },
        "body": {
            "id": 65155,
            "name": "ALL TERAIN VEHICLE",
            "code": "ATV",
            "active": true,
            "motorcycle": false,
            "sortOrder": 29
        },
        "vehicleYear": 0,
        "keyStatus": "KEY_MADE",
        "odometer": 0,
        "vin": "2P4GP2539YR506044",
        "noVin": false,
        "vinNotVisible": false,
        "noPlate": false,
        "license": "KK00001",
        "licenseState": {
            "code": "NC",
            "name": "NORTH CAROLINA",
            "active": true
        },
        "storage": [
            {
                "timeFrom": "2023-01-09T04:29:09.232",
                "lot": {
                    "code": "ART-IMP-TS",
                    "latitude": 29.763576,
                    "longitude": -95.356544,
                    "companyCode": "ART-IMP-TS",
                    "addr1": "123 Test Zone Lot",
                    "city": "San Francisco",
                    "zip": "94105",
                    "phone": "9999999999",
                    "twoStepRelease": false,
                    "state": {
                        "id": "CA",
                        "code": "CA",
                        "name": "CALIFORNIA",
                        "country": "USA",
                        "displayName": "CA - CALIFORNIA"
                    },
                    "id": 1369,
                    "name": "ART-IMP-TS Test Lot"
                },
                "id": 50408
            }
        ],
        "account": {
            "id": 305,
            "code": "TSTACC",
            "name": "TSTACC",
            "active": true,
            "regionCode": "IMP-TS",
            "requestTowCompany": false,
            "imsOnly": false,
            "sortOrder": 0,
            "etims": false
        },
        "equipment": {
            "id": 188,
            "equipmentClass": "LIGHT",
            "regionCode": "IMP-TS",
            "code": "LIGHT",
            "name": "Regular",
            "secondVehicleAllowed": false,
            "dispatch": true,
            "impound": true,
            "defaultForAutodispatch": true,
            "allowedIfTCTZETisMissing": false
        },
        "reason": {
            "id": 1887,
            "code": "TEST",
            "name": "Test",
            "regionCode": "IMP-TS",
            "active": true,
            "sendToImpoundSystem": true,
            "category": "IMPOUND",
            "medical": false,
            "sweep": false,
            "skipStorage": false,
            "salvor": false,
            "ads": true,
            "publiclyVisible": false
        },
        "zone": {
            "code": "IMP-TS",
            "name": "Test Zone",
            "precinctId": 0,
            "active": true,
            "testZone": true,
            "regionDefault": false
        },
        "towOperatorCompany": {
            "code": "ART-IMP-TS",
            "id": 1338,
            "name": "Test Company"
        },
        "currentImpoundOperator": {
            "code": "ART-IMP-TS",
            "id": 1338,
            "name": "Test Company"
        },
        "currentLot": {
            "code": "ART-IMP-TS",
            "latitude": 29.763576,
            "longitude": -95.356544,
            "companyCode": "ART-IMP-TS",
            "addr1": "123 Test Zone Lot",
            "city": "San Francisco",
            "zip": "94105",
            "phone": "9999999999",
            "twoStepRelease": false,
            "state": {
                "id": "CA",
                "code": "CA",
                "name": "CALIFORNIA",
                "country": "USA",
                "displayName": "CA - CALIFORNIA"
            },
            "id": 1369,
            "name": "ART-IMP-TS Test Lot"
        },
        "currentLocation": {
            "code": "ART-IMP-TS",
            "latitude": 29.763576,
            "longitude": -95.356544,
            "companyCode": "ART-IMP-TS",
            "addr1": "123 Test Zone Lot",
            "city": "San Francisco",
            "zip": "94105",
            "phone": "9999999999",
            "twoStepRelease": false,
            "state": {
                "id": "CA",
                "code": "CA",
                "name": "CALIFORNIA",
                "country": "USA",
                "displayName": "CA - CALIFORNIA"
            },
            "id": 1369,
            "name": "ART-IMP-TS Test Lot"
        },
        "holds": [],
        "contacts": [
            {
                "phoneNumber": "5555555555",
                "email": "joe@example.com",
                "void": false,
                "city": "City",
                "zip": "12345",
                "firstName": "Joe",
                "lastName": "Schmoe",
                "address1": "Address",
                "address2": "Address2",
                "identification": "ABC123",
                "identificationType": "US_DL",
                "idState": "CA",
                "contactId": 12330,
                "state": "CA",
                "type": "PAID_BY",
                "id": 12330
            },
            {
                "phoneNumber": "5555555555",
                "email": "joe@example.com",
                "void": false,
                "city": "City",
                "zip": "12345",
                "firstName": "Joe",
                "lastName": "Schmoe",
                "address1": "Address",
                "address2": "Address2",
                "identification": "ABC123",
                "identificationType": "US_DL",
                "idState": "CA",
                "contactId": 12331,
                "state": "CA",
                "type": "PAID_BY",
                "id": 12331
            }
        ],
        "relatedVehicles": [],
        "towReferenceNumber": "000268A000268",
        "waivers": [],
        "patrolUnitNumber": "5409",
        "towOrigin": {
            "addr1": "SEE MAP",
            "city": "Mountain View",
            "state": "CA"
        },
        "responseDate": "2023-01-09T04:47:37",
        "requestedDate": "2023-01-09T04:27:37.207",
        "dispatchedDate": "2023-01-09T04:27:37",
        "acceptedDate": "2023-01-09T04:28:52",
        "onsiteDate": "2023-01-09T04:28:58",
        "inTowDate": "2023-01-09T04:29:04",
        "clearedDate": "2023-01-09T04:29:09.232",
        "driverName": "Passport Test Driver",
        "conditions": [],
        "specialEvent": false,
        "nonStandardVin": false
    }
]

Once you have the correct vehicle you can then retrieve its fees and total unpaid amount by its vehicleId.

VehicleId is the unique id for each time a vehicle gets towed. If it gets towed twice, it will get 2 vehicleIds. You then make a request to the /impound endpoint which will get you the complete vehicle details including the fees as of the time of the request.

curl --location 'https://staging-api.autoreturn.net/api-web/api/impound?id=1067632

for example will give a response containing most of the details of the vehicle. In particular you’ll want to look at

currentLocation which represents the best way to get into contact with whoever has current possession of the vehicle
make.name , model.name , color.name , license , licenseState.code
unpaidFeeItems which contains all of the fee items that are not paid yet.
totalUnpaid which contains the total unpaid amount for this vehicle
eligibleForOnlinePayment indicates if the vehicle is currently releasable. Holds may prevent release of the vehicle, in which case you probably don’t want to let people pay for it. The vehicle may also enter other states that would make online payments not apply correctly.

Here is an example of the response

Once the user has indicated that they want to pay you must collect contact information from the user, this is used to ensure that the vehicle is released to the correct person later in the process.

You then call the /createReceiptAndPayment endpoint with the vehicleId, contact details and amount paid.

Note how in the response the vehicle’s status has changed to RELEASE_PENDING. This happens when a vehicle in a releasable state has been fully paid for. Also note the value in vehicle.releaseAuthorizedThrough, this is the latest time that the vehicle owner can show up to the yard to retrieve the vehicle before additional fees might be applied.