Appraiva API Documentation

Overview

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.

Base URL

https://api.appraiva.com

Authentication

All API endpoints require an API key to be included in the x-api-key header.

Example:

x-api-key: your_api_key_here

Endpoints

Submit Properties for Distress Analysis

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-64 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

Limits:

Maximum of 30,000 properties can be submitted in a single request

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"
       }
     ]'

Get Distress Analysis Results

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",
  "created_at": "2025-04-19T06:56:01.789811+00:00",
  "completed_at": "2025-04-19T06:57:01.789811+00:00",
  "breakdown": {
    "total_properties": 5,
    "analyzed": 1,
    "under_construction": 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",
      "image_date": "2023-05"
    },
    {
      "custom_id": "ABC123XYZ",
      "distress_score": null,
      "status": "no_image",
      "address": "456 Elm St",
      "city": "Los Angeles",
      "state": "California",
      "zip": "90001",
      "image_date": null
    },
    {
      "custom_id": "DEF456UVW",
      "distress_score": null,
      "status": "not_visible",
      "address": "789 Oak St",
      "city": "Chicago",
      "state": "Illinois",
      "zip": "60601",
      "image_date": "2024-02"
    },
    {
      "custom_id": "GHI789RST",
      "distress_score": null,
      "status": "address_not_found",
      "address": "101 Pine Ave",
      "city": "Miami",
      "state": "Florida",
      "zip": "33101",
      "image_date": null
    },
    {
      "custom_id": "PQR321ZYX",
      "distress_score": null,
      "status": "under_construction",
      "address": "555 Cedar Blvd",
      "city": "Seattle",
      "state": "Washington",
      "zip": "98101",
      "image_date": "2024-01"
    }
  ]
}

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”)
created_at	string	ISO 8601 timestamp when the job was created
completed_at	string	ISO 8601 timestamp when the job was 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.under_construction	number	Number of properties that are under construction
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”, “under_construction”, “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
results[].image_date	string/null	Date of the property image in “YYYY-MM” format, or null for properties with status “address_not_found” or “no_image”

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"

Error Responses

All error responses have the following format:

{
  "error": "Error type",
  "message": "Detailed error message"
}

Test/Sandbox Mode

The API includes a test/sandbox mode for development and integration testing purposes:

Each customer account includes both production and test API keys
Using test API keys allows you to test the full API workflow without incurring charges
Test keys provide the same functionality as production keys but return simulated data

Using Test Mode

Use your test API key in all requests to activate test mode
Submit properties in the same format as you would for production
Test keys follow the same asynchronous flow as production:
- Initial submission returns a job ID with “processing” status
- Subsequent status checks will eventually show “completed” status
- Completed jobs include realistic mock data with randomized results

Test Mode Characteristics

Test mode preserves your original property data (addresses, custom IDs, etc.)
Results include randomized distress scores for properties marked as “analyzed”
Properties are assigned various statuses to help you test all possible response scenarios
Image dates are provided in “YYYY-MM” format for properties with visible imagery
Image dates are null for properties with status “address_not_found” or “no_image”
Test keys have their own rate limits separate from your production quota

Test mode provides a realistic simulation of the production API, enabling thorough integration testing before deploying to production environments.

Rate Limiting

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.

Support

For assistance with the API, please contact support@appraiva.com.