Sending an Observation
An observation reports something seen at a parking facility, such as a vehicle entering or leaving. Send each observation as a POST request to the Observations API. First, get an access token with the observations scope. See Getting an Access Token.
This API may reject fields sent as null. Omit an optional field when you have no value for it. Always include observed_images; if you have no images, send an empty list ([]), not null.
1. Start with the required fields
Every request must include:
identifiers: the identifier object assigned to your integration.observed_on: when the event happened, as an ISO 8601 timestamp.observation_medium: how the event was observed.observed_images: a list of images. Use an empty list if you have no images.
The example uses a spothero identifier object with a rental ID and facility ID. Your integration may use a different identifier key and different fields. Use the identifier details provided for your integration. Exactly one identifier object is required.
POST https://api.staging.spothero.com/v2/facilities/observations
Authorization: Bearer <access_token>
Content-Type: application/json
{
"identifiers": {
"spothero": {
"rental_id": "123456789",
"facility_id": "cf_01jschkxr3f65a9n6b5cet3bna"
}
},
"observed_on": "2030-03-22T12:30:00Z",
"observation_medium": "SCANNER",
"observed_images": []
}
The observed_on value must include a date and time. The example uses Z to show that the time is in UTC.
Supported observation_medium values are:
FIXED_CAMERA, AUTOMATED_LPR, VISUAL, SCANNER, RF_TRANSPONDER, and CHALK_MARK.
Each example in the next sections shows the required fields plus the optional field covered in that section. The examples do not carry optional fields from earlier sections. The complete request at the end combines them all.
2. Add the event type (optional)
Use observed_action to describe what happened:
{
"identifiers": {
"spothero": {
"rental_id": "123456789",
"facility_id": "cf_01jschkxr3f65a9n6b5cet3bna"
}
},
"observed_on": "2030-03-22T12:30:00Z",
"observation_medium": "SCANNER",
"observed_action": "VEHICLE_ENTRY",
"observed_images": []
}
This request adds observed_action to the required fields.
Supported values are VEHICLE_ENTRY, VEHICLE_EXIT, VALET_CHECKIN, VALET_CHECKOUT, SCAN_IN, and SCAN_OUT.
3. Add the credential that was observed (optional)
If you captured a credential, include both its type and content in observed_credential:
{
"identifiers": {
"spothero": {
"rental_id": "123456789",
"facility_id": "cf_01jschkxr3f65a9n6b5cet3bna"
}
},
"observed_on": "2030-03-22T12:30:00Z",
"observation_medium": "SCANNER",
"observed_images": [],
"observed_credential": {
"type": "LICENSE_PLATE",
"content": "ABCS231"
}
}
This body contains the required fields and observed_credential.
Supported credential types are BARCODE, BLUETOOTH, E_TICKET, HANGTAG, LICENSE_PLATE, OTHER, PERMIT, PHONE_NUMBER, QR_CODE, RFID, and TICKET.
4. Add vehicle details (optional)
If you include observed_vehicle, it must include license_plate. The plate must contain 1 to 20 uppercase letters or numbers. You can also add the vehicle's make, model, and color:
{
"identifiers": {
"spothero": {
"rental_id": "123456789",
"facility_id": "cf_01jschkxr3f65a9n6b5cet3bna"
}
},
"observed_on": "2030-03-22T12:30:00Z",
"observation_medium": "SCANNER",
"observed_images": [],
"observed_vehicle": {
"license_plate": "ABCS231",
"make": "Subaru",
"model": "WRX STI",
"color": "BLUE"
}
}
This body contains the required fields and observed_vehicle.
Make must be 3 to 20 characters. Model must be 1 to 50 characters. Color must be 3 to 16 uppercase letters. If you do not have vehicle details, leave out observed_vehicle; do not send it as null.
5. Add images (optional)
observed_images is a list. Each image needs a URL and the image file's SHA-256 hash in hexadecimal:
{
"identifiers": {
"spothero": {
"rental_id": "123456789",
"facility_id": "cf_01jschkxr3f65a9n6b5cet3bna"
}
},
"observed_on": "2030-03-22T12:30:00Z",
"observation_medium": "SCANNER",
"observed_images": [
{
"image_url": "https://images.example.com/parking/observation.jpg",
"image_sha256_hash_hex": "0ac529807c593e607e397e10dfaeed75522ff539780210b62a76c74ea2d9c895"
}
]
}
This body contains the required fields and observed_images.
SpotHero must be able to download the image using GET for at least 7 days after you send the observation. The hash lets SpotHero check that the downloaded file has not changed. On a Unix-based system, you can calculate the hash with sha256sum image.jpg.
If there are no images, set observed_images to an empty list. This complete body shows that the required fields remain in the request:
{
"identifiers": {
"spothero": {
"rental_id": "123456789",
"facility_id": "cf_01jschkxr3f65a9n6b5cet3bna"
}
},
"observed_on": "2030-03-22T12:30:00Z",
"observation_medium": "SCANNER",
"observed_images": []
}
Do not send "observed_images": null.
6. Complete request example
This staging example combines the required fields with an event type, credential, vehicle, and image:
POST https://api.staging.spothero.com/v2/facilities/observations
Authorization: Bearer <access_token>
Content-Type: application/json
{
"identifiers": {
"spothero": {
"rental_id": "123456789",
"facility_id": "cf_01jschkxr3f65a9n6b5cet3bna"
}
},
"observed_on": "2030-03-22T12:30:00Z",
"observation_medium": "SCANNER",
"observed_action": "VEHICLE_ENTRY",
"observed_credential": {
"type": "LICENSE_PLATE",
"content": "ABCS231"
},
"observed_vehicle": {
"license_plate": "ABCS231",
"make": "Subaru",
"model": "WRX STI",
"color": "BLUE"
},
"observed_images": [
{
"image_url": "https://images.example.com/parking/observation.jpg",
"image_sha256_hash_hex": "0ac529807c593e607e397e10dfaeed75522ff539780210b62a76c74ea2d9c895"
}
]
}
7. Read the response
A successful request returns HTTP 201 Created and an observation_id, which is SpotHero's identifier for the new observation:
{
"observation_id": "obv_01jqpsxs51f008kmxmh1pttkvx"
}
For the full request schema and error responses, see the Observations API reference.