{ "openapi": "3.1.0", "info": { "title": "Appraisal Host API", "version": "1.0.0", "summary": "Place, track and receive appraisal orders with an appraisal management company that runs on Appraisal Host.", "description": "The Appraisal Host API lets a loan origination system, a point of sale, or any\nordering platform place appraisal orders with an appraisal management company\nthat runs on Appraisal Host, follow each order through its lifecycle,\nexchange messages and documents, and receive the finished report package.\n\nOne address serves every appraisal management company on the platform. Each\ncredential we issue belongs to one lender account at one company, so the\ncredential itself tells us where the order belongs. You store one base URL and one credential per lender you serve.\n\nConventions used throughout:\n\n* JSON request and response bodies, UTF-8.\n* Identifiers are opaque prefixed strings (`ord_`, `doc_`, `msg_`, `rr_`,\n `evt_`, `cli_`). Treat them as strings of up to 64 characters and do not\n parse them.\n* Timestamps are ISO-8601 in UTC, for example `2026-09-17T14:32:05Z`. Dates\n without a time are `YYYY-MM-DD`.\n* Money is a decimal string with a separate currency code, for example\n `\"525.00\"` with `\"USD\"`. We never send money as a floating point number.\n* Every error shares one body shape: `code`, `message`, an optional\n `details` array, and a `correlation_id` you can quote to our integrations\n team.\n* List endpoints return a `data` array with `page`, `per_page`, `total` and\n `total_pages`. The event feed uses a cursor instead.\n\nThe full guide, including sandbox access and webhook verification samples,\nis published at https://www.appraisalhost.com/developers and this document is\ndownloadable at https://www.appraisalhost.com/developers/spec/openapi.json.\n", "contact": { "name": "Appraisal Host integrations team", "email": "integrations@appraisalhost.com", "url": "https://www.appraisalhost.com/developers" } }, "servers": [ { "url": "https://api.appraisalhost.com/v1", "description": "Production" }, { "url": "https://sandbox.api.appraisalhost.com/v1", "description": "Sandbox. Access is provisioned on request by our integrations team." } ], "security": [ { "bearerAuth": [] }, { "oauth2ClientCredentials": [ "lender" ] } ], "tags": [ { "name": "Service", "description": "Liveness check. No credential required." }, { "name": "Authentication", "description": "Exchange your client id and client secret for a short lived bearer token,\nthen send that token on every other call.\n" }, { "name": "Order Types", "description": "The products a lender may order from its appraisal management company, and the report format each\nproduct is delivered in. Read this before you place an order: it tells you\nwhich loan types and add-ons apply and which documents to expect back.\n" }, { "name": "Orders", "description": "Create, read, list and amend orders." }, { "name": "Order Actions", "description": "Hold, resume and cancel. These are the rules this interface enforces, and an\naction the order's current status does not allow returns 409.\n" }, { "name": "Revision Requests", "description": "Ask for a correction to a delivered report, or request a reconsideration of\nvalue, and read the company's responses.\n" }, { "name": "Messages", "description": "Exchange messages with the appraisal management company, and with the appraiser when the company allows it." }, { "name": "Documents", "description": "Upload supporting documents, list the documents on an order, and download a\ndelivered document through a signed link.\n" }, { "name": "Events", "description": "Every event we raised for your client, with its webhook delivery state. Use\nthis feed to catch up after an outage and to reconcile.\n" }, { "name": "Webhook Configuration", "description": "Read and update the endpoint we deliver your events to, and send yourself a test delivery." }, { "name": "Sandbox", "description": "Sandbox only. Move a test order through the lifecycle so that your own test\nsuite can exercise every status and every event without anyone else being\ninvolved.\n" } ], "paths": { "/ping": { "get": { "tags": [ "Service" ], "operationId": "getPing", "summary": "Liveness check", "description": "Returns 200 while the API is serving traffic. No credential is required,\nand the response never contains account data. Use it in your own\nmonitoring.\n", "security": [], "responses": { "200": { "description": "The API is serving traffic.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ping" }, "example": { "status": "ok", "time": "2026-09-17T14:32:05Z" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/oauth/token": { "post": { "tags": [ "Authentication" ], "operationId": "createToken", "summary": "Get an access token", "description": "Exchange your client id and client secret for a bearer token. The token is\nopaque, is valid for 60 minutes, and carries the `lender` scope. Request a\nnew token shortly before the old one expires, or when a call returns 401\nwith code `token_expired`. Tokens are not revoked when you request a new\none, so a rolling refresh is safe.\n\nThis is an OAuth 2.0 client credentials token endpoint. It accepts\n`application/x-www-form-urlencoded`, with `client_id` and `client_secret`\neither in the body or in an HTTP Basic header, and it also accepts a JSON\nbody of the same fields. Never place a client secret in a URL or in a\nquery string.\n\nErrors here, and only here, use the RFC 6749 shape (`error`,\n`error_description`) rather than this API's standard error body, so that a\nstandard client library can classify them. Every other endpoint answers\nwith the standard error body.\n", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/TokenRequest" }, "example": { "grant_type": "client_credentials", "client_id": "cli_example_2f8c41", "client_secret": "example_secret_do_not_use_9f4b1c77ae" } }, "application/json": { "schema": { "$ref": "#/components/schemas/TokenRequest" }, "example": { "grant_type": "client_credentials", "client_id": "cli_example_2f8c41", "client_secret": "example_secret_do_not_use_9f4b1c77ae" } } } }, "responses": { "200": { "description": "A new access token.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" }, "example": { "access_token": "aht_at_7Qk2rX9wTm4ZbN1sV6yH0pL8", "token_type": "Bearer", "expires_in": 3600, "scope": "lender" } } } }, "400": { "description": "The request is not a valid token request: a missing or unsupported\n`grant_type`, or a missing credential. RFC 6749 shape.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" }, "example": { "error": "invalid_request", "error_description": "grant_type must be client_credentials.", "correlation_id": "req_01J9Z2A7K3M5P8R1T4W6Y9B2D" } } } }, "401": { "description": "The client id or client secret is wrong, or the client has been\nrevoked. RFC 6749 shape.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" }, "example": { "error": "invalid_client", "error_description": "The client id or client secret is not valid.", "correlation_id": "req_01J9Z2A7K3M5P8R1T4W6Y9B2D" } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/account": { "get": { "tags": [ "Authentication" ], "operationId": "getAccount", "summary": "Read what this credential is for", "description": "Returns the lender account and the appraisal management company this\ncredential belongs to, the environment it works in, the scopes it carries\nand its rate limit.\n\nCall it at start-up for every credential you hold, and check `lender.id`\nand `lender.name` against your own configuration before you place an order\nwith it. A credential mapped to the wrong lender would place that lender's\nborrower on another lender's account, and this is the check that catches\nit.\n", "responses": { "200": { "description": "The account this credential belongs to.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" }, "example": { "client_id": "cli_example_2f8c41", "environment": "production", "lender": { "id": "len_4WQ2H8ZKPB31", "name": "Example Mortgage Group" }, "company": { "id": "cmp_7YT5M2XRND94", "name": "Example Appraisal Management" }, "scopes": [ "lender" ], "rate_limit": { "requests_per_minute": 600 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/order-types": { "get": { "tags": [ "Order Types" ], "operationId": "listOrderTypes", "summary": "List the products this lender may order", "description": "Returns the order types available to your lender account, the report\nformat each one is delivered in, and, for products on the current report\nstandard, the loan types and add-ons that may be attached.\n\nRead this endpoint before you place an order. It is the only place that\ntells you, in advance, which documents will come back and which\n`loan_type_code` and `add_on_codes` values the product accepts. Codes are\nstable for each appraisal management company; names are display text and may be reworded. The list is\nordered by `code`, ascending.\n\nA product this lender is not entitled to order does not appear here at\nall. A product the company has withdrawn appears with `active: false` and\ncannot be ordered.\n", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "name": "has_adu", "in": "query", "required": false, "description": "Which add-ons to list. The default, false, lists the add-ons that\napply to a property without an accessory dwelling unit. True lists\nthose same add-ons plus the ones that apply only when the property has\none.\n", "schema": { "type": "boolean", "default": false } }, { "name": "report_format", "in": "query", "required": false, "description": "Return only order types delivered in this report format.", "schema": { "$ref": "#/components/schemas/ReportFormat" } } ], "responses": { "200": { "description": "The order types available to your lender account.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderTypeList" }, "example": { "data": [ { "code": "SFR-1004-36", "name": "Single Family Residential, current report standard", "report_format": "uad_3_6", "appraiser_certification": "none", "active": true, "loan_types": [ { "code": "conventional", "name": "Conventional" }, { "code": "conventional_new_construction", "name": "Conventional, New Construction" }, { "code": "va", "name": "VA" } ], "add_ons": [ { "code": "rent_schedule", "name": "Rent Schedule" }, { "code": "operating_income_statement", "name": "Operating Income Statement" } ], "loan_purposes": [], "property_types": [ "single_family", "condominium", "townhouse", "two_to_four_unit_property" ] }, { "code": "SFR-1004-FHA", "name": "Single Family Residential, FHA", "report_format": "uad_3_6", "appraiser_certification": "fha_required", "active": true, "loan_types": [ { "code": "fha", "name": "FHA" } ], "add_ons": [], "loan_purposes": [], "property_types": [ "single_family", "condominium", "townhouse" ] }, { "code": "DRIVEBY-2055", "name": "Exterior Only Inspection", "report_format": "uad_2_6", "appraiser_certification": "none", "active": true, "loan_types": [], "add_ons": [ { "code": "rent_schedule", "name": "Rent Schedule" } ], "loan_purposes": [ "purchase" ], "property_types": [] } ], "page": 1, "per_page": 25, "total": 3, "total_pages": 1 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/orders": { "post": { "tags": [ "Orders" ], "operationId": "createOrder", "summary": "Place an order", "description": "Places a new appraisal order for your lender account at its appraisal management company.\n\nSend `order_type_code` from `GET /order-types`. For a product on the\ncurrent report standard, also send `loan_type_code`, and `add_on_codes`\nwhen you need them: both are validated against the product, and an unknown\nor inapplicable code is refused with 422 rather than being guessed at.\n\n`property.postal_code` is required. City, state and county are filled in\nfrom the postal code when you leave them out.\n\nAlways send an `Idempotency-Key`. We keep the key for 24 hours: a repeat of\nthe same key with the same body returns the original order instead of\ncreating a second one, and a repeat with a different body is refused with\n409 and code `idempotency_key_reused`.\n\nA create returns 201 and the order. An order we can place straight away is\nat `new` and stays there until the appraisal management company assigns an\nappraiser. An order that needs a review by the company first, for example\nan unusual product, loan type or property, is at `pending_review` and moves\nto `new` when the company places it. Both are normal, and you will see\n`order.status_changed` when the order moves on. A request we can refuse\ndeterministically, such as an unknown code or a code that does not apply to\nthe product, is refused with 422 instead and no order is created.\n\nWe never accept card details. API ordering requires a lender account the\nappraisal management company invoices. An account that pays for each order\nby card is refused with 403 and code `account_not_billable`: ask the\ncompany to put the account on invoicing first.\n", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderCreate" }, "examples": { "currentStandard": { "summary": "A product on the current report standard, with a loan type and an add-on", "value": { "order_type_code": "SFR-1004-36", "loan_type_code": "conventional", "add_on_codes": [ "rent_schedule" ], "due_date": "2026-10-02", "rush": false, "complex": false, "rural": false, "priority": false, "certified_appraiser_required": true, "appraiser_instructions": "Gate code 4417. Call the listing agent for access.", "lender_reference": "LN-2026-88421", "loan": { "purpose": "purchase", "number": "88421", "client": "Example Mortgage Group", "investor": "Example Investor Trust", "purchase_price": "415000.00", "currency": "USD" }, "property": { "address": { "street": "100 Example Avenue", "unit": "Unit 2", "city": "Springfield", "state": "IL", "postal_code": "62701", "county": "Sangamon" }, "type": "single_family", "occupancy": "primary_residence", "has_adu": true }, "borrowers": [ { "role": "borrower", "first_name": "Sample", "last_name": "Borrower", "receives_report": false, "receives_status_updates": true, "address": { "street": "300 Example Street", "city": "Springfield", "state": "IL", "postal_code": "62703" }, "contacts": [ { "type": "email", "role": "home", "value": "sample.borrower@example.com" }, { "type": "phone", "role": "cell", "value": "+1-217-555-0142" } ] }, { "role": "co_borrower", "first_name": "Second", "last_name": "Borrower", "contacts": [ { "type": "phone", "role": "work", "value": "+1-217-555-0143" } ] } ], "parties": { "real_estate_agent": { "first_name": "Sample", "last_name": "Agent", "contacts": [ { "type": "phone", "role": "cell", "value": "+1-217-555-0190" } ] }, "additional_contacts": [ { "purpose": "status", "name": "Processing Desk", "email": "processing@example.com" }, { "purpose": "report", "name": "Closing Desk", "email": "closing@example.com" } ] }, "notes": [ { "type": "order", "text": "Borrower prefers a morning appointment." }, { "type": "appointment", "text": "Dog on the property, please call ahead." } ] } }, "priorStandard": { "summary": "A product on the prior report standard, minimum fields", "value": { "order_type_code": "DRIVEBY-2055", "due_date": "2026-09-30", "loan": { "purpose": "refinance", "number": "88422" }, "property": { "address": { "street": "200 Example Lane", "postal_code": "62704" }, "type": "condominium", "occupancy": "second_home" }, "borrowers": [ { "role": "borrower", "first_name": "Example", "last_name": "Borrower", "contacts": [ { "type": "email", "role": "home", "value": "example.borrower@example.com" } ] } ] } } } } } }, "responses": { "201": { "description": "The order was created.", "headers": { "Location": { "description": "The URL of the new order.", "schema": { "type": "string", "format": "uri" } }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "example": { "id": "ord_9TBK4C2QFA7M", "order_number": "2026-1043", "lender_reference": "LN-2026-88421", "status": { "code": "new", "label": "New Order", "changed_at": "2026-09-17T14:32:05Z" }, "order_type": { "code": "SFR-1004-36", "name": "Single Family Residential, current report standard", "report_format": "uad_3_6", "appraiser_certification": "none" }, "loan": { "purpose": "purchase", "purpose_other": null, "number": "88421", "client": "Example Mortgage Group", "investor": "Example Investor Trust", "agency_case_number": null, "fha_case_number": null, "purchase_price": "415000.00", "currency": "USD", "loan_type": { "code": "conventional", "name": "Conventional" }, "add_ons": [ { "code": "rent_schedule", "name": "Rent Schedule" } ] }, "property": { "address": { "street": "100 Example Avenue", "unit": "Unit 2", "city": "Springfield", "state": "IL", "postal_code": "62701", "county": "Sangamon" }, "type": "single_family", "occupancy": "primary_residence", "has_adu": true }, "borrowers": [ { "role": "borrower", "first_name": "Sample", "last_name": "Borrower", "receives_report": false, "receives_status_updates": true, "address": { "street": "300 Example Street", "city": "Springfield", "state": "IL", "postal_code": "62703", "county": "Sangamon" }, "contacts": [ { "type": "email", "role": "home", "value": "sample.borrower@example.com" }, { "type": "phone", "role": "cell", "value": "+1-217-555-0142" } ] }, { "role": "co_borrower", "first_name": "Second", "last_name": "Borrower", "receives_report": false, "receives_status_updates": false, "address": null, "contacts": [ { "type": "phone", "role": "work", "value": "+1-217-555-0143" } ] } ], "parties": { "real_estate_agent": { "first_name": "Sample", "last_name": "Agent", "contacts": [ { "type": "phone", "role": "cell", "value": "+1-217-555-0190" } ] }, "additional_contacts": [ { "purpose": "status", "name": "Processing Desk", "email": "processing@example.com" }, { "purpose": "report", "name": "Closing Desk", "email": "closing@example.com" } ] }, "notes": [ { "type": "order", "text": "Borrower prefers a morning appointment." }, { "type": "appointment", "text": "Dog on the property, please call ahead." } ], "flags": { "rush": false, "complex": false, "rural": false, "priority": false, "certified_appraiser_required": true }, "appraiser_instructions": "Gate code 4417. Call the listing agent for access.", "appraiser": null, "dates": { "created_at": "2026-09-17T14:32:05Z", "updated_at": "2026-09-17T14:32:05Z", "due_date": "2026-10-02", "appointment_at": null, "completed_at": null }, "fees": { "appraisal_fee": "525.00", "currency": "USD" }, "documents": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The credential is valid but this account cannot place orders through\nthe API: it pays for each order by card rather than being invoiced.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "account_not_billable", "message": "This lender account is billed per order by card and cannot order through the API.", "correlation_id": "req_01J9Z2CF8H4N7Q0S3V6X9A2C5" } } } }, "409": { "description": "The `Idempotency-Key` was already used with a different body.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "idempotency_key_reused", "message": "This Idempotency-Key was used for a different request within the last 24 hours.", "correlation_id": "req_01J9Z2CF8H4N7Q0S3V6X9A2C5" } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "get": { "tags": [ "Orders" ], "operationId": "listOrders", "summary": "List orders", "description": "Returns the orders that belong to your lender account, ordered by\n`created_at` descending with `id` as the tie break.\n\nFilter by one or more status codes, and by `updated_since` to poll for\nchange. `updated_since` is inclusive to the second, so overlap your\nwindows by a second or two rather than trusting exact boundaries.\nWebhooks remain the primary way to learn about change: this endpoint is\nfor reconciliation and for catching up.\n\nPage numbers walk a collection that can change while you read it, so an\norder touched between your first page and your last can move. Walk every\npage quickly, then run the same window again and compare the two runs:\nwhen they agree, nothing moved underneath you.\n", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "name": "status", "in": "query", "required": false, "description": "One or more status codes, comma separated. See the status catalog in\nthe schema `OrderStatusCode`.\n", "schema": { "type": "string", "examples": [ "report_complete,revised_report_complete" ] } }, { "name": "updated_since", "in": "query", "required": false, "description": "Return only orders changed at or after this instant. `updated_at`\nmoves when anything you can see on the order changes: its status, its\ndates, its fee, its documents, its messages and its own fields.\n", "schema": { "type": "string", "format": "date-time", "examples": [ "2026-09-17T00:00:00Z" ] } }, { "name": "order_number", "in": "query", "required": false, "description": "Return the order carrying this order number from the appraisal management company.", "schema": { "type": "string", "examples": [ "2026-1043" ] } }, { "name": "lender_reference", "in": "query", "required": false, "description": "Return orders carrying this reference of yours.", "schema": { "type": "string", "examples": [ "LN-2026-88421" ] } } ], "responses": { "200": { "description": "A page of orders.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderList" }, "example": { "data": [ { "id": "ord_9TBK4C2QFA7M", "order_number": "2026-1043", "lender_reference": "LN-2026-88421", "status": { "code": "appraiser_assigned", "label": "Appraiser Assigned", "changed_at": "2026-09-18T13:04:11Z" }, "order_type": { "code": "SFR-1004-36", "name": "Single Family Residential, current report standard", "report_format": "uad_3_6", "appraiser_certification": "none" }, "property_address_summary": "100 Example Avenue, Springfield, IL 62701", "dates": { "created_at": "2026-09-17T14:32:05Z", "updated_at": "2026-09-18T13:04:11Z", "due_date": "2026-10-02", "appointment_at": null, "completed_at": null } } ], "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/orders/{order_id}": { "parameters": [ { "$ref": "#/components/parameters/OrderIdPath" } ], "get": { "tags": [ "Orders" ], "operationId": "getOrder", "summary": "Read an order", "description": "Returns the full order, its current status, the documents on it, and the\nfee the lender is charged. You see exactly what the lender sees in the\nportal, with the same status wording, and nothing more.\n", "responses": { "200": { "description": "The order.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "example": { "id": "ord_9TBK4C2QFA7M", "order_number": "2026-1043", "lender_reference": "LN-2026-88421", "status": { "code": "report_complete", "label": "Report Complete", "changed_at": "2026-09-29T18:12:44Z" }, "order_type": { "code": "SFR-1004-36", "name": "Single Family Residential, current report standard", "report_format": "uad_3_6", "appraiser_certification": "none" }, "loan": { "purpose": "purchase", "purpose_other": null, "number": "88421", "client": "Example Mortgage Group", "investor": "Example Investor Trust", "agency_case_number": null, "fha_case_number": null, "purchase_price": "415000.00", "currency": "USD", "loan_type": { "code": "conventional", "name": "Conventional" }, "add_ons": [ { "code": "rent_schedule", "name": "Rent Schedule" } ] }, "property": { "address": { "street": "100 Example Avenue", "unit": "Unit 2", "city": "Springfield", "state": "IL", "postal_code": "62701", "county": "Sangamon" }, "type": "single_family", "occupancy": "primary_residence", "has_adu": true }, "borrowers": [ { "role": "borrower", "first_name": "Sample", "last_name": "Borrower", "receives_report": false, "receives_status_updates": true, "address": null, "contacts": [ { "type": "email", "role": "home", "value": "sample.borrower@example.com" } ] } ], "parties": { "real_estate_agent": null, "additional_contacts": [] }, "notes": [ { "type": "order", "text": "Borrower prefers a morning appointment." } ], "flags": { "rush": false, "complex": false, "rural": false, "priority": false, "certified_appraiser_required": true }, "appraiser_instructions": "Gate code 4417. Call the listing agent for access.", "appraiser": { "name": "J. Marsh" }, "dates": { "created_at": "2026-09-17T14:32:05Z", "updated_at": "2026-09-29T18:12:44Z", "due_date": "2026-10-02", "appointment_at": "2026-09-22T15:00:00Z", "completed_at": "2026-09-29T18:12:44Z" }, "fees": { "appraisal_fee": "525.00", "currency": "USD" }, "documents": [ { "id": "doc_3XH8M1PLQW60", "kind": "report_pdf", "filename": "report_2026-1043.pdf", "content_type": "application/pdf", "size_bytes": 2841773, "created_at": "2026-09-29T18:12:44Z" }, { "id": "doc_5RJ2N7VKTB41", "kind": "report_data", "filename": "report_2026-1043.zip", "content_type": "application/zip", "size_bytes": 1044210, "created_at": "2026-09-29T18:12:44Z" }, { "id": "doc_8QL4P9WMYC72", "kind": "invoice", "filename": "invoice_2026-1043.pdf", "content_type": "application/pdf", "size_bytes": 88120, "created_at": "2026-09-29T18:12:45Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "patch": { "tags": [ "Orders" ], "operationId": "updateOrder", "summary": "Amend an order", "description": "Amends the parts of an open order a lender may change: the loan number and\nyour own reference, the contacts and parties, the notes, the appraiser\ninstructions, and a request to move the due date.\n\nA due date you send is a REQUEST. The appraisal management company confirms\nor adjusts it, and the date on the order changes only when the company\naccepts it. Watch\n`order.due_date_changed` for the outcome.\n\nThe property, the borrower names, the order type, the loan type and the\nadd-ons cannot be changed once an order exists. Cancel the order and place\na new one instead. Amending a closed order is refused with 409.\n\nSome companies do not let a lender amend an order at all. Then the call is\nrefused with 403 and code `action_not_permitted_for_client`, and the way to\nask is a message on the order.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPatch" }, "example": { "lender_reference": "LN-2026-88421-R2", "loan": { "number": "88421-A" }, "due_date": "2026-10-06", "appraiser_instructions": "New gate code 8891.", "notes": [ { "type": "appointment", "text": "Borrower now prefers afternoons." } ], "parties": { "additional_contacts": [ { "purpose": "status", "name": "Processing Desk", "email": "processing2@example.com" } ] } } } } }, "responses": { "200": { "description": "The amended order.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "example": { "id": "ord_9TBK4C2QFA7M", "order_number": "2026-1043", "lender_reference": "LN-2026-88421-R2", "status": { "code": "appraiser_assigned", "label": "Appraiser Assigned", "changed_at": "2026-09-18T13:04:11Z" }, "order_type": { "code": "SFR-1004-36", "name": "Single Family Residential, current report standard", "report_format": "uad_3_6", "appraiser_certification": "none" }, "loan": { "purpose": "purchase", "purpose_other": null, "number": "88421-A", "client": "Example Mortgage Group", "investor": "Example Investor Trust", "agency_case_number": null, "fha_case_number": null, "purchase_price": "415000.00", "currency": "USD", "loan_type": { "code": "conventional", "name": "Conventional" }, "add_ons": [] }, "property": { "address": { "street": "100 Example Avenue", "unit": "Unit 2", "city": "Springfield", "state": "IL", "postal_code": "62701", "county": "Sangamon" }, "type": "single_family", "occupancy": "primary_residence", "has_adu": true }, "borrowers": [], "parties": { "real_estate_agent": null, "additional_contacts": [ { "purpose": "status", "name": "Processing Desk", "email": "processing2@example.com" } ] }, "notes": [ { "type": "appointment", "text": "Borrower now prefers afternoons." } ], "flags": { "rush": false, "complex": false, "rural": false, "priority": false, "certified_appraiser_required": true }, "appraiser_instructions": "New gate code 8891.", "appraiser": { "name": "J. Marsh" }, "dates": { "created_at": "2026-09-17T14:32:05Z", "updated_at": "2026-09-19T09:15:00Z", "due_date": "2026-10-02", "appointment_at": null, "completed_at": null }, "fees": { "appraisal_fee": "525.00", "currency": "USD" }, "documents": [] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/orders/{order_id}/hold": { "parameters": [ { "$ref": "#/components/parameters/OrderIdPath" } ], "post": { "tags": [ "Order Actions" ], "operationId": "holdOrder", "summary": "Place an order on hold", "description": "Puts an open order on hold and stands the appraiser down. The appraiser is\nremembered, so resuming puts the order back where it was.\n\nA hold is allowed while the order is open, is not already on hold, and no\nreport has been delivered. It is refused with 409 when the report has been\ndelivered (`report_complete`, `revised_report_complete`), a correction is\nopen (`revision_requested`), the order is cancelled, or it is already on\nhold.\n\nSend a reason: the appraisal management company and the appraiser both see\nit.\n", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionRequest" }, "example": { "reason": "Borrower is renegotiating the purchase price." } } } }, "responses": { "200": { "description": "The order is on hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderActionResult" }, "example": { "id": "ord_9TBK4C2QFA7M", "order_number": "2026-1043", "status": { "code": "on_hold", "label": "On Hold", "changed_at": "2026-09-19T11:02:00Z" }, "previous_status": { "code": "appraiser_assigned", "label": "Appraiser Assigned" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The order's current status does not allow a hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "action_not_allowed_in_status", "message": "An order with a delivered report cannot be placed on hold.", "current_status": "report_complete", "details": [ { "field": "status", "code": "current_status", "value": "report_complete", "message": "The report has already been delivered." } ], "correlation_id": "req_01J9Z3B2D5F8H1K4M7P0R3T6" } } } }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/orders/{order_id}/resume": { "parameters": [ { "$ref": "#/components/parameters/OrderIdPath" } ], "post": { "tags": [ "Order Actions" ], "operationId": "resumeOrder", "summary": "Take an order off hold", "description": "Returns an order from hold to the point it had reached, and puts the\nremembered appraiser back on it. A resume is allowed while the order is on\nhold; any other status is refused with 409.\n\nThe order comes back at `off_hold`, which is transitional: it moves on to\nits working status shortly afterwards, so read the order again rather than\ntreating `off_hold` as a resting state.\n", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionRequest" }, "example": { "reason": "Purchase price agreed, please proceed." } } } }, "responses": { "200": { "description": "The order has resumed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderActionResult" }, "example": { "id": "ord_9TBK4C2QFA7M", "order_number": "2026-1043", "status": { "code": "off_hold", "label": "Off Hold", "changed_at": "2026-09-22T08:40:12Z" }, "previous_status": { "code": "on_hold", "label": "On Hold" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The order is not on hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "action_not_allowed_in_status", "message": "Only an order that is on hold can be resumed.", "current_status": "appraiser_assigned", "details": [ { "field": "status", "code": "current_status", "value": "appraiser_assigned", "message": "The order is not on hold." } ], "correlation_id": "req_01J9Z3C4F7H0K3M6P9R2T5W8" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/orders/{order_id}/cancel": { "parameters": [ { "$ref": "#/components/parameters/OrderIdPath" } ], "post": { "tags": [ "Order Actions" ], "operationId": "cancelOrder", "summary": "Cancel an order", "description": "Cancels an open order. A cancellation is allowed while the order is open\nand no report has been delivered. It is refused with 409 when the report\nhas been delivered, a correction is open, or the order is already\ncancelled. A held order must be resumed first.\n\nSome companies do not allow a lender to cancel at all. In that case the\ncall is refused with 403 and code `action_not_permitted_for_client`, and\nthe way to ask is a message on the order.\n", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionRequest" }, "example": { "reason": "Loan withdrawn by the borrower." } } } }, "responses": { "200": { "description": "The order is cancelled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderActionResult" }, "example": { "id": "ord_9TBK4C2QFA7M", "order_number": "2026-1043", "status": { "code": "cancelled", "label": "Order Cancelled", "changed_at": "2026-09-20T16:22:31Z" }, "previous_status": { "code": "appointment_scheduled", "label": "Appointment Scheduled" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The order's current status does not allow a cancellation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "action_not_allowed_in_status", "message": "An order with a delivered report cannot be cancelled.", "current_status": "report_complete", "details": [ { "field": "status", "code": "current_status", "value": "report_complete", "message": "The report has already been delivered." } ], "correlation_id": "req_01J9Z3D6H9K2M5P8R1T4W7Y0" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/orders/{order_id}/revision-requests": { "parameters": [ { "$ref": "#/components/parameters/OrderIdPath" } ], "post": { "tags": [ "Revision Requests" ], "operationId": "createRevisionRequest", "summary": "Request a correction or a reconsideration of value", "description": "Opens a revision request against a delivered report.\n\nTwo kinds are accepted. A `correction` asks the appraiser to fix or\nclarify something in the report. A `reconsideration_of_value` asks the\nappraiser to reconsider the opinion of value, and requires at least one\nacknowledgement: that a prior appraisal was provided, or that comparable\nsales were provided. Attach the sales or the prior report with\n`POST /orders/{order_id}/documents` before you open the request, or send\nthem inline.\n\nA request is accepted while the order is at `report_complete`,\n`revised_report_complete`, `revision_requested`,\n`reconsideration_requested` or `cancelled`. In any other status it is\nrefused with 409.\n\nWe fill the rest of the record the appraisal management company needs from\nthe order and your credential. If the order has no loan number, send\n`loan.number` on the order first.\n\nThe appraisal management company may review the request before it reaches the appraiser. A request\ntherefore starts at `submitted` and moves to `accepted` or `declined`.\nWatch `order.revision_requested` and `order.revision_responded`.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionRequestCreate" }, "examples": { "correction": { "summary": "A correction", "value": { "kind": "correction", "reason": "The gross living area on page 2 does not match the sketch." } }, "reconsideration": { "summary": "A reconsideration of value with acknowledgements", "value": { "kind": "reconsideration_of_value", "reason": "Three closed sales within 0.4 miles support a higher value.", "acknowledgements": { "prior_appraisal_provided": false, "comparable_sales_provided": true }, "document_ids": [ "doc_2KM7Q0VZTC93" ] } } } } } }, "responses": { "201": { "description": "The revision request was opened.", "headers": { "Location": { "description": "The URL of the revision request collection for this order.", "schema": { "type": "string", "format": "uri" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionRequest" }, "example": { "id": "rr_6PD3K8YWQN25", "order_id": "ord_9TBK4C2QFA7M", "kind": "reconsideration_of_value", "status": "submitted", "reason": "Three closed sales within 0.4 miles support a higher value.", "acknowledgements": { "prior_appraisal_provided": false, "comparable_sales_provided": true }, "documents": [ { "id": "doc_2KM7Q0VZTC93", "kind": "supporting", "filename": "comparable_sales.pdf", "content_type": "application/pdf", "size_bytes": 412998, "created_at": "2026-09-30T10:02:00Z" } ], "responses": [], "created_at": "2026-09-30T10:04:18Z", "updated_at": "2026-09-30T10:04:18Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The order's current status does not allow a revision request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "action_not_allowed_in_status", "message": "A revision request can be opened only once a report has been delivered.", "current_status": "appraiser_assigned", "details": [ { "field": "status", "code": "current_status", "value": "appraiser_assigned", "message": "No report has been delivered on this order yet." } ], "correlation_id": "req_01J9Z3F8K1M4P7R0T3W6Y9B2" } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "get": { "tags": [ "Revision Requests" ], "operationId": "listRevisionRequests", "summary": "List the revision requests on an order", "description": "Returns every revision request on the order, ordered by `created_at`\ndescending with `id` as the tie break, with the company's responses and any\ndocuments attached on either side.\n", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" } ], "responses": { "200": { "description": "A page of revision requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionRequestList" }, "example": { "data": [ { "id": "rr_6PD3K8YWQN25", "order_id": "ord_9TBK4C2QFA7M", "kind": "reconsideration_of_value", "status": "accepted", "reason": "Three closed sales within 0.4 miles support a higher value.", "acknowledgements": { "prior_appraisal_provided": false, "comparable_sales_provided": true }, "documents": [], "responses": [ { "id": "msg_4NF9R2XWTD86", "created_at": "2026-09-30T15:41:00Z", "author": { "type": "manager", "name": "Order Desk" }, "message": "Sent to the appraiser for review. Revised report expected within two business days." } ], "created_at": "2026-09-30T10:04:18Z", "updated_at": "2026-09-30T15:41:00Z" } ], "page": 1, "per_page": 25, "total": 1, "total_pages": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/orders/{order_id}/messages": { "parameters": [ { "$ref": "#/components/parameters/OrderIdPath" } ], "get": { "tags": [ "Messages" ], "operationId": "listMessages", "summary": "Read the message thread on an order", "description": "Returns the messages on the order that the lender is party to, ordered by\n`created_at` ascending, with their attachments. Internal notes between the\ncompany and the appraiser are not included: you see the thread the lender\nsees in the portal.\n", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" } ], "responses": { "200": { "description": "A page of messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageList" }, "example": { "data": [ { "id": "msg_7SG1T4ZXUE07", "order_id": "ord_9TBK4C2QFA7M", "recipient": "manager", "subject": "Access arrangements", "body": "The listing agent will meet the appraiser on site.", "author": { "type": "lender", "name": "Example Mortgage Group" }, "attachments": [], "created_at": "2026-09-18T15:10:00Z" }, { "id": "msg_8TH2U5AYVF18", "order_id": "ord_9TBK4C2QFA7M", "recipient": "lender", "subject": "Access arrangements", "body": "Understood. The appraiser will call the agent to confirm.", "author": { "type": "manager", "name": "Order Desk" }, "attachments": [], "created_at": "2026-09-18T16:02:00Z" } ], "page": 1, "per_page": 25, "total": 2, "total_pages": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "tags": [ "Messages" ], "operationId": "createMessage", "summary": "Post a message on an order", "description": "Sends a message to the appraisal management company, or to the appraiser\nwhen the company allows direct contact. `recipient` must be `manager` or\n`appraiser`; a company that keeps appraiser contact in its own hands\nrefuses `appraiser` with 422 and code `recipient_not_allowed`.\n\nAttach a document by uploading it first and quoting its id, or send the\nmessage on its own.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageCreate" }, "example": { "recipient": "manager", "subject": "Access arrangements", "body": "The listing agent will meet the appraiser on site.", "document_ids": [] } } } }, "responses": { "201": { "description": "The message was posted.", "headers": { "Location": { "description": "The URL of the message thread for this order.", "schema": { "type": "string", "format": "uri" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" }, "example": { "id": "msg_7SG1T4ZXUE07", "order_id": "ord_9TBK4C2QFA7M", "recipient": "manager", "subject": "Access arrangements", "body": "The listing agent will meet the appraiser on site.", "author": { "type": "lender", "name": "Example Mortgage Group" }, "attachments": [], "created_at": "2026-09-18T15:10:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/orders/{order_id}/documents": { "parameters": [ { "$ref": "#/components/parameters/OrderIdPath" } ], "get": { "tags": [ "Documents" ], "operationId": "listOrderDocuments", "summary": "List the documents on an order", "description": "Returns every document on the order that the lender may see, ordered by\n`created_at` descending with `id` as the tie break, as summaries without a\ndownload link. Ask for a link one document at a\ntime with `GET /documents/{document_id}`, so that links are short lived\nand are only minted when you are about to use them.\n\nWhich documents arrive depends on the product's report format. A product\non the prior report standard delivers the report as a PDF plus the report\ndata as an XML file. A product on the current standard delivers the report\nas a PDF plus the report data as a package in ZIP form. In both cases the\ninvoice, the certificates and any other delivery document are separate\nfiles: the package never contains them.\n", "parameters": [ { "$ref": "#/components/parameters/PageParam" }, { "$ref": "#/components/parameters/PerPageParam" }, { "name": "kind", "in": "query", "required": false, "description": "Return only documents of this kind.", "schema": { "$ref": "#/components/schemas/DocumentKind" } } ], "responses": { "200": { "description": "A page of document summaries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentList" }, "example": { "data": [ { "id": "doc_3XH8M1PLQW60", "kind": "report_pdf", "filename": "report_2026-1043.pdf", "content_type": "application/pdf", "size_bytes": 2841773, "created_at": "2026-09-29T18:12:44Z" }, { "id": "doc_5RJ2N7VKTB41", "kind": "report_data", "filename": "report_2026-1043.zip", "content_type": "application/zip", "size_bytes": 1044210, "created_at": "2026-09-29T18:12:44Z" }, { "id": "doc_8QL4P9WMYC72", "kind": "invoice", "filename": "invoice_2026-1043.pdf", "content_type": "application/pdf", "size_bytes": 88120, "created_at": "2026-09-29T18:12:45Z" } ], "page": 1, "per_page": 25, "total": 3, "total_pages": 1 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "tags": [ "Documents" ], "operationId": "uploadOrderDocument", "summary": "Upload a supporting document", "description": "Uploads a document to an open order: a purchase and sale contract, an\nengagement letter, comparable sales for a reconsideration, or anything\nelse the appraiser needs.\n\nA document you upload is visible to the appraisal management company and\nto the assigned appraiser. Send `purpose` to say what it is:\n`engagement_letter`, `sales_contract`, `prior_report` or `other`.\n\nSend `multipart/form-data` with a `file` part and a `kind` part. The limit\nis 25 MB per file; a larger file is refused with 413. Accepted media types\nare PDF, JPEG, PNG, TIFF, ZIP, plain text, XML, and the common office\ndocument types; anything else is refused with 415. `kind` must be\n`supporting` on an upload: a report, a report data file, an invoice or a\ncertificate is produced by the appraisal management company, never uploaded by a lender.\n", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DocumentUpload" }, "example": { "file": "(the bytes of purchase_and_sale.pdf)", "kind": "supporting", "purpose": "sales_contract", "description": "Purchase and sale contract" } } } }, "responses": { "201": { "description": "The document was stored on the order.", "headers": { "Location": { "description": "The URL of the new document.", "schema": { "type": "string", "format": "uri" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentSummary" }, "example": { "id": "doc_2KM7Q0VZTC93", "kind": "supporting", "filename": "purchase_and_sale.pdf", "content_type": "application/pdf", "size_bytes": 412998, "created_at": "2026-09-17T14:40:11Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/documents/{document_id}": { "parameters": [ { "$ref": "#/components/parameters/DocumentIdPath" } ], "get": { "tags": [ "Documents" ], "operationId": "getDocument", "summary": "Get a document and a link to download it", "description": "Returns the document's details and a signed download link that is valid\nfor five minutes and may be used more than once inside that window. Follow\nthe link with a plain GET and no credential of ours: the signature in the\nlink is the authorization. The `expires` value in the link is `expires_at`\nin Unix seconds. Fetch a fresh link when one expires rather than storing\nlinks.\n\nA document you are not entitled to see returns 404, not 403, so that ids\ncannot be probed.\n", "responses": { "200": { "description": "The document, with a signed link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" }, "example": { "id": "doc_5RJ2N7VKTB41", "order_id": "ord_9TBK4C2QFA7M", "kind": "report_data", "filename": "report_2026-1043.zip", "content_type": "application/zip", "size_bytes": 1044210, "created_at": "2026-09-29T18:12:44Z", "download": { "url": "https://api.appraisalhost.com/v1/download/doc_5RJ2N7VKTB41?expires=1790705864&signature=4f1c8e2b9a7d5c3f6e0b8a2d4c6f1e9b", "expires_at": "2026-09-29T18:17:44Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/events": { "get": { "tags": [ "Events" ], "operationId": "listEvents", "summary": "Read your event feed", "description": "Returns the events we raised for your client, ordered by `created_at`\nascending, which is also event id order, each with its webhook delivery\nstate. This is the catch-up feed: if your endpoint was\ndown, read forward from the last event id you processed and you will miss\nnothing.\n\nThis endpoint uses a cursor rather than page numbers. Pass the last id you\nprocessed as `after`, and keep reading while `next_cursor` is not null.\nEvents are retained for 30 days.\n", "parameters": [ { "name": "after", "in": "query", "required": false, "description": "Return events after this event id. Omit to start at the oldest retained event.", "schema": { "type": "string", "examples": [ "evt_01M2T9W27R459H4DHVZGW4WNSS" ] } }, { "name": "type", "in": "query", "required": false, "description": "One or more event types, comma separated.", "schema": { "type": "string", "examples": [ "order.status_changed,order.completed" ] } }, { "name": "order_id", "in": "query", "required": false, "description": "Return only events for this order.", "schema": { "type": "string", "examples": [ "ord_9TBK4C2QFA7M" ] } }, { "name": "delivery_status", "in": "query", "required": false, "description": "Return only events in this delivery state.", "schema": { "$ref": "#/components/schemas/DeliveryStatus" } }, { "$ref": "#/components/parameters/PerPageParam" } ], "responses": { "200": { "description": "A page of events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventList" }, "example": { "data": [ { "id": "evt_01M2T9W27R459H4DHVZGW4WNSS", "type": "order.status_changed", "created_at": "2026-09-18T13:04:11Z", "order_id": "ord_9TBK4C2QFA7M", "data": { "order_id": "ord_9TBK4C2QFA7M", "order_number": "2026-1043", "status": { "code": "appraiser_assigned", "label": "Appraiser Assigned", "changed_at": "2026-09-18T13:04:11Z" }, "previous_status": { "code": "new", "label": "New Order" } }, "delivery": { "status": "delivered", "attempts": 1, "last_attempt_at": "2026-09-18T13:04:13Z", "next_attempt_at": null, "last_response_status": 200 } }, { "id": "evt_01M3Q5WZA8V0AB3B4S4B8E3XC5", "type": "order.completed", "created_at": "2026-09-29T18:12:45Z", "order_id": "ord_9TBK4C2QFA7M", "data": { "order_id": "ord_9TBK4C2QFA7M", "order_number": "2026-1043", "report_format": "uad_3_6", "documents": [ { "id": "doc_3XH8M1PLQW60", "kind": "report_pdf", "filename": "report_2026-1043.pdf", "content_type": "application/pdf", "size_bytes": 2841773, "created_at": "2026-09-29T18:12:44Z" }, { "id": "doc_5RJ2N7VKTB41", "kind": "report_data", "filename": "report_2026-1043.zip", "content_type": "application/zip", "size_bytes": 1044210, "created_at": "2026-09-29T18:12:44Z" }, { "id": "doc_8QL4P9WMYC72", "kind": "invoice", "filename": "invoice_2026-1043.pdf", "content_type": "application/pdf", "size_bytes": 88120, "created_at": "2026-09-29T18:12:45Z" } ], "completed_at": "2026-09-29T18:12:44Z" }, "delivery": { "status": "failed", "attempts": 3, "last_attempt_at": "2026-09-29T18:48:02Z", "next_attempt_at": "2026-09-29T20:48:02Z", "last_response_status": 502 } } ], "next_cursor": "evt_01M3Q5WZA8V0AB3B4S4B8E3XC5" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/sandbox/orders/{order_id}/advance": { "parameters": [ { "$ref": "#/components/parameters/OrderIdPath" } ], "post": { "tags": [ "Sandbox" ], "operationId": "advanceSandboxOrder", "summary": "Move a sandbox order to another status", "description": "Moves one of your sandbox orders to the status you name and raises\neverything a real move raises: the same events, the same payloads, the\nsame signed deliveries to your endpoint.\n\nThree rules govern it.\n\n* It exists in the sandbox environment only. The same path in production\n returns 404.\n* The transition table below is the whole rule for `to_status`. You may\n skip statuses, because a real order often does. You may not move an\n order backwards, you may not name the status the order is already at,\n and you may not reach `pending_review`, `revision_requested`,\n `reconsideration_requested`, `on_hold`, `off_hold`, `cancelled` or\n `reactivated` this way: those are produced by `POST /orders`, by\n `POST /orders/{order_id}/revision-requests`, and by `hold`, `resume`\n and `cancel`, which work in the sandbox exactly as they do in\n production. A move the table does not list is refused with 409 and\n code `action_not_allowed_in_status`, with the order's current status in\n `current_status` and the status you asked for in `details[0].value`.\n* It fires the same notifications production fires.\n\n| Current status | `to_status` you may name |\n|---|---|\n| `pending_review` | `new` |\n| `new` | `appraiser_assigned`, `appraiser_accepted`, `borrower_contacted`, `left_message_for_borrower`, `appointment_scheduled`, `awaiting_review`, `report_rejected_for_correction`, `report_complete` |\n| `appraiser_assigned` | `appraiser_accepted`, `borrower_contacted`, `left_message_for_borrower`, `appointment_scheduled`, `awaiting_review`, `report_rejected_for_correction`, `report_complete` |\n| `appraiser_accepted` | `borrower_contacted`, `left_message_for_borrower`, `appointment_scheduled`, `awaiting_review`, `report_rejected_for_correction`, `report_complete` |\n| `borrower_contacted` | `left_message_for_borrower`, `appointment_scheduled`, `awaiting_review`, `report_rejected_for_correction`, `report_complete` |\n| `left_message_for_borrower` | `borrower_contacted`, `appointment_scheduled`, `awaiting_review`, `report_rejected_for_correction`, `report_complete` |\n| `appointment_scheduled` | `awaiting_review`, `report_rejected_for_correction`, `report_complete` |\n| `awaiting_review` | `report_rejected_for_correction`, `report_complete` |\n| `report_rejected_for_correction` | `awaiting_review`, `report_complete` |\n| `report_complete` | Nothing. Open a correction or a reconsideration first, which moves the order to `revision_requested` or `reconsideration_requested`. |\n| `revision_requested` | `revised_report_complete` |\n| `reconsideration_requested` | `revised_report_complete` |\n| `revised_report_complete` | Nothing. Open another correction first. |\n| `on_hold`, `cancelled` | Nothing. Resume a held order first; a cancelled order is not advanced. |\n\nAn order at `off_hold` or `reactivated` may be advanced to whatever the\ntable allows for the status it held before the hold or the cancellation,\nwhich the `hold` and `cancel` responses give you in `previous_status`.\n\nDrive your test suite from this call: place an order, advance it through\nassignment, appointment, review and delivery, and assert on what your\nlistener received.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxAdvance" }, "example": { "to_status": "appraiser_assigned" } } } }, "responses": { "200": { "description": "The order after the move.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "No such order, or this path does not exist in this environment. It\nexists in the sandbox only.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "not_found", "message": "No order with that id in this environment.", "correlation_id": "req_01J9Z3K4R7T0W3Y6B9D2F5H8" } } } }, "409": { "description": "The order's current status does not allow that move.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "action_not_allowed_in_status", "message": "An order cannot be moved backwards.", "current_status": "report_complete", "details": [ { "field": "to_status", "code": "not_applicable", "value": "appraiser_assigned", "message": "The order is already at report_complete." } ], "correlation_id": "req_01J9Z3K4R7T0W3Y6B9D2F5H8" } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/webhook/test": { "post": { "tags": [ "Webhook Configuration" ], "operationId": "sendTestWebhook", "summary": "Send yourself a signed test event", "description": "Delivers one signed specimen event of the type you name to your configured\nendpoint, and returns what your endpoint answered. Use it to prove your\nsignature check, your timestamp tolerance and your ten second\nacknowledgement before you place an order.\n\nThe delivery is signed with your current secret and carries the same\nheaders as a real one. Its envelope carries `\"test\": true`, and it is not\nwritten to your feed, so `GET /events` is unaffected. Its payload carries\na synthetic `order_id`, always prefixed `ord_test_`, which no real order\nin any environment ever carries, so a specimen can never be mistaken for\none of your orders. It works in both environments, on the same terms: a\nhandler that sees `test` true verifies the signature, answers 2xx, and\nstops, without storing the event or looking the order up. A client with\nno webhook configured is refused with 404 and code\n`webhook_not_configured`.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestRequest" }, "example": { "type": "order.status_changed" } } } }, "responses": { "200": { "description": "The delivery was attempted. Read `delivered` for the outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestResult" }, "example": { "event_id": "evt_01M2TM1N60M4HGM9QGTHVCDMA2", "type": "order.status_changed", "url": "https://los.example.com/hooks/appraisal-host", "delivered": true, "response_status": 200, "response_time_ms": 142, "error": null, "attempted_at": "2026-09-18T16:02:04Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "No webhook has been configured for this client yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "webhook_not_configured", "message": "No webhook endpoint has been configured for this client.", "correlation_id": "req_01J9Z3K4R7T0W3Y6B9D2F5H8" } } } }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/webhook": { "get": { "tags": [ "Webhook Configuration" ], "operationId": "getWebhook", "summary": "Read your webhook configuration", "description": "Returns the endpoint we deliver your events to, which event types you are\nsubscribed to, and when the signing secret was last rotated. The secret\nitself is never returned.\n", "responses": { "200": { "description": "Your webhook configuration.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfig" }, "example": { "url": "https://los.example.com/hooks/appraisal-host", "enabled": true, "events": [ "*" ], "secret_set": true, "secret_rotated_at": "2026-09-15T09:00:00Z", "updated_at": "2026-09-15T09:00:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "No webhook has been configured for this client yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "webhook_not_configured", "message": "No webhook endpoint has been configured for this client.", "correlation_id": "req_01J9Z3K4R7T0W3Y6B9D2F5H8" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "put": { "tags": [ "Webhook Configuration" ], "operationId": "putWebhook", "summary": "Set or update your webhook configuration", "description": "Sets the endpoint we deliver your events to. The URL must be HTTPS and\nmust answer a POST with a 2xx within 10 seconds.\n\nThis call replaces the fields you send and leaves the others as they are.\nOmitting `events` keeps your current subscription; omitting `secret` keeps\nyour current secret, which this call never clears. Send\n`\"enabled\": false` to stop delivery without losing your configuration.\n\nSend `secret` to set or rotate the signing secret. Use at least 32\ncharacters of random text. We store it in a form we can sign with and\nnever display it again, so keep your own copy. One secret is in force at a\ntime, and every attempt is signed with the secret in force when that\nattempt is made, so a retry sent after a rotation carries the new secret.\nChange both sides together, or accept either signature for a short window.\n\nSend `events` to subscribe to a subset of event types, or `[\"*\"]` for all\nof them. Unsubscribed events are still raised and still readable at\n`GET /events`; we simply do not deliver them.\n\nThe appraisal management company can also set this endpoint for you from its own screens. The last\nwrite wins, whichever side made it.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfigUpdate" }, "example": { "url": "https://los.example.com/hooks/appraisal-host", "enabled": true, "events": [ "order.status_changed", "order.completed", "order.document_added" ], "secret": "example_webhook_secret_replace_this_with_32_random_characters" } } } }, "responses": { "200": { "description": "The configuration was saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfig" }, "example": { "url": "https://los.example.com/hooks/appraisal-host", "enabled": true, "events": [ "order.status_changed", "order.completed", "order.document_added" ], "secret_set": true, "secret_rotated_at": "2026-09-17T14:45:00Z", "updated_at": "2026-09-17T14:45:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } } }, "webhooks": { "order.created": { "post": { "tags": [ "Events" ], "operationId": "webhookOrderCreated", "summary": "An order was created", "description": "Raised when an order is created for your lender account, including orders\nplaced in the portal by the lender's own staff rather than through the\nAPI.\n", "security": [], "parameters": [ { "$ref": "#/components/parameters/XAHSignature" }, { "$ref": "#/components/parameters/XAHEventId" }, { "$ref": "#/components/parameters/XAHEventType" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOrderCreated" }, "example": { "id": "evt_01M2QWG9M8BSNHMTEF5XX0GB38", "type": "order.created", "created_at": "2026-09-17T14:32:05Z", "api_version": "1.0.0", "data": { "order_id": "ord_9TBK4C2QFA7M", "order_number": "2026-1043", "lender_reference": "LN-2026-88421", "order_type": { "code": "SFR-1004-36", "name": "Single Family Residential, current report standard", "report_format": "uad_3_6", "appraiser_certification": "none" }, "status": { "code": "new", "label": "New Order", "changed_at": "2026-09-17T14:32:05Z" }, "due_date": "2026-10-02", "created_at": "2026-09-17T14:32:05Z" } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds to acknowledge receipt." } } } }, "order.status_changed": { "post": { "tags": [ "Events" ], "operationId": "webhookOrderStatusChanged", "summary": "An order's status changed", "description": "Raised on every change to the status the lender sees. An order is always\nreported with the status the lender sees in the portal, in the same\nwords.\n", "security": [], "parameters": [ { "$ref": "#/components/parameters/XAHSignature" }, { "$ref": "#/components/parameters/XAHEventId" }, { "$ref": "#/components/parameters/XAHEventType" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOrderStatusChanged" }, "example": { "id": "evt_01M2T9W27R459H4DHVZGW4WNSS", "type": "order.status_changed", "created_at": "2026-09-18T13:04:11Z", "api_version": "1.0.0", "data": { "order_id": "ord_9TBK4C2QFA7M", "order_number": "2026-1043", "status": { "code": "appraiser_assigned", "label": "Appraiser Assigned", "changed_at": "2026-09-18T13:04:11Z" }, "previous_status": { "code": "new", "label": "New Order" }, "note": "Assigned to a certified appraiser covering Sangamon county." } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds to acknowledge receipt." } } } }, "order.assigned": { "post": { "tags": [ "Events" ], "operationId": "webhookOrderAssigned", "summary": "An appraiser was assigned", "description": "Raised when the appraisal management company assigns an appraiser. The\nevent always fires. `appraiser` carries the appraiser's display name where\nthe company shares the assigned appraiser with its lenders, and is null\nwhere it does not.\n", "security": [], "parameters": [ { "$ref": "#/components/parameters/XAHSignature" }, { "$ref": "#/components/parameters/XAHEventId" }, { "$ref": "#/components/parameters/XAHEventType" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOrderAssigned" }, "example": { "id": "evt_01M2T9W27RXJWVPHSK03CJAJQH", "type": "order.assigned", "created_at": "2026-09-18T13:04:11Z", "api_version": "1.0.0", "data": { "order_id": "ord_9TBK4C2QFA7M", "order_number": "2026-1043", "appraiser": { "name": "J. Marsh" }, "assigned_at": "2026-09-18T13:04:11Z" } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds to acknowledge receipt." } } } }, "order.on_hold": { "post": { "tags": [ "Events" ], "operationId": "webhookOrderOnHold", "summary": "An order was placed on hold", "description": "Raised when an order is put on hold, whoever put it there.", "security": [], "parameters": [ { "$ref": "#/components/parameters/XAHSignature" }, { "$ref": "#/components/parameters/XAHEventId" }, { "$ref": "#/components/parameters/XAHEventType" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOrderOnHold" }, "example": { "id": "evt_01M2WN9220WJX8W2ZDA9CMHHKM", "type": "order.on_hold", "created_at": "2026-09-19T11:02:00Z", "api_version": "1.0.0", "data": { "order_id": "ord_9TBK4C2QFA7M", "order_number": "2026-1043", "status": { "code": "on_hold", "label": "On Hold", "changed_at": "2026-09-19T11:02:00Z" }, "reason": "Borrower is renegotiating the purchase price." } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds to acknowledge receipt." } } } }, "order.resumed": { "post": { "tags": [ "Events" ], "operationId": "webhookOrderResumed", "summary": "An order resumed from hold", "description": "Raised when an order comes off hold and work restarts.", "security": [], "parameters": [ { "$ref": "#/components/parameters/XAHSignature" }, { "$ref": "#/components/parameters/XAHEventId" }, { "$ref": "#/components/parameters/XAHEventType" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOrderResumed" }, "example": { "id": "evt_01M344BJF0DA2RXN7VKXTHJWEG", "type": "order.resumed", "created_at": "2026-09-22T08:40:12Z", "api_version": "1.0.0", "data": { "order_id": "ord_9TBK4C2QFA7M", "order_number": "2026-1043", "status": { "code": "off_hold", "label": "Off Hold", "changed_at": "2026-09-22T08:40:12Z" }, "reason": "Purchase price agreed, please proceed." } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds to acknowledge receipt." } } } }, "order.cancelled": { "post": { "tags": [ "Events" ], "operationId": "webhookOrderCancelled", "summary": "An order was cancelled", "description": "Raised when an order is cancelled, whoever cancelled it.", "security": [], "parameters": [ { "$ref": "#/components/parameters/XAHSignature" }, { "$ref": "#/components/parameters/XAHEventId" }, { "$ref": "#/components/parameters/XAHEventType" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOrderCancelled" }, "example": { "id": "evt_01M2ZT0NARH2NGSGKRP6ZFPYN7", "type": "order.cancelled", "created_at": "2026-09-20T16:22:31Z", "api_version": "1.0.0", "data": { "order_id": "ord_9TBK4C2QFA7M", "order_number": "2026-1043", "status": { "code": "cancelled", "label": "Order Cancelled", "changed_at": "2026-09-20T16:22:31Z" }, "reason": "Loan withdrawn by the borrower." } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds to acknowledge receipt." } } } }, "order.completed": { "post": { "tags": [ "Events" ], "operationId": "webhookOrderCompleted", "summary": "A report was delivered", "description": "Raised when the report is delivered, and again when a revised report is\ndelivered. `documents` lists every file that came with the delivery, each\nas a separate document. Fetch each one with\n`GET /documents/{document_id}` to obtain a signed link.\n", "security": [], "parameters": [ { "$ref": "#/components/parameters/XAHSignature" }, { "$ref": "#/components/parameters/XAHEventId" }, { "$ref": "#/components/parameters/XAHEventType" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOrderCompleted" }, "example": { "id": "evt_01M3Q5WZA8V0AB3B4S4B8E3XC5", "type": "order.completed", "created_at": "2026-09-29T18:12:45Z", "api_version": "1.0.0", "data": { "order_id": "ord_9TBK4C2QFA7M", "order_number": "2026-1043", "status": { "code": "report_complete", "label": "Report Complete", "changed_at": "2026-09-29T18:12:44Z" }, "report_format": "uad_3_6", "revision": false, "completed_at": "2026-09-29T18:12:44Z", "documents": [ { "id": "doc_3XH8M1PLQW60", "kind": "report_pdf", "filename": "report_2026-1043.pdf", "content_type": "application/pdf", "size_bytes": 2841773, "created_at": "2026-09-29T18:12:44Z" }, { "id": "doc_5RJ2N7VKTB41", "kind": "report_data", "filename": "report_2026-1043.zip", "content_type": "application/zip", "size_bytes": 1044210, "created_at": "2026-09-29T18:12:44Z" }, { "id": "doc_8QL4P9WMYC72", "kind": "invoice", "filename": "invoice_2026-1043.pdf", "content_type": "application/pdf", "size_bytes": 88120, "created_at": "2026-09-29T18:12:45Z" } ] } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds to acknowledge receipt." } } } }, "order.document_added": { "post": { "tags": [ "Events" ], "operationId": "webhookOrderDocumentAdded", "summary": "A document was added to an order", "description": "Raised when a document the lender may see is added to an order, including\nthe files that arrive with a delivery and anything the company adds later.\n", "security": [], "parameters": [ { "$ref": "#/components/parameters/XAHSignature" }, { "$ref": "#/components/parameters/XAHEventId" }, { "$ref": "#/components/parameters/XAHEventType" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOrderDocumentAdded" }, "example": { "id": "evt_01M3Q5WZA8WNXQQRS6N3X84JWZ", "type": "order.document_added", "created_at": "2026-09-29T18:12:45Z", "api_version": "1.0.0", "data": { "order_id": "ord_9TBK4C2QFA7M", "order_number": "2026-1043", "document": { "id": "doc_8QL4P9WMYC72", "kind": "invoice", "filename": "invoice_2026-1043.pdf", "content_type": "application/pdf", "size_bytes": 88120, "created_at": "2026-09-29T18:12:45Z" } } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds to acknowledge receipt." } } } }, "order.message_posted": { "post": { "tags": [ "Events" ], "operationId": "webhookOrderMessagePosted", "summary": "A message was posted on an order", "description": "Raised when a message the lender is party to is posted by the appraisal management company or the\nappraiser. Your own messages do not raise this event.\n", "security": [], "parameters": [ { "$ref": "#/components/parameters/XAHSignature" }, { "$ref": "#/components/parameters/XAHEventId" }, { "$ref": "#/components/parameters/XAHEventType" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOrderMessagePosted" }, "example": { "id": "evt_01M2TM1N60M4HGM9QGTHVCDMA2", "type": "order.message_posted", "created_at": "2026-09-18T16:02:00Z", "api_version": "1.0.0", "data": { "order_id": "ord_9TBK4C2QFA7M", "order_number": "2026-1043", "message": { "id": "msg_8TH2U5AYVF18", "order_id": "ord_9TBK4C2QFA7M", "recipient": "lender", "subject": "Access arrangements", "body": "Understood. The appraiser will call the agent to confirm.", "author": { "type": "manager", "name": "Order Desk" }, "attachments": [], "created_at": "2026-09-18T16:02:00Z" } } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds to acknowledge receipt." } } } }, "order.revision_requested": { "post": { "tags": [ "Events" ], "operationId": "webhookOrderRevisionRequested", "summary": "A revision request was opened", "description": "Raised when a correction or a reconsideration of value is opened on the\norder, whether through the API or in the portal.\n", "security": [], "parameters": [ { "$ref": "#/components/parameters/XAHSignature" }, { "$ref": "#/components/parameters/XAHEventId" }, { "$ref": "#/components/parameters/XAHEventType" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOrderRevisionRequested" }, "example": { "id": "evt_01M3RWBA6G2CGMPB7GYCEAG70Y", "type": "order.revision_requested", "created_at": "2026-09-30T10:04:18Z", "api_version": "1.0.0", "data": { "order_id": "ord_9TBK4C2QFA7M", "order_number": "2026-1043", "revision_request": { "id": "rr_6PD3K8YWQN25", "order_id": "ord_9TBK4C2QFA7M", "kind": "reconsideration_of_value", "status": "submitted", "reason": "Three closed sales within 0.4 miles support a higher value.", "acknowledgements": { "prior_appraisal_provided": false, "comparable_sales_provided": true }, "documents": [], "responses": [], "created_at": "2026-09-30T10:04:18Z", "updated_at": "2026-09-30T10:04:18Z" } } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds to acknowledge receipt." } } } }, "order.revision_responded": { "post": { "tags": [ "Events" ], "operationId": "webhookOrderRevisionResponded", "summary": "A revision request was answered", "description": "Raised when the appraisal management company accepts, declines or comments on a revision request.\nA revised report that follows arrives as `order.completed` with\n`revision` set to true.\n", "security": [], "parameters": [ { "$ref": "#/components/parameters/XAHSignature" }, { "$ref": "#/components/parameters/XAHEventId" }, { "$ref": "#/components/parameters/XAHEventType" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOrderRevisionResponded" }, "example": { "id": "evt_01M3SFKTQ0PPQ3NCREDTYS1BKE", "type": "order.revision_responded", "created_at": "2026-09-30T15:41:00Z", "api_version": "1.0.0", "data": { "order_id": "ord_9TBK4C2QFA7M", "order_number": "2026-1043", "revision_request_id": "rr_6PD3K8YWQN25", "status": "accepted", "response": { "id": "msg_4NF9R2XWTD86", "created_at": "2026-09-30T15:41:00Z", "author": { "type": "manager", "name": "Order Desk" }, "message": "Sent to the appraiser for review. Revised report expected within two business days." } } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds to acknowledge receipt." } } } }, "order.due_date_changed": { "post": { "tags": [ "Events" ], "operationId": "webhookOrderDueDateChanged", "summary": "An order's due date changed", "description": "Raised when the due date on the order changes, including when the appraisal management company\naccepts or adjusts a date you requested.\n", "security": [], "parameters": [ { "$ref": "#/components/parameters/XAHSignature" }, { "$ref": "#/components/parameters/XAHEventId" }, { "$ref": "#/components/parameters/XAHEventType" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOrderDueDateChanged" }, "example": { "id": "evt_01M2WFE9G0VF1S24AE8RTAH2ZC", "type": "order.due_date_changed", "created_at": "2026-09-19T09:20:00Z", "api_version": "1.0.0", "data": { "order_id": "ord_9TBK4C2QFA7M", "order_number": "2026-1043", "due_date": "2026-10-06", "previous_due_date": "2026-10-02", "requested_by": "lender" } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds to acknowledge receipt." } } } }, "order.fee_changed": { "post": { "tags": [ "Events" ], "operationId": "webhookOrderFeeChanged", "summary": "An order's fee changed", "description": "Raised when the fee the lender is charged changes. The fee is read only\nthrough the API: fee negotiation happens between the appraisal management company and the lender,\nnot over this interface.\n", "security": [], "parameters": [ { "$ref": "#/components/parameters/XAHSignature" }, { "$ref": "#/components/parameters/XAHEventId" }, { "$ref": "#/components/parameters/XAHEventType" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventOrderFeeChanged" }, "example": { "id": "evt_01M31Z3MA00XVKABD7905AR0R1", "type": "order.fee_changed", "created_at": "2026-09-21T12:30:00Z", "api_version": "1.0.0", "data": { "order_id": "ord_9TBK4C2QFA7M", "order_number": "2026-1043", "appraisal_fee": "575.00", "previous_appraisal_fee": "525.00", "currency": "USD", "reason": "Complex property, additional scope agreed with the lender." } } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds to acknowledge receipt." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "opaque", "description": "Send the token from `POST /oauth/token` as\n`Authorization: Bearer ` on every call except `GET /ping`\nand the token endpoint itself.\n" }, "oauth2ClientCredentials": { "type": "oauth2", "description": "The same credential expressed as an OAuth 2.0 client credentials flow.\n`POST /oauth/token` accepts the standard\n`application/x-www-form-urlencoded` request, with the credential either in\nthe body or in an HTTP Basic header, so a client generated from this\ndocument authenticates without modification. Errors at that endpoint\nfollow RFC 6749.\n", "flows": { "clientCredentials": { "tokenUrl": "https://api.appraisalhost.com/v1/oauth/token", "scopes": { "lender": "Place and manage orders for the lender account the credential belongs to." } } } } }, "parameters": { "PageParam": { "name": "page", "in": "query", "required": false, "description": "The page to return, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "PerPageParam": { "name": "per_page", "in": "query", "required": false, "description": "How many items to return per page, from 1 to 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A unique key of your own, up to 128 characters, that makes this create\nsafe to retry. We remember the key and its result for 24 hours.\n\nA key is scoped to your client credential and to this endpoint: the same\nkey sent by another credential is a different key. A repeat with the same\nkey and the same body returns the original order with the original 201. A\nrepeat with the same key and a different body is refused with 409 and code\n`idempotency_key_reused`.\n", "schema": { "type": "string", "maxLength": 128, "examples": [ "los-88421-create-1" ] } }, "OrderIdPath": { "name": "order_id", "in": "path", "required": true, "description": "The order's id, as returned when it was created.", "schema": { "type": "string", "maxLength": 64, "examples": [ "ord_9TBK4C2QFA7M" ] } }, "DocumentIdPath": { "name": "document_id", "in": "path", "required": true, "description": "The document's id.", "schema": { "type": "string", "maxLength": 64, "examples": [ "doc_5RJ2N7VKTB41" ] } }, "XAHSignature": { "name": "X-AH-Signature", "in": "header", "required": true, "description": "The signature over the delivery, as `t=,v1=`. `v1` is a\nhex encoded HMAC-SHA256 of the string `.` keyed with\nyour webhook secret. `t` is when we signed this attempt, not when the\nevent was raised: a retry hours later carries a fresh `t` and the original\n`created_at`. Compare `v1` with a constant time comparison, and reject a\ndelivery whose `t` is more than five minutes from your own clock.\n", "schema": { "type": "string", "examples": [ "t=1789736654,v1=3b1f8c0a7d2e5f49b6c8a1d3e5f709b2c4d6e8fa1b3c5d7e9f0a2b4c6d8e0f2a4" ] } }, "XAHEventId": { "name": "X-AH-Event-Id", "in": "header", "required": true, "description": "The event id, the same value as `id` in the body. Use it to make your handler idempotent.", "schema": { "type": "string", "examples": [ "evt_01M2T9W27R459H4DHVZGW4WNSS" ] } }, "XAHEventType": { "name": "X-AH-Event-Type", "in": "header", "required": true, "description": "The event type, the same value as `type` in the body. Useful for routing before you parse.", "schema": { "type": "string", "examples": [ "order.status_changed" ] } } }, "headers": { "XRateLimitLimit": { "description": "The number of requests allowed in the current window.", "schema": { "type": "integer", "examples": [ 600 ] } }, "XRateLimitRemaining": { "description": "The number of requests left in the current window.", "schema": { "type": "integer", "examples": [ 598 ] } }, "XRateLimitReset": { "description": "The Unix time in seconds at which the current window resets.", "schema": { "type": "integer", "examples": [ 1790000060 ] } }, "RetryAfter": { "description": "How many seconds to wait before retrying.", "schema": { "type": "integer", "examples": [ 30 ] } } }, "responses": { "BadRequest": { "description": "The request could not be read: malformed JSON, a missing required field,\nor a value of the wrong type. `details` names each field at fault.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "The request could not be processed. See details.", "details": [ { "field": "property.postal_code", "code": "required", "value": null, "message": "A postal code is required." }, { "field": "loan.purpose", "code": "invalid_value", "value": "cash_out", "message": "Must be one of: construction_only, construction_to_permanent, mortgage_modification, other, purchase, refinance." } ], "correlation_id": "req_01J9Z40M8P1R4T7W0Y3B6D9F" } } } }, "Unauthorized": { "description": "No token was sent, the token is not valid, or the token has expired. Ask\nfor a new token and retry once.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "token_expired", "message": "The access token has expired.", "correlation_id": "req_01J9Z41P0R3T6W9Y2B5D8F1H" } } } }, "Forbidden": { "description": "The credential is valid but is not allowed to do this: the action is\nswitched off for this client, or the resource belongs to another lender\naccount.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "action_not_permitted_for_client", "message": "This client is not permitted to cancel orders.", "correlation_id": "req_01J9Z42R2T5W8Y1B4D7F0H3K" } } } }, "NotFound": { "description": "No such resource, or one your credential is not entitled to see. We return\n404 rather than 403 for another account's resource so that ids cannot be\nprobed.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "not_found", "message": "No order with that id.", "correlation_id": "req_01J9Z43T4W7Y0B3D6F9H2K5M" } } } }, "Conflict": { "description": "The request is well formed but conflicts with the order's current state:\nan action the status does not allow, an amendment to a closed order, or a\nreused idempotency key.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "action_not_allowed_in_status", "message": "A closed order cannot be amended.", "current_status": "cancelled", "details": [ { "field": "status", "code": "current_status", "value": "cancelled", "message": "The order has been cancelled." } ], "correlation_id": "req_01J9Z44W6Y9B2D5F8H1K4M7P" } } } }, "PayloadTooLarge": { "description": "The upload is larger than 25 MB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "payload_too_large", "message": "The file is larger than the 25 MB limit.", "correlation_id": "req_01J9Z45Y8B1D4F7H0K3M6P9R" } } } }, "UnsupportedMediaType": { "description": "The `Content-Type` is not supported. JSON endpoints require\n`application/json`; the upload endpoint requires `multipart/form-data`\nwith a file of an accepted type.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "unsupported_media_type", "message": "Send application/json.", "correlation_id": "req_01J9Z46B0D3F6H9K2M5P8R1T" } } } }, "UnprocessableEntity": { "description": "The request is well formed and the fields are of the right type, but the\nvalues cannot be used: an order type this lender may not order, a loan\ntype that does not apply to the product, a due date in the past, an\nacknowledgement missing from a reconsideration.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "semantic_validation_failed", "message": "The loan type does not apply to this order type.", "details": [ { "field": "loan_type_code", "code": "not_applicable", "value": "va", "message": "That loan type is not available on order type SFR-1004-FHA. Read GET /order-types for the loan types the product accepts." } ], "correlation_id": "req_01J9Z47D2F5H8K1M4P7R0T3W" } } } }, "ServiceUnavailable": { "description": "The API is not serving requests for a moment, for example during planned\nmaintenance. Nothing you sent was applied. Wait for the number of seconds\nin `Retry-After` and retry.\n", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "service_unavailable", "message": "The API is briefly unavailable. Retry after the interval in Retry-After.", "correlation_id": "req_01J9Z49H6K9M2P5R8T1W4Y7B" } } } }, "TooManyRequests": { "description": "You have made more requests than your limit allows. Wait for the number of\nseconds in `Retry-After` and retry.\n", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "rate_limited", "message": "Too many requests. Retry after 30 seconds.", "correlation_id": "req_01J9Z48F4H7K0M3P6R9T2W5Y" } } } }, "InternalServerError": { "description": "Something failed on our side. The request may or may not have been\napplied: retry a read, and retry a create with the same\n`Idempotency-Key`. For a write that takes no key, such as a message, an\nupload or a revision request, read the order first rather than sending it\nagain. Quote the `correlation_id` to our integrations team.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "internal_error", "message": "The request could not be completed. Quote the correlation id if it continues.", "correlation_id": "req_01J9Z49H6K9M2P5R8T1W4Y7B" } } } } }, "schemas": { "Ping": { "type": "object", "description": "The liveness response.", "required": [ "status", "time" ], "properties": { "status": { "type": "string", "const": "ok" }, "time": { "type": "string", "format": "date-time", "description": "Our clock in UTC, useful when you verify signature timestamps." } } }, "TokenRequest": { "type": "object", "description": "A client credentials token request.", "required": [ "grant_type", "client_id", "client_secret" ], "properties": { "grant_type": { "type": "string", "const": "client_credentials" }, "client_id": { "type": "string", "description": "The client id we issued. Always starts with `cli_`.", "examples": [ "cli_example_2f8c41" ] }, "client_secret": { "type": "string", "description": "The client secret we issued. Shown once, at creation. Store it in a secret manager.", "examples": [ "example_secret_do_not_use_9f4b1c77ae" ] }, "scope": { "type": "string", "description": "Optional. The only scope in version 1 is `lender`, which is also the default.", "examples": [ "lender" ] } } }, "TokenResponse": { "type": "object", "description": "A bearer token.", "required": [ "access_token", "token_type", "expires_in", "scope" ], "properties": { "access_token": { "type": "string", "description": "The opaque token. Send it as `Authorization: Bearer `." }, "token_type": { "type": "string", "const": "Bearer" }, "expires_in": { "type": "integer", "description": "Seconds until the token expires, counted from this response.", "examples": [ 3600 ] }, "scope": { "type": "string", "examples": [ "lender" ] } } }, "Error": { "type": "object", "description": "The one error shape. `code` is stable and safe to branch on. `message` is\nplain text for a human and may be reworded. `details` names the fields at\nfault when the failure is a validation failure.\n", "required": [ "code", "message", "correlation_id" ], "properties": { "code": { "type": "string", "description": "A stable machine readable code.", "examples": [ "validation_failed" ] }, "message": { "type": "string", "description": "A plain description of what went wrong." }, "current_status": { "oneOf": [ { "$ref": "#/components/schemas/OrderStatusCode" }, { "type": "null" } ], "description": "The order's current status code. Present on every 409 that refuses an\naction because of the status the order has reached, so that you can\nbranch without walking `details`. Absent on every other error.\n" }, "details": { "type": "array", "description": "One entry per field at fault, when applicable.", "items": { "$ref": "#/components/schemas/ErrorDetail" } }, "correlation_id": { "type": "string", "description": "The identifier for this request in our logs. Quote it when you contact us.", "examples": [ "req_01J9Z40M8P1R4T7W0Y3B6D9F" ] } } }, "ErrorDetail": { "type": "object", "description": "One field level problem.", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string", "description": "A dotted path to the field, for example `property.postal_code` or `borrowers.0.last_name`.", "examples": [ "property.postal_code" ] }, "code": { "type": "string", "description": "A stable reason: `required`, `invalid_value`, `too_long`, `not_applicable`, `not_found`, `current_status`.", "examples": [ "required" ] }, "value": { "type": [ "string", "null" ], "description": "The machine readable value at fault, when there is one: the value you\nsent, or the order's current status code on a 409. Safe to branch on.\n`message` never is.\n", "examples": [ "report_complete" ] }, "message": { "type": "string", "description": "A plain explanation for a person. Never match on it." } } }, "OAuthError": { "type": "object", "description": "The error body at `POST /oauth/token` only, in the shape RFC 6749 defines.\nEvery other endpoint uses `Error`.\n", "required": [ "error" ], "properties": { "error": { "type": "string", "enum": [ "invalid_request", "invalid_client", "invalid_grant", "unauthorized_client", "unsupported_grant_type", "invalid_scope" ] }, "error_description": { "type": [ "string", "null" ], "description": "A plain explanation for a person. Never match on it." }, "correlation_id": { "type": [ "string", "null" ], "description": "The identifier for this request in our logs.", "examples": [ "req_01J9Z2A7K3M5P8R1T4W6Y9B2D" ] } } }, "AccountParty": { "type": "object", "description": "A named party on the account.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "examples": [ "len_4WQ2H8ZKPB31" ] }, "name": { "type": "string", "examples": [ "Example Mortgage Group" ] } } }, "AccountRateLimit": { "type": "object", "description": "The published limit for this client.", "required": [ "requests_per_minute" ], "properties": { "requests_per_minute": { "type": "integer", "examples": [ 600 ] } } }, "Account": { "type": "object", "description": "What a credential resolves to. Read it at start-up and assert on it.", "required": [ "client_id", "environment", "lender", "company", "scopes", "rate_limit" ], "properties": { "client_id": { "type": "string", "description": "Your client id. Safe to log.", "examples": [ "cli_example_2f8c41" ] }, "environment": { "type": "string", "description": "The environment this credential works in.", "enum": [ "sandbox", "production" ] }, "lender": { "allOf": [ { "$ref": "#/components/schemas/AccountParty" } ], "description": "The lender account orders placed with this credential belong to." }, "company": { "allOf": [ { "$ref": "#/components/schemas/AccountParty" } ], "description": "The appraisal management company that holds the lender account." }, "scopes": { "type": "array", "description": "The scopes the credential carries. Version 1 issues `lender`.", "items": { "type": "string" }, "examples": [ [ "lender" ] ] }, "rate_limit": { "$ref": "#/components/schemas/AccountRateLimit" } } }, "SandboxAdvance": { "type": "object", "description": "Sandbox only. The status to move a test order to.", "required": [ "to_status" ], "properties": { "to_status": { "type": "string", "description": "The status to move the order to. These are the statuses this call can\nset. `pending_review` is set by order creation, `revision_requested`\nand `reconsideration_requested` by\n`POST /orders/{order_id}/revision-requests`, and `on_hold`,\n`off_hold`, `cancelled` and `reactivated` by `hold`, `resume` and\n`cancel`, so none of them can be named here. Which of these is legal\nfrom the order's current status is in the transition table on the\nadvance operation.\n", "enum": [ "new", "appraiser_assigned", "appraiser_accepted", "borrower_contacted", "left_message_for_borrower", "appointment_scheduled", "awaiting_review", "report_rejected_for_correction", "report_complete", "revised_report_complete" ], "examples": [ "appraiser_assigned" ] }, "note": { "type": [ "string", "null" ], "maxLength": 255, "description": "Optional text to carry on the status, as a company would enter it." } } }, "WebhookTestRequest": { "type": "object", "description": "Which specimen event to send yourself.", "required": [ "type" ], "properties": { "type": { "$ref": "#/components/schemas/EventType" } } }, "WebhookTestResult": { "type": "object", "description": "What your endpoint did with the test delivery. The event it delivered\ncarries `test` true and a synthetic `order_id`, always prefixed\n`ord_test_`, which no real order in any environment ever carries. It is\nnot written to your feed, and no order changed.\n", "required": [ "event_id", "type", "url", "delivered", "attempted_at" ], "properties": { "event_id": { "type": "string", "description": "The id carried by the specimen event. It is not stored in your feed.", "examples": [ "evt_01M2TM1N60M4HGM9QGTHVCDMA2" ] }, "type": { "$ref": "#/components/schemas/EventType" }, "url": { "type": "string", "format": "uri", "description": "The endpoint we delivered to." }, "delivered": { "type": "boolean", "description": "True when your endpoint answered with a 2xx inside ten seconds." }, "response_status": { "type": [ "integer", "null" ], "description": "The status your endpoint returned, when it returned one.", "examples": [ 200 ] }, "response_time_ms": { "type": [ "integer", "null" ], "examples": [ 142 ] }, "error": { "type": [ "string", "null" ], "description": "What went wrong, when the delivery failed." }, "attempted_at": { "type": "string", "format": "date-time" } } }, "Pagination": { "type": "object", "description": "The page envelope shared by every list endpoint except the event feed.", "required": [ "page", "per_page", "total", "total_pages" ], "properties": { "page": { "type": "integer", "examples": [ 1 ] }, "per_page": { "type": "integer", "examples": [ 25 ] }, "total": { "type": "integer", "description": "How many items match in total.", "examples": [ 1 ] }, "total_pages": { "type": "integer", "examples": [ 1 ] } } }, "ReportFormat": { "type": "string", "description": "The report standard a product is delivered in.\n\n* `uad_2_6`: the report arrives as a PDF, plus `report_data` as the MISMO\n 2.6 GSE appraisal XML, with the report PDF embedded as that standard\n defines.\n* `uad_3_6`: the report arrives as a PDF, plus `report_data` as the UAD 3.6\n delivery package, a ZIP produced by the appraiser's forms software to the\n GSE UAD 3.6 specification. The members of that package are defined by\n that specification. The package is delivered exactly as the forms\n software produced it, so whether a copy of the report PDF sits inside it\n is that software's doing; `report_pdf` is always delivered as its own\n file as well, and that is the copy to read.\n\nIn both cases the invoice, the certificates and any other delivery\ndocument are separate files. The package replaces the report data file\nonly; it never contains the invoice. Sample files for both formats are\navailable from our integrations team.\n", "enum": [ "uad_2_6", "uad_3_6" ] }, "OrderStatusCode": { "type": "string", "description": "The statuses this interface reports. An order is always reported with the\nstatus the lender sees in the portal, in the same words.\n\n* `pending_review`: received, and with the appraisal management company\n for a look before it is placed. Nothing is wrong.\n* `new`: received, not yet assigned.\n* `appraiser_assigned`: an appraiser has the order.\n* `appraiser_accepted`: the appraiser accepted the assignment.\n* `borrower_contacted`: the appraiser has reached the contact.\n* `left_message_for_borrower`: the appraiser left a message for the borrower or the broker.\n* `appointment_scheduled`: an inspection appointment is set.\n* `awaiting_review`: the report has been submitted and is in review before delivery.\n* `report_complete`: the report has been delivered. Documents are available.\n* `report_rejected_for_correction`: the report was sent back for correction before delivery.\n* `revision_requested`: a correction has been requested on a delivered report.\n* `reconsideration_requested`: a reconsideration of value has been requested.\n* `revised_report_complete`: a revised report has been delivered.\n* `on_hold`: work is paused.\n* `off_hold`: work has resumed after a hold.\n* `cancelled`: the order was cancelled.\n* `reactivated`: a cancelled order was put back into production.\n\n`off_hold` and `reactivated` are transitional: an order at either moves on\nto its working status shortly afterwards, so read the order again rather\nthan treating one as a resting state.\n\nNot every company uses every status, so treat this as the complete set of\nwhat you may receive and never as a sequence you must see. A few labels\nare ours rather than the company's, because the status they stand for is\ninternal to the company. Branch on `code`, display `label`, and store a\ncode you do not know rather than failing on it.\n", "enum": [ "pending_review", "new", "appraiser_assigned", "appraiser_accepted", "borrower_contacted", "left_message_for_borrower", "appointment_scheduled", "awaiting_review", "report_complete", "report_rejected_for_correction", "revision_requested", "reconsideration_requested", "revised_report_complete", "on_hold", "off_hold", "cancelled", "reactivated" ] }, "OrderStatus": { "type": "object", "description": "A status, as a stable code with display text.", "required": [ "code", "label", "changed_at" ], "properties": { "code": { "$ref": "#/components/schemas/OrderStatusCode" }, "label": { "type": "string", "description": "The wording the lender sees. An appraisal management company may reword its own labels, so\nbranch on `code` and display `label`.\n", "examples": [ "Appraiser Assigned" ] }, "changed_at": { "type": "string", "format": "date-time" } } }, "OrderStatusRef": { "type": "object", "description": "A status without a timestamp, used for a previous status.", "required": [ "code", "label" ], "properties": { "code": { "$ref": "#/components/schemas/OrderStatusCode" }, "label": { "type": "string", "examples": [ "New Order" ] } } }, "LoanPurpose": { "type": "string", "description": "Why the loan is being made. Send `other` with `loan.purpose_other` when nothing else fits.", "enum": [ "construction_only", "construction_to_permanent", "mortgage_modification", "other", "purchase", "refinance" ] }, "PropertyType": { "type": "string", "description": "What kind of property is being appraised.", "enum": [ "church", "commercial_non_residential", "condominium", "condominium_over_four_stories", "cooperative", "farm", "home_and_business_combined", "manufactured_mobile_home", "mixed_use_residential", "multifamily_more_than_four_units", "other", "single_family", "townhouse", "two_to_four_unit_property", "vacant_land" ] }, "Occupancy": { "type": "string", "description": "How the property is occupied.", "enum": [ "investment_property", "primary_residence", "second_home", "vacant" ] }, "ContactType": { "type": "string", "enum": [ "phone", "email" ] }, "ContactRole": { "type": "string", "enum": [ "home", "cell", "work", "other" ] }, "Contact": { "type": "object", "description": "One way to reach a person.", "required": [ "type", "role", "value" ], "properties": { "type": { "$ref": "#/components/schemas/ContactType" }, "role": { "allOf": [ { "$ref": "#/components/schemas/ContactRole" } ], "description": "Whose number or address this is. On an email address use `home`,\n`work` or `other`.\n" }, "value": { "type": "string", "description": "The phone number or the email address. Phone numbers are text:\ninclude the country code, as in `+1-217-555-0142`, and read back what\nyou sent.\n", "examples": [ "sample.borrower@example.com" ] } } }, "Address": { "type": "object", "description": "A United States street address. Properties and territories of the United\nStates only.\n\n`postal_code` is required. `city`, `state` and `county` are filled in from\nit when you leave them out, and the filled in values are returned on the\norder. Where a postal code covers more than one place name we store the\npostal service's preferred name. A postal code we cannot resolve is\nrefused with 422.\n", "required": [ "street", "postal_code" ], "properties": { "street": { "type": "string", "maxLength": 255, "examples": [ "100 Example Avenue" ] }, "unit": { "type": [ "string", "null" ], "maxLength": 64, "examples": [ "Unit 2" ] }, "city": { "type": [ "string", "null" ], "maxLength": 128, "examples": [ "Springfield" ] }, "state": { "type": [ "string", "null" ], "description": "The two letter state or territory code.", "minLength": 2, "maxLength": 2, "examples": [ "IL" ] }, "postal_code": { "type": "string", "maxLength": 10, "examples": [ "62701" ] }, "county": { "type": [ "string", "null" ], "maxLength": 128, "examples": [ "Sangamon" ] } } }, "CatalogItem": { "type": "object", "description": "A code and its display name from an appraisal management company's own catalog.", "required": [ "code", "name" ], "properties": { "code": { "type": "string", "description": "Stable for this company. Send this value, not the name.", "examples": [ "conventional" ] }, "name": { "type": "string", "description": "Display text. May be reworded.", "examples": [ "Conventional" ] } } }, "AppraiserCertification": { "type": "string", "description": "Which appraiser certification a product requires.\n\n* `none`: no special certification.\n* `fha_required`: only an FHA approved appraiser may take it, and\n `loan.fha_case_number` is required on the order.\n* `fha_optional`: an FHA approved appraiser may take it, and the case\n number is accepted but not required.\n* `usda`: a USDA product, and `loan.fha_case_number` is required on the\n order.\n", "enum": [ "none", "fha_required", "fha_optional", "usda" ] }, "OrderTypeRef": { "type": "object", "description": "The product an order was placed against.", "required": [ "code", "name", "report_format", "appraiser_certification" ], "properties": { "code": { "type": "string", "description": "The product code. Codes belong to the appraisal management company and\nare opaque: treat one as a string and read it from `GET /order-types`.\nSome companies use numbers. A product appears only when the company has\nenabled it for API ordering and given it a code.\n", "examples": [ "SFR-1004-36" ] }, "name": { "type": "string", "examples": [ "Single Family Residential, current report standard" ] }, "report_format": { "$ref": "#/components/schemas/ReportFormat" }, "appraiser_certification": { "$ref": "#/components/schemas/AppraiserCertification" } } }, "OrderType": { "allOf": [ { "$ref": "#/components/schemas/OrderTypeRef" }, { "type": "object", "description": "A product the lender may order, with the tiers that apply to it.", "required": [ "active", "loan_types", "add_ons" ], "properties": { "description": { "type": [ "string", "null" ], "description": "The company's own description of the product, when it has set one." }, "active": { "type": "boolean", "description": "False when the company has withdrawn the product. A withdrawn product cannot be ordered." }, "loan_types": { "type": "array", "description": "The loan type tier that may be attached to this product. Empty for\na product that does not take one, which today means every product\nother than those on the current report standard. When the list is\nnot empty, `loan_type_code` is required on create.\n", "items": { "$ref": "#/components/schemas/CatalogItem" } }, "add_ons": { "type": "array", "description": "The add-ons that may be attached to this product. Add-ons are not\nparticular to one report standard: read this list on every\nproduct rather than assuming which products carry them. Some\nadd-ons apply only when the property has an accessory dwelling\nunit: pass `has_adu=true` to see those as well.\n\nSome add-ons are quoted by the appraisal management company rather\nthan priced from a rate card. An order carrying one is placed with\n`fees.appraisal_fee` null until the company quotes it, and\n`order.fee_changed` tells you the price.\n", "items": { "$ref": "#/components/schemas/CatalogItem" } }, "loan_purposes": { "type": "array", "description": "The loan purposes this product may be ordered for. An empty list\nmeans the product takes any purpose. A purpose the product does\nnot accept is refused with 422.\n", "items": { "$ref": "#/components/schemas/LoanPurpose" } }, "property_types": { "type": "array", "description": "The property types this product may be ordered for. An empty list\nmeans the product takes any type. A type the product does not\naccept is refused with 422.\n", "items": { "$ref": "#/components/schemas/PropertyType" } } } } ] }, "OrderTypeList": { "allOf": [ { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrderType" } } } }, { "$ref": "#/components/schemas/Pagination" } ] }, "BorrowerFields": { "type": "object", "description": "The fields a borrower and a co-borrower share.", "required": [ "first_name", "last_name" ], "properties": { "first_name": { "type": "string", "maxLength": 128, "examples": [ "Sample" ] }, "last_name": { "type": "string", "maxLength": 128, "examples": [ "Borrower" ] }, "address": { "oneOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ], "description": "The borrower's own address, when it is not the property address." }, "receives_report": { "type": "boolean", "default": false, "description": "True to send the delivered report to this borrower." }, "receives_status_updates": { "type": "boolean", "default": false, "description": "True to send status updates to this borrower." } } }, "Borrower": { "allOf": [ { "$ref": "#/components/schemas/BorrowerFields" }, { "type": "object", "description": "The borrower. `role`, `first_name`, `last_name` and at least one entry\nin `contacts` are required, so that the appraiser can arrange access. A\nborrower with no contacts is refused with 422 and\n`details[].field = \"borrowers.0.contacts\"`.\n", "required": [ "role", "contacts" ], "properties": { "role": { "type": "string", "const": "borrower" }, "contacts": { "type": "array", "minItems": 1, "description": "Phone numbers and email addresses for the borrower. At least one is\nrequired. Either a phone number or an email address satisfies it;\nsend a phone number where you have one, because that is how an\nappraiser arranges access.\n", "items": { "$ref": "#/components/schemas/Contact" } } } } ] }, "CoBorrower": { "allOf": [ { "$ref": "#/components/schemas/BorrowerFields" }, { "type": "object", "description": "The co-borrower, when there is one. `role`, `first_name` and\n`last_name` are required and `contacts` is optional: a co-borrower\nwith no contacts is accepted, because the appraiser arranges access\nthrough the borrower.\n", "required": [ "role" ], "properties": { "role": { "type": "string", "const": "co_borrower" }, "contacts": { "type": "array", "description": "Phone numbers and email addresses for the co-borrower. Optional:\nthe array may be empty or left out.\n", "items": { "$ref": "#/components/schemas/Contact" } } } } ] }, "BorrowerOrCoBorrower": { "description": "One person on the order. `role` says which of the two this is, and which\nrules apply: contacts are required on the borrower and optional on the\nco-borrower. An order carries one borrower and at most one co-borrower.\n", "oneOf": [ { "$ref": "#/components/schemas/Borrower" }, { "$ref": "#/components/schemas/CoBorrower" } ], "discriminator": { "propertyName": "role", "mapping": { "borrower": "#/components/schemas/Borrower", "co_borrower": "#/components/schemas/CoBorrower" } } }, "RealEstateAgent": { "type": "object", "description": "The agent to contact for access, when there is one.", "properties": { "first_name": { "type": [ "string", "null" ], "maxLength": 128 }, "last_name": { "type": [ "string", "null" ], "maxLength": 128 }, "company": { "type": [ "string", "null" ], "maxLength": 255 }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } } }, "AdditionalContact": { "type": "object", "description": "Someone else to copy. `report` receives the delivered report; `status`\nreceives status updates.\n", "required": [ "purpose", "email" ], "properties": { "purpose": { "type": "string", "enum": [ "report", "status" ] }, "name": { "type": [ "string", "null" ], "maxLength": 255 }, "email": { "type": "string", "format": "email", "examples": [ "processing@example.com" ] } } }, "Parties": { "type": "object", "description": "Other people involved in the order.", "properties": { "real_estate_agent": { "oneOf": [ { "$ref": "#/components/schemas/RealEstateAgent" }, { "type": "null" } ] }, "additional_contacts": { "type": "array", "items": { "$ref": "#/components/schemas/AdditionalContact" } } } }, "Note": { "type": "object", "description": "A note on the order. `order` notes are general instructions; `appointment`\nnotes are about arranging access. An order carries one note of each type.\nNotes have no ids and cannot be edited or removed through this interface.\n", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "enum": [ "order", "appointment" ] }, "text": { "type": "string", "maxLength": 4000 } } }, "OrderFlags": { "type": "object", "description": "The handling flags on the order.", "properties": { "rush": { "type": "boolean", "default": false, "description": "The lender is asking for a faster turn time. The appraisal management company decides whether a rush fee applies." }, "complex": { "type": "boolean", "default": false }, "rural": { "type": "boolean", "default": false }, "priority": { "type": "boolean", "default": false }, "certified_appraiser_required": { "type": "boolean", "default": false, "description": "True when only a certified appraiser may take the assignment." } } }, "LoanCreate": { "type": "object", "description": "The loan the appraisal supports.", "required": [ "purpose" ], "properties": { "purpose": { "$ref": "#/components/schemas/LoanPurpose" }, "purpose_other": { "type": [ "string", "null" ], "maxLength": 255, "description": "Required when `purpose` is `other`." }, "number": { "type": [ "string", "null" ], "maxLength": 64, "description": "The lender's loan number.", "examples": [ "88421" ] }, "client": { "type": [ "string", "null" ], "maxLength": 255, "description": "The client the lender is acting for, when it is not the lender itself." }, "investor": { "type": [ "string", "null" ], "maxLength": 255 }, "agency_case_number": { "type": [ "string", "null" ], "maxLength": 64 }, "fha_case_number": { "type": [ "string", "null" ], "maxLength": 64, "description": "The case number for the loan. Required when the product's\n`appraiser_certification` is `fha_required` or `usda`, accepted and\nnot required when it is `fha_optional`, and not used when it is\n`none`.\n" }, "purchase_price": { "type": [ "string", "null" ], "pattern": "^-?\\d+\\.\\d{2}$", "description": "A decimal string with two places. Required when `purpose` is `purchase`.", "examples": [ "415000.00" ] }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "description": "The three letter currency code for the amounts on this order. Defaults to USD.", "examples": [ "USD" ] } } }, "Loan": { "allOf": [ { "$ref": "#/components/schemas/LoanCreate" }, { "type": "object", "properties": { "loan_type": { "oneOf": [ { "$ref": "#/components/schemas/CatalogItem" }, { "type": "null" } ], "description": "The loan type tier the order was placed on, for a product on the current report standard." }, "add_ons": { "type": "array", "description": "The add-ons attached to the order.", "items": { "$ref": "#/components/schemas/CatalogItem" } } } } ] }, "PropertyCreate": { "type": "object", "description": "The property to be appraised.", "required": [ "address", "type", "occupancy" ], "properties": { "address": { "$ref": "#/components/schemas/Address" }, "type": { "$ref": "#/components/schemas/PropertyType" }, "occupancy": { "$ref": "#/components/schemas/Occupancy" }, "has_adu": { "type": "boolean", "default": false, "description": "True when the property has an accessory dwelling unit. Some add-ons on\nthe current report standard apply only when this is true.\n" } } }, "Property": { "type": "object", "description": "The property on an order, as it is read back.", "required": [ "address", "type", "occupancy" ], "properties": { "address": { "$ref": "#/components/schemas/Address" }, "type": { "$ref": "#/components/schemas/PropertyType" }, "occupancy": { "$ref": "#/components/schemas/Occupancy" }, "has_adu": { "type": "boolean", "description": "True when the property has an accessory dwelling unit." } } }, "OrderCreate": { "type": "object", "description": "An order to place. Read `GET /order-types` first: it gives you the\n`order_type_code` to send and, for a product on the current report\nstandard, the `loan_type_code` and `add_on_codes` values that product\naccepts.\n", "required": [ "order_type_code", "due_date", "loan", "property", "borrowers" ], "properties": { "order_type_code": { "type": "string", "description": "The product to order, from `GET /order-types`.", "examples": [ "SFR-1004-36" ] }, "loan_type_code": { "type": [ "string", "null" ], "description": "The loan type tier, from the product's `loan_types`. Required when the\nproduct lists loan types. An unknown or inapplicable code is refused\nwith 422 rather than being guessed at.\n", "examples": [ "conventional" ] }, "add_on_codes": { "type": "array", "description": "Add-ons to attach, from the product's `add_ons`.", "items": { "type": "string" }, "examples": [ [ "rent_schedule" ] ] }, "due_date": { "type": "string", "format": "date", "description": "The date the lender needs the report by. The appraisal management company confirms or adjusts it.", "examples": [ "2026-10-02" ] }, "lender_reference": { "type": [ "string", "null" ], "maxLength": 64, "description": "Your own reference for this order. We store it and return it, and you can search on it." }, "rush": { "type": "boolean", "default": false }, "complex": { "type": "boolean", "default": false }, "rural": { "type": "boolean", "default": false }, "priority": { "type": "boolean", "default": false }, "certified_appraiser_required": { "type": "boolean", "default": false }, "appraiser_instructions": { "type": [ "string", "null" ], "maxLength": 4000, "description": "Access instructions and anything else the appraiser needs to know." }, "loan": { "$ref": "#/components/schemas/LoanCreate" }, "property": { "$ref": "#/components/schemas/PropertyCreate" }, "borrowers": { "type": "array", "minItems": 1, "maxItems": 2, "description": "The borrower, and a co-borrower when there is one.", "items": { "$ref": "#/components/schemas/BorrowerOrCoBorrower" } }, "parties": { "$ref": "#/components/schemas/Parties" }, "notes": { "type": "array", "items": { "$ref": "#/components/schemas/Note" } }, "documents": { "type": "array", "description": "Supporting documents to attach at create, base64 encoded. Prefer\n`POST /orders/{order_id}/documents` for anything over a megabyte or\ntwo.\n", "items": { "$ref": "#/components/schemas/InlineDocument" } } } }, "InlineDocument": { "type": "object", "description": "A supporting document sent inside a JSON body.", "required": [ "filename", "content_type", "data" ], "properties": { "kind": { "type": "string", "const": "supporting", "default": "supporting" }, "purpose": { "$ref": "#/components/schemas/DocumentPurpose" }, "filename": { "type": "string", "maxLength": 255, "examples": [ "purchase_and_sale.pdf" ] }, "content_type": { "type": "string", "examples": [ "application/pdf" ] }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "data": { "type": "string", "contentEncoding": "base64", "description": "The file's bytes, base64 encoded. The decoded size counts against the 25 MB limit." } } }, "OrderPatch": { "type": "object", "description": "The parts of an open order a lender may change. Send only what changes.\nAn empty body is refused with 400.\n", "properties": { "lender_reference": { "type": [ "string", "null" ], "maxLength": 64 }, "due_date": { "type": "string", "format": "date", "description": "A REQUEST to move the due date. The date changes only when the appraisal management company accepts it." }, "appraiser_instructions": { "type": [ "string", "null" ], "maxLength": 4000 }, "loan": { "type": "object", "description": "Only the loan number, the client and the investor may be changed.", "properties": { "number": { "type": [ "string", "null" ], "maxLength": 64 }, "client": { "type": [ "string", "null" ], "maxLength": 255 }, "investor": { "type": [ "string", "null" ], "maxLength": 255 } } }, "borrower_contacts": { "type": "array", "description": "Replaces the borrower's contact list. Names and the property cannot be changed.", "items": { "$ref": "#/components/schemas/Contact" } }, "parties": { "$ref": "#/components/schemas/Parties" }, "notes": { "type": "array", "description": "Notes to add to the order. An order carries one note of each type, and\nwhat you send is added to the note of that type rather than replacing\nit. Nothing already on the order is removed.\n", "items": { "$ref": "#/components/schemas/Note" } } } }, "Fees": { "type": "object", "description": "The fee the lender is charged. Read only through this API.", "required": [ "appraisal_fee", "currency" ], "properties": { "appraisal_fee": { "type": [ "string", "null" ], "pattern": "^-?\\d+\\.\\d{2}$", "description": "The fee the lender is charged, as a decimal string with two places. It\nis normally set when the order is created. It is null when the product\nor an add-on has to be quoted by the appraisal management company, and\nit can change later. Either way `order.fee_changed` tells you.\n", "examples": [ "525.00" ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "examples": [ "USD" ] } } }, "OrderDates": { "type": "object", "description": "The dates on the order.", "required": [ "created_at", "updated_at", "due_date" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "description": "When anything you can see on the order last changed: its status, its\ndates, its fee, its documents, its messages or its own fields. This is\nthe field `updated_since` filters on.\n" }, "due_date": { "type": "string", "format": "date" }, "appointment_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The inspection appointment, when one has been scheduled." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the report was delivered." } } }, "AppraiserRef": { "type": "object", "description": "The assigned appraiser, by display name only. It is present only where the\nappraisal management company shares the assigned appraiser with its\nlenders. Where it does not, `appraiser` is null.\n", "required": [ "name" ], "properties": { "name": { "type": "string", "examples": [ "J. Marsh" ] } } }, "Order": { "type": "object", "description": "An order, as the lender sees it.", "required": [ "id", "order_number", "status", "order_type", "loan", "property", "dates", "fees" ], "properties": { "id": { "type": "string", "description": "Our id for the order. Always starts with `ord_`.", "examples": [ "ord_9TBK4C2QFA7M" ] }, "order_number": { "type": "string", "description": "The order number the appraisal management company uses, the one a person will quote on the phone.", "examples": [ "2026-1043" ] }, "lender_reference": { "type": [ "string", "null" ], "examples": [ "LN-2026-88421" ] }, "status": { "$ref": "#/components/schemas/OrderStatus" }, "order_type": { "$ref": "#/components/schemas/OrderTypeRef" }, "loan": { "$ref": "#/components/schemas/Loan" }, "property": { "$ref": "#/components/schemas/Property" }, "borrowers": { "type": "array", "items": { "$ref": "#/components/schemas/BorrowerOrCoBorrower" } }, "parties": { "$ref": "#/components/schemas/Parties" }, "notes": { "type": "array", "items": { "$ref": "#/components/schemas/Note" } }, "flags": { "$ref": "#/components/schemas/OrderFlags" }, "appraiser_instructions": { "type": [ "string", "null" ] }, "appraiser": { "oneOf": [ { "$ref": "#/components/schemas/AppraiserRef" }, { "type": "null" } ] }, "dates": { "$ref": "#/components/schemas/OrderDates" }, "fees": { "$ref": "#/components/schemas/Fees" }, "documents": { "type": "array", "description": "The documents on the order, without download links.", "items": { "$ref": "#/components/schemas/DocumentSummary" } } } }, "OrderSummary": { "type": "object", "description": "An order as it appears in a list.", "required": [ "id", "order_number", "status", "order_type", "dates" ], "properties": { "id": { "type": "string", "examples": [ "ord_9TBK4C2QFA7M" ] }, "order_number": { "type": "string", "examples": [ "2026-1043" ] }, "lender_reference": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/OrderStatus" }, "order_type": { "$ref": "#/components/schemas/OrderTypeRef" }, "property_address_summary": { "type": "string", "description": "The property address on one line, for display.", "examples": [ "100 Example Avenue, Springfield, IL 62701" ] }, "dates": { "$ref": "#/components/schemas/OrderDates" } } }, "OrderList": { "allOf": [ { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrderSummary" } } } }, { "$ref": "#/components/schemas/Pagination" } ] }, "ActionRequest": { "type": "object", "description": "The reason for an action. The appraisal management company and the appraiser both see it.", "properties": { "reason": { "type": "string", "maxLength": 4000 } } }, "OrderActionResult": { "type": "object", "description": "The outcome of a hold, a resume or a cancellation.", "required": [ "id", "order_number", "status" ], "properties": { "id": { "type": "string", "examples": [ "ord_9TBK4C2QFA7M" ] }, "order_number": { "type": "string", "examples": [ "2026-1043" ] }, "status": { "$ref": "#/components/schemas/OrderStatus" }, "previous_status": { "$ref": "#/components/schemas/OrderStatusRef" } } }, "RevisionKind": { "type": "string", "description": "`correction` asks the appraiser to fix or clarify the report.\n`reconsideration_of_value` asks the appraiser to reconsider the opinion of\nvalue and requires at least one acknowledgement.\n", "enum": [ "correction", "reconsideration_of_value" ] }, "RevisionAcknowledgements": { "type": "object", "description": "Required on a reconsideration of value. At least one must be true, or the\nrequest is refused with 422.\n", "properties": { "prior_appraisal_provided": { "type": "boolean", "default": false }, "comparable_sales_provided": { "type": "boolean", "default": false } } }, "RevisionRequestCreate": { "type": "object", "required": [ "kind", "reason" ], "properties": { "kind": { "$ref": "#/components/schemas/RevisionKind" }, "reason": { "type": "string", "maxLength": 4000, "description": "What needs to change, and why." }, "acknowledgements": { "$ref": "#/components/schemas/RevisionAcknowledgements" }, "document_ids": { "type": "array", "description": "Documents already uploaded to this order that support the request.", "items": { "type": "string" }, "examples": [ [ "doc_2KM7Q0VZTC93" ] ] }, "documents": { "type": "array", "description": "Documents to attach inline instead of uploading first.", "items": { "$ref": "#/components/schemas/InlineDocument" } } } }, "RevisionResponse": { "type": "object", "description": "One reply on a revision request.", "required": [ "id", "created_at", "author", "message" ], "properties": { "id": { "type": "string", "examples": [ "msg_4NF9R2XWTD86" ] }, "created_at": { "type": "string", "format": "date-time" }, "author": { "$ref": "#/components/schemas/Author" }, "message": { "type": "string" }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentSummary" } } } }, "RevisionRequest": { "type": "object", "description": "A correction or reconsideration on a delivered report.", "required": [ "id", "order_id", "kind", "status", "reason", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "description": "Always starts with `rr_`.", "examples": [ "rr_6PD3K8YWQN25" ] }, "order_id": { "type": "string", "examples": [ "ord_9TBK4C2QFA7M" ] }, "kind": { "$ref": "#/components/schemas/RevisionKind" }, "status": { "type": "string", "description": "`submitted` while the appraisal management company reviews it,\n`accepted` once it is with the appraiser, `declined` when the company\ndoes not take it forward, and\n`completed` once a revised report has been delivered against it.\n", "enum": [ "submitted", "accepted", "declined", "completed" ] }, "reason": { "type": "string" }, "acknowledgements": { "$ref": "#/components/schemas/RevisionAcknowledgements" }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentSummary" } }, "responses": { "type": "array", "items": { "$ref": "#/components/schemas/RevisionResponse" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "RevisionRequestList": { "allOf": [ { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RevisionRequest" } } } }, { "$ref": "#/components/schemas/Pagination" } ] }, "Author": { "type": "object", "description": "Who wrote a message. People are identified by display name only.", "required": [ "type", "name" ], "properties": { "type": { "type": "string", "enum": [ "lender", "manager", "appraiser", "system" ] }, "name": { "type": "string", "examples": [ "Order Desk" ] } } }, "MessageCreate": { "type": "object", "required": [ "recipient", "body" ], "properties": { "recipient": { "type": "string", "description": "Who the message is for. A company that keeps appraiser contact in its\nown hands refuses `appraiser` with 422 and code\n`recipient_not_allowed`.\n", "enum": [ "manager", "appraiser" ] }, "subject": { "type": [ "string", "null" ], "maxLength": 255 }, "body": { "type": "string", "maxLength": 10000 }, "document_ids": { "type": "array", "description": "Documents already uploaded to this order to attach.", "items": { "type": "string" } } } }, "Message": { "type": "object", "description": "A message on an order.", "required": [ "id", "order_id", "recipient", "body", "author", "created_at" ], "properties": { "id": { "type": "string", "description": "Always starts with `msg_`.", "examples": [ "msg_7SG1T4ZXUE07" ] }, "order_id": { "type": "string", "examples": [ "ord_9TBK4C2QFA7M" ] }, "recipient": { "type": "string", "description": "Who the message was addressed to.", "enum": [ "manager", "appraiser", "lender" ] }, "subject": { "type": [ "string", "null" ] }, "body": { "type": "string" }, "author": { "$ref": "#/components/schemas/Author" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentSummary" } }, "created_at": { "type": "string", "format": "date-time" } } }, "MessageList": { "allOf": [ { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, { "$ref": "#/components/schemas/Pagination" } ] }, "DocumentKind": { "type": "string", "description": "What a document is.\n\n* `report_pdf`: the appraisal report as a PDF.\n* `report_data`: the report data. On `uad_2_6` it is the MISMO 2.6 GSE\n appraisal XML, with the report PDF embedded as that standard defines.\n On `uad_3_6` it is the UAD 3.6 delivery package, a ZIP produced by the\n appraiser's forms software to the GSE UAD 3.6 specification, whose\n members are defined by that specification. The package is delivered\n exactly as the forms software produced it, so whether a copy of the\n report PDF sits inside it is that software's doing. Either way\n `report_pdf` is always delivered as its own file as well, and that is\n the copy to read.\n* `invoice`: the invoice for the order. Always a separate file, and never\n inside the package.\n* `compliance_certificate`: the compliance certificate.\n* `borrower_certificate`: the borrower delivery certificate.\n* `ssr`: a submission summary report from the collateral delivery portal.\n* `review_report`: a quality review report produced by the appraisal\n management company's own review process, when the company provides it to\n lenders. It is not something a lender orders through this API.\n* `supporting`: anything supplied to support the order, by either side.\n", "enum": [ "report_pdf", "report_data", "invoice", "compliance_certificate", "borrower_certificate", "ssr", "review_report", "supporting" ] }, "DocumentSummary": { "type": "object", "description": "A document without a download link.", "required": [ "id", "kind", "filename", "content_type", "created_at" ], "properties": { "id": { "type": "string", "description": "Always starts with `doc_`.", "examples": [ "doc_5RJ2N7VKTB41" ] }, "kind": { "$ref": "#/components/schemas/DocumentKind" }, "filename": { "type": "string", "examples": [ "report_2026-1043.zip" ] }, "content_type": { "type": "string", "examples": [ "application/zip" ] }, "size_bytes": { "type": [ "integer", "null" ], "examples": [ 1044210 ] }, "description": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Download": { "type": "object", "description": "A signed link to the file. It is valid for five minutes and may be used\nmore than once inside that window. Fetch a fresh link rather than storing\none.\n", "required": [ "url", "expires_at" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Follow it with a plain GET and no Authorization header: the signature\nin the link is the authorization. Its `expires` value is `expires_at`\nin Unix seconds.\n" }, "expires_at": { "type": "string", "format": "date-time", "description": "When the link stops working. Ask for another one after that." } } }, "Document": { "allOf": [ { "$ref": "#/components/schemas/DocumentSummary" }, { "type": "object", "required": [ "order_id", "download" ], "properties": { "order_id": { "type": "string", "examples": [ "ord_9TBK4C2QFA7M" ] }, "download": { "$ref": "#/components/schemas/Download" } } } ] }, "DocumentList": { "allOf": [ { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentSummary" } } } }, { "$ref": "#/components/schemas/Pagination" } ] }, "DocumentPurpose": { "type": "string", "description": "What a document you upload is for. Optional; `other` is assumed when you\nleave it out.\n", "enum": [ "engagement_letter", "sales_contract", "prior_report", "other" ] }, "DocumentUpload": { "type": "object", "description": "A multipart upload. A document you upload is visible to the appraisal\nmanagement company and to the assigned appraiser.\n", "required": [ "file", "kind" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The file. Up to 25 MB." }, "kind": { "type": "string", "const": "supporting", "description": "Only `supporting` may be uploaded by a lender." }, "purpose": { "$ref": "#/components/schemas/DocumentPurpose" }, "description": { "type": "string", "maxLength": 255, "description": "What the file is, for the appraiser." } } }, "DeliveryStatus": { "type": "string", "description": "How delivery of an event to your endpoint is going.\n\n* `pending`: not yet attempted, or waiting for its next attempt.\n* `delivered`: your endpoint returned a 2xx.\n* `failed`: at least one attempt failed and another is scheduled.\n* `dead_lettered`: every attempt failed. We will not try again, and the\n event stays readable here.\n* `not_subscribed`: raised but not delivered, because your subscription\n does not include this type.\n", "enum": [ "pending", "delivered", "failed", "dead_lettered", "not_subscribed" ] }, "EventDelivery": { "type": "object", "description": "The delivery state of one event.", "required": [ "status", "attempts" ], "properties": { "status": { "$ref": "#/components/schemas/DeliveryStatus" }, "attempts": { "type": "integer", "examples": [ 3 ] }, "last_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_response_status": { "type": [ "integer", "null" ], "description": "The HTTP status your endpoint returned on the last attempt.", "examples": [ 502 ] } } }, "EventType": { "type": "string", "description": "The event catalog.", "enum": [ "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", "order.fee_changed" ] }, "Event": { "type": "object", "description": "An event in your feed, with its delivery state.", "required": [ "id", "type", "created_at", "order_id", "data", "delivery" ], "properties": { "id": { "type": "string", "description": "Always starts with `evt_`. Ids are lexicographically sortable and come\nout in the order the events were raised. Compare them as strings; do\nnot decode one.\n", "examples": [ "evt_01M2T9W27R459H4DHVZGW4WNSS" ] }, "type": { "$ref": "#/components/schemas/EventType" }, "created_at": { "type": "string", "format": "date-time" }, "order_id": { "type": "string", "description": "Every event type in version 1 is an order event, so this is always set.", "examples": [ "ord_9TBK4C2QFA7M" ] }, "data": { "type": "object", "description": "The same payload we deliver to your endpoint for this event, without\nthe envelope fields. Its schema is the one published under `webhooks`\nfor this `type`.\n", "additionalProperties": true }, "delivery": { "$ref": "#/components/schemas/EventDelivery" } } }, "EventList": { "type": "object", "description": "A page of events. The feed uses a cursor: pass `next_cursor` back as\n`after` until it comes back null.\n", "required": [ "data", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass this as `after` to read the next page. Null when you have reached the end.", "examples": [ "evt_01M3Q5WZA8V0AB3B4S4B8E3XC5" ] } } }, "WebhookConfig": { "type": "object", "description": "Where we deliver your events.", "required": [ "url", "enabled", "events", "secret_set" ], "properties": { "url": { "type": "string", "format": "uri", "examples": [ "https://los.example.com/hooks/appraisal-host" ] }, "enabled": { "type": "boolean" }, "events": { "type": "array", "description": "The event types you are subscribed to, or `[\"*\"]` for all of them.", "items": { "type": "string" } }, "secret_set": { "type": "boolean", "description": "True when a signing secret is set. The secret itself is never returned." }, "secret_rotated_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "WebhookConfigUpdate": { "type": "object", "description": "The fields you send are replaced. The fields you leave out keep their\ncurrent values: omitting `events` keeps your subscription, and omitting\n`secret` keeps your secret. `url` is always required.\n", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "An HTTPS URL that answers a POST with a 2xx within 10 seconds." }, "enabled": { "type": "boolean", "default": true, "description": "Send false to stop delivery without losing your configuration." }, "events": { "type": "array", "description": "Event types to subscribe to, or `[\"*\"]` for all of them. Leave it out\nto keep your current subscription.\n", "items": { "type": "string" } }, "secret": { "type": "string", "minLength": 32, "maxLength": 128, "description": "Set or rotate the signing secret. At least 32 characters of random\ntext. Never returned, and never cleared by this call: leave it out to\nkeep the secret you have.\n" } } }, "WebhookEnvelope": { "type": "object", "description": "Every webhook body shares these fields. Branch on `type`, and use `id` to\nmake your handler idempotent: a redelivery carries the same id.\n", "required": [ "id", "type", "created_at", "api_version", "data" ], "properties": { "id": { "type": "string", "description": "The event id, the same value as `X-AH-Event-Id`.", "examples": [ "evt_01M2T9W27R459H4DHVZGW4WNSS" ] }, "type": { "$ref": "#/components/schemas/EventType" }, "created_at": { "type": "string", "format": "date-time", "description": "When we raised the event, not when we delivered it." }, "api_version": { "type": "string", "description": "The version of this contract the payload was built to.", "examples": [ "1.0.0" ] }, "test": { "type": "boolean", "default": false, "description": "True only on a specimen event sent by `POST /webhook/test`. Never true\non a real event, and a test event is not written to your feed. A\nspecimen carries a synthetic `data.order_id`, always prefixed\n`ord_test_`, which no real order in any environment ever carries, so\nit can never match one of your orders. When `test` is true, verify\nthe signature, answer 2xx, and stop: do not store the event and do\nnot look the order up. This holds in production as well as in the\nsandbox.\n" }, "data": { "type": "object", "additionalProperties": true } } }, "EventOrderRef": { "type": "object", "description": "Every event payload carries at least these two fields.", "required": [ "order_id", "order_number" ], "properties": { "order_id": { "type": "string", "examples": [ "ord_9TBK4C2QFA7M" ] }, "order_number": { "type": "string", "examples": [ "2026-1043" ] } } }, "EventOrderCreated": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/EventOrderRef" }, { "type": "object", "properties": { "lender_reference": { "type": [ "string", "null" ] }, "order_type": { "$ref": "#/components/schemas/OrderTypeRef" }, "status": { "$ref": "#/components/schemas/OrderStatus" }, "due_date": { "type": "string", "format": "date" }, "created_at": { "type": "string", "format": "date-time" } } } ] } } } ] }, "EventOrderStatusChanged": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/EventOrderRef" }, { "type": "object", "required": [ "status" ], "properties": { "status": { "$ref": "#/components/schemas/OrderStatus" }, "previous_status": { "$ref": "#/components/schemas/OrderStatusRef" }, "note": { "type": [ "string", "null" ], "description": "The note the appraisal management company entered with the status, when the lender may see it." } } } ] } } } ] }, "EventOrderAssigned": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/EventOrderRef" }, { "type": "object", "required": [ "appraiser", "assigned_at" ], "properties": { "appraiser": { "oneOf": [ { "$ref": "#/components/schemas/AppraiserRef" }, { "type": "null" } ], "description": "The appraiser's display name, present only where the\nappraisal management company shares the assigned appraiser\nwith its lenders. Where it does not, this is null and the\nevent still fires.\n" }, "assigned_at": { "type": "string", "format": "date-time" } } } ] } } } ] }, "EventOrderOnHold": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/EventOrderRef" }, { "type": "object", "required": [ "status" ], "properties": { "status": { "$ref": "#/components/schemas/OrderStatus" }, "reason": { "type": [ "string", "null" ] } } } ] } } } ] }, "EventOrderResumed": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/EventOrderRef" }, { "type": "object", "required": [ "status" ], "properties": { "status": { "$ref": "#/components/schemas/OrderStatus" }, "reason": { "type": [ "string", "null" ] } } } ] } } } ] }, "EventOrderCancelled": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/EventOrderRef" }, { "type": "object", "required": [ "status" ], "properties": { "status": { "$ref": "#/components/schemas/OrderStatus" }, "reason": { "type": [ "string", "null" ] } } } ] } } } ] }, "EventOrderCompleted": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/EventOrderRef" }, { "type": "object", "required": [ "status", "report_format", "documents", "completed_at" ], "properties": { "status": { "$ref": "#/components/schemas/OrderStatus" }, "report_format": { "$ref": "#/components/schemas/ReportFormat" }, "revision": { "type": "boolean", "description": "True when this delivery is a revised report." }, "completed_at": { "type": "string", "format": "date-time" }, "documents": { "type": "array", "description": "Every file delivered with the report, each a separate document.", "items": { "$ref": "#/components/schemas/DocumentSummary" } } } } ] } } } ] }, "EventOrderDocumentAdded": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/EventOrderRef" }, { "type": "object", "required": [ "document" ], "properties": { "document": { "$ref": "#/components/schemas/DocumentSummary" } } } ] } } } ] }, "EventOrderMessagePosted": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/EventOrderRef" }, { "type": "object", "required": [ "message" ], "properties": { "message": { "$ref": "#/components/schemas/Message" } } } ] } } } ] }, "EventOrderRevisionRequested": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/EventOrderRef" }, { "type": "object", "required": [ "revision_request" ], "properties": { "revision_request": { "$ref": "#/components/schemas/RevisionRequest" } } } ] } } } ] }, "EventOrderRevisionResponded": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/EventOrderRef" }, { "type": "object", "required": [ "revision_request_id", "status" ], "properties": { "revision_request_id": { "type": "string", "examples": [ "rr_6PD3K8YWQN25" ] }, "status": { "type": "string", "enum": [ "submitted", "accepted", "declined", "completed" ] }, "response": { "$ref": "#/components/schemas/RevisionResponse" } } } ] } } } ] }, "EventOrderDueDateChanged": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/EventOrderRef" }, { "type": "object", "required": [ "due_date" ], "properties": { "due_date": { "type": "string", "format": "date" }, "previous_due_date": { "type": [ "string", "null" ], "format": "date" }, "requested_by": { "type": "string", "description": "Who asked for the change: `lender` for a request you sent,\n`company` for a change the appraisal management company\nmade.\n", "enum": [ "lender", "company" ] } } } ] } } } ] }, "EventOrderFeeChanged": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/EventOrderRef" }, { "type": "object", "required": [ "appraisal_fee", "currency" ], "properties": { "appraisal_fee": { "type": "string", "examples": [ "575.00" ] }, "previous_appraisal_fee": { "type": [ "string", "null" ], "examples": [ "525.00" ] }, "currency": { "type": "string", "examples": [ "USD" ] }, "reason": { "type": [ "string", "null" ] } } } ] } } } ] } } } }