Changelog

Every change to the Appraisal Host API is recorded here, newest first. Within v1 changes are additive only: see the versioning policy on the Reference notes page.

We write to the technical contact on every active credential when we add something you may want, and at least 12 months before anything in v1 is retired.

How to read an entry: Added is safe to ignore until you want it. Changed never alters an existing field's meaning within a major version. Fixed means behavior now matches this documentation. Deprecated carries a date after which the item will stop working in the next major version, never sooner.

1.0.0

The published contract for version 1 of the Appraisal Host API. This is the interface partner integrations are built against. Access to each environment is provisioned by our integrations team as part of onboarding.

Added

One address for every appraisal management company on the platform: https://api.appraisalhost.com/v1 in production and https://sandbox.api.appraisalhost.com/v1 in the sandbox. A credential identifies its lender account and its company, so no routing is needed.
OAuth 2.0 client credentials authentication at POST /oauth/token, accepting form encoding with the credential in the body or in an HTTP Basic header, and JSON, with a 60 minute bearer token and the lender scope. Errors at that endpoint follow RFC 6749.
GET /account: the lender account and the appraisal management company a credential belongs to, its environment, its scopes and its rate limit.
GET /ping, an unauthenticated liveness check.
GET /order-types: the products a lender may order, each with its report format, the appraiser certification it requires, the loan purposes and property types it may be ordered for, and the loan types and add-ons that apply.
POST /orders, with Idempotency-Key honored for 24 hours, GET /orders, GET /orders/{order_id} and PATCH /orders/{order_id}.
POST /orders/{order_id}/hold, /resume and /cancel, each following the rules published on the Order lifecycle page and answering 409 with the order's current_status when the status does not allow the action.
POST /orders/{order_id}/revision-requests and GET for the same path: corrections and reconsiderations of value, with the company's responses.
GET and POST /orders/{order_id}/messages.
GET /orders/{order_id}/documents, POST /orders/{order_id}/documents for supporting uploads up to 25 MB, and GET /documents/{document_id} returning a five minute signed download link.
GET /events, the catch-up feed, with the delivery state of every event and a 30 day retention.
GET and PUT /webhook for your delivery endpoint, your subscription and your signing secret. PUT replaces the fields you send and leaves the others as they are.
POST /webhook/test, which sends you one signed specimen event and returns what your endpoint answered.
POST /sandbox/orders/{order_id}/advance in the sandbox, which moves a test order to the status you name and raises everything a real move raises, so a test suite can run a full lifecycle unattended.
Signed webhooks for 13 event types: order.created, order.status_changed, order.assigned, order.on_hold, order.resumed, order.cancelled, order.completed, order.document_added, order.message_posted, order.revision_requested, order.revision_responded, order.due_date_changed and order.fee_changed. Deliveries carry X-AH-Signature, X-AH-Event-Id and X-AH-Event-Type, with a five minute replay window and nine delivery attempts before a dead letter.
Delivery of both report standards: on uad_2_6 the report as a PDF with the report data as the MISMO 2.6 GSE appraisal XML, on uad_3_6 the report as a PDF with the report data as the UAD 3.6 delivery package, a ZIP produced to the GSE UAD 3.6 specification. The invoice, the certificates and every other delivery document are separate files in both cases.
A published rate limit of 600 requests per minute per client, with X-RateLimit-* headers and Retry-After on 429.
One error body everywhere, with a stable code, field level details carrying a machine readable value, a top level current_status on a lifecycle refusal, and a correlation_id.
The machine readable contract, OpenAPI 3.1, published at /developers/spec/openapi.json.

Changelog

Every change to the Appraisal Host API is recorded here, newest first. Within v1 changes are additive only: see the versioning policy on the Reference notes page.

We write to the technical contact on every active credential when we add something you may want, and at least 12 months before anything in v1 is retired.

1.0.0

Added

One address for every appraisal management company on the platform: https://api.appraisalhost.com/v1 in production and https://sandbox.api.appraisalhost.com/v1 in the sandbox. A credential identifies its lender account and its company, so no routing is needed.

OAuth 2.0 client credentials authentication at POST /oauth/token, accepting form encoding with the credential in the body or in an HTTP Basic header, and JSON, with a 60 minute bearer token and the lender scope. Errors at that endpoint follow RFC 6749.

GET /account: the lender account and the appraisal management company a credential belongs to, its environment, its scopes and its rate limit.

GET /ping, an unauthenticated liveness check.

GET /order-types: the products a lender may order, each with its report format, the appraiser certification it requires, the loan purposes and property types it may be ordered for, and the loan types and add-ons that apply.

POST /orders, with Idempotency-Key honored for 24 hours, GET /orders, GET /orders/{order_id} and PATCH /orders/{order_id}.

POST /orders/{order_id}/hold, /resume and /cancel, each following the rules published on the Order lifecycle page and answering 409 with the order's current_status when the status does not allow the action.

POST /orders/{order_id}/revision-requests and GET for the same path: corrections and reconsiderations of value, with the company's responses.

GET and POST /orders/{order_id}/messages.

GET /orders/{order_id}/documents, POST /orders/{order_id}/documents for supporting uploads up to 25 MB, and GET /documents/{document_id} returning a five minute signed download link.

GET /events, the catch-up feed, with the delivery state of every event and a 30 day retention.

GET and PUT /webhook for your delivery endpoint, your subscription and your signing secret. PUT replaces the fields you send and leaves the others as they are.

POST /webhook/test, which sends you one signed specimen event and returns what your endpoint answered.

POST /sandbox/orders/{order_id}/advance in the sandbox, which moves a test order to the status you name and raises everything a real move raises, so a test suite can run a full lifecycle unattended.

Signed webhooks for 13 event types: order.created, order.status_changed, order.assigned, order.on_hold, order.resumed, order.cancelled, order.completed, order.document_added, order.message_posted, order.revision_requested, order.revision_responded, order.due_date_changed and order.fee_changed. Deliveries carry X-AH-Signature, X-AH-Event-Id and X-AH-Event-Type, with a five minute replay window and nine delivery attempts before a dead letter.

Delivery of both report standards: on uad_2_6 the report as a PDF with the report data as the MISMO 2.6 GSE appraisal XML, on uad_3_6 the report as a PDF with the report data as the UAD 3.6 delivery package, a ZIP produced to the GSE UAD 3.6 specification. The invoice, the certificates and every other delivery document are separate files in both cases.

A published rate limit of 600 requests per minute per client, with X-RateLimit-* headers and Retry-After on 429.

One error body everywhere, with a stable code, field level details carrying a machine readable value, a top level current_status on a lifecycle refusal, and a correlation_id.

The machine readable contract, OpenAPI 3.1, published at /developers/spec/openapi.json.