The Appraiva API provides endpoints for property distress analysis. It allows clients to submit property information for analysis and retrieve the results once they are ready. The API follows a two-step process: first, you submit properties for analysis using an async POST endpoint, and then you poll the GET endpoint to fetch the results once processing is complete.
https://api.appraiva.com
All API endpoints require an API key to be included in the x-api-key header.
Example:
x-api-key: your_api_key_here
Submit a list of properties for asynchronous distress analysis.
Endpoint: POST /v1/properties/distress/async
Example Request Body: JSON array of property objects with the following structure:
[
{
"custom_id": "JKL123MNO",
"address": "123 James Ave",
"city": "New York",
"state": "New York",
"zip": "07008"
},
{
"custom_id": "ABC123XYZ",
"address": "456 Elm St",
"city": "Los Angeles",
"state": "California",
"zip": "90001"
}
]
Request Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| custom_id | string | Yes | Unique identifier for the property (provided by client). Must be 3-30 characters and contain only letters, numbers, underscores, or hyphens. |
| address | string | Yes | Street address of the property |
| city | string | Yes | City where the property is located |
| state | string | Yes | State where the property is located |
| zip | string | Yes | ZIP/Postal code of the property |
Example Response:
{
"job_id": "JOB123ABC",
"status": "processing"
}
Response Fields:
| Field | Type | Description |
|---|---|---|
| job_id | string | Unique identifier for the analysis job |
| status | string | Current status of the job (always “processing” for new submissions) |
Status Codes:
| Status | Description |
|---|---|
| 202 | Accepted - The request has been accepted for processing |
| 400 | Bad Request - Invalid request format |
| 401 | Unauthorized - Missing or invalid API key |
| 429 | Too Many Requests - Rate limit exceeded |
cURL Usage Example:
curl -X POST "https://api.appraiva.com/v1/properties/distress/async" \
-H "x-api-key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '[
{
"custom_id": "JKL123MNO",
"address": "123 James Ave",
"city": "New York",
"state": "New York",
"zip": "07008"
},
{
"custom_id": "ABC123XYZ",
"address": "456 Elm St",
"city": "Los Angeles",
"state": "California",
"zip": "90001"
}
]'
Retrieve the results of a previously submitted distress analysis job.
Endpoint: GET /v1/properties/distress/async/job/{job_id}
URL Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| job_id | string | Yes | Unique identifier for the analysis job |
Example Response (Processing):
{
"job_id": "JOB123ABC",
"status": "processing",
"message": "Results not ready. Please check back soon."
}
Example Response (Completed):
{
"job_id": "JOB123ABC",
"status": "completed",
"breakdown": {
"total_properties": 4,
"analyzed": 1,
"no_image": 1,
"not_visible": 1,
"address_not_found": 1
},
"results": [
{
"custom_id": "JKL123MNO",
"distress_score": 75,
"status": "analyzed",
"address": "123 James Ave",
"city": "New York",
"state": "New York",
"zip": "07008"
},
{
"custom_id": "ABC123XYZ",
"distress_score": null,
"status": "no_image",
"address": "456 Elm St",
"city": "Los Angeles",
"state": "California",
"zip": "90001"
},
{
"custom_id": "DEF456UVW",
"distress_score": null,
"status": "not_visible",
"address": "789 Oak St",
"city": "Chicago",
"state": "Illinois",
"zip": "60601"
},
{
"custom_id": "GHI789RST",
"distress_score": null,
"status": "address_not_found",
"address": "101 Pine Ave",
"city": "Miami",
"state": "Florida",
"zip": "33101"
}
]
}
Response Fields (Processing):
| Field | Type | Description |
|---|---|---|
| job_id | string | Unique identifier for the analysis job |
| status | string | Current status of the job (“processing”) |
| message | string | Information about the job status |
Response Fields (Completed):
| Field | Type | Description |
|---|---|---|
| job_id | string | Unique identifier for the analysis job |
| status | string | Current status of the job (“completed”) |
| breakdown | object | Summary statistics of the analysis |
| breakdown.total_properties | number | Total number of properties submitted |
| breakdown.analyzed | number | Number of properties successfully analyzed |
| breakdown.no_image | number | Number of properties with no available imagery |
| breakdown.not_visible | number | Number of properties not visible in the image |
| breakdown.address_not_found | number | Number of properties where the address was not found in our database |
| results | array | Array of property results |
| results[].custom_id | string | Client-provided unique identifier for the property |
| results[].distress_score | number/null | Distress score (0-100), or null if analysis couldn’t be performed. Higher score indicates greater property distress. |
| results[].status | string | Analysis status (“analyzed”, “no_image”, “not_visible”, or “address_not_found”) |
| results[].address | string | Street address of the property |
| results[].city | string | City where the property is located |
| results[].state | string | State where the property is located |
| results[].zip | string | ZIP/Postal code of the property |
Status Codes:
| Status | Description |
|---|---|
| 200 | OK - The request was successful |
| 400 | Bad Request - Invalid job ID format |
| 401 | Unauthorized - Missing or invalid API key |
| 404 | Not Found - Job ID does not exist |
| 429 | Too Many Requests - Rate limit exceeded |
cURL Usage Example:
curl -X GET "https://api.appraiva.com/v1/properties/distress/async/job/JOB123ABC" \
-H "x-api-key: your_api_key_here"
All error responses have the following format:
{
"error": "Error type",
"message": "Detailed error message"
}
The API supports a test/sandbox mode for development and integration testing:
API requests are subject to rate limiting based on your API key’s usage plan. If you exceed the rate limit, you’ll receive a 429 Too Many Requests response.
For assistance with the API, please contact support@appraiva.com.