Orders

As the name suggests, orders are our primary model. You'll find how to create orders using the information you obtained from the configurations endpoint.

The order model

The order model has all the relevant order information, such as the appraisal company, the borrower, the payment method, etc. It also contains the valid actions you can take on an order, like hold, request cancellation, revision, etc.

Properties

Name
id
Type
string
Description
Unique identifier for the contact.
Name
allow_transitions
Type
array
Description
The allowed transitions for the order, e.g. hold, request cancellation, etc.
Name
borrower
Type
object
Description
Borrower model.
Name
company
Type
object
Description
The appraisal company model.
Name
complex_property
Type
boolean
Description
Indicates whether the property is a complex property.
Name
contract_price
Type
number
Description
The contract price of the property.
Name
due_date
Type
timestamp
Description
The due date of the order.
Name
green_certified
Type
timestamp
Description
Indicates whether the property is green certified.
Name
fha_case_number
Type
string
Description
FHA Case Number when the loan is FHA.
Name
file_number
Type
string
Description
CXP file number, e.g. CXP-00000001.
Name
full_address
Type
string
Description
The full address of the property, e.g. 123 Main St, New York, NY 10001.
Name
invoice_strategy
Type
string
Description
An enum indicating the invoice strategy for the order. Valid values are invoice_borrower, invoice_client, invoice_client_credit_card.
Name
loan_amount
Type
string
Description
The loan amount of the property.
Name
loan_type
Type
string
Description
An enum indicating the loan type of the order. Valid values are conventional, fha, usda, reo, asset_valuation, other.
Name
point_of_contact
Type
object
Description
The point of contact model.
Name
products
Type
array
Description
An array of product models.
Name
property_type
Type
object
Description
The property type model.
Name
occupancy_type
Type
string
Description
An enum indicating the occupancy type of the order. Valid values are primary_residence, second_home, investment.
Name
estate_held_type
Type
string
Description
An enum indicating the estate held type of the order. Valid values are fee_simple, lease_hold.
Name
special_instructions
Type
string
Description
Special instructions for the order.
Name
status
Type
object
Description
Status model.
Name
transaction_type
Type
string
Description
An enum indicating the transaction type of the order. Valid values are refinance, purchase, home_equity, construction, other.

get/api/v1/orders

Order list

This endpoint returns the list of orders.

Query Parameters

Name
page
Type
number
Description
The page number.
Name
per_page
Type
number
Description
The number of items per page.
Name
q
Type
object
Description
Search parameters using Ransack syntax.

Glossary

Name
status
Type
string
Description
An enum indicating the current status of the order. Valid values are:
Action required, Assigned, Assignment accepted with condition, Assignment rejected, Assignment timed out, Attention needed, Auto assign processing, Bidding, Cancel requested, Cancelled, Client quality assurance, Client request, Completed, Completion payment hold, Completion requested, Draft, Fulfilled, In review, Inspection completed, Inspection scheduled, Internal quality assurance, On hold, Pending, Pending assignment, Pending payment, Refused negotiation, Submission fee failed, Submission requested, Unassigned, Under negotiation, Waiting info from client, Waiting payment.

Date fields

Name
created_at
Type
DateTime
Description
Name
updated_at
Type
DateTime
Description
Name
submitted_at
Type
DateTime
Description
Name
completed_at
Type
DateTime
Description
Name
inspection_completed_at
Type
DateTime
Description
Name
due_date
Type
DateTime
Description
Name
vendor_due_date
Type
DateTime
Description
Name
original_due_date
Type
DateTime
Description
Name
assigned_at
Type
DateTime
Description
Name
fulfilled_at
Type
DateTime
Description
Name
closing_date
Type
DateTime
Description

Enums

Name
loan_type
Type
string
Description
An enum indicating the loan type of the order. Valid values are:
203k, asset_valuation, conventional, fha, other, portfolio, renovation, reo, sba_504, sba_504_and_sba_7a, sba_7a, sba_capline, usda, va.

Deprecation Warnings

Name
point_of_contact
Type
object
Description
It is being deprecated in favor of points_of_contact.

Request

GET

/api/v1/orders

curl --location --request GET 'https://app.collateralxp.com/api/v1/orders?page=1&per_page=10' \
  --header 'X-API-KEY: {api_key}' \
  --header 'Accept: application/json'

Response

{
  "data": [
    {
      "id": "ce8cdcfe-2eec-468c-86d7-55b40a430025",
      "file_number": "CXP-00003787",
      "full_address": "1424 Tongass Ave, Ketchikan, AK 99901",
      "status": {
        "id": "4c5c86fb-86fa-4b4b-afdf-25e25d2d0b75",
        "name": "Unassigned"
      },
      "due_date": "02/28/2025",
      "loan_type": "conventional",
      "transaction_type": "refinance"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 2,
    "total_count": 11,
    "per_page": 10,
    "has_next_page": true,
    "has_prev_page": false
  }
}

get/api/v1/orders/:id

Order show

This endpoint brings the details of an order.

Required URL attributes

Name
order_id
Type
string
Description
Unique identifier for the order.

Glossary

Name
parties->poc
Type
boolean
Description
Indicates whether the party member is a point of contact. Also present in the points_of_contact array.
Name
status
Type
string
Description
An enum indicating the current status of the order. Valid values are:
Action required, Assigned, Assignment accepted with condition, Assignment rejected, Assignment timed out, Attention needed, Auto assign processing, Bidding, Cancel requested, Cancelled, Client quality assurance, Client request, Completed, Completion payment hold, Completion requested, Draft, Fulfilled, In review, Inspection completed, Inspection scheduled, Internal quality assurance, On hold, Pending, Pending assignment, Pending payment, Refused negotiation, Submission fee failed, Submission requested, Unassigned, Under negotiation, Waiting info from client, Waiting payment.

Enums

Name
estate_held_type
Type
string
Description
An enum indicating the estate held type of the order. Valid values are:
fee_simple, leasehold.
Name
invoice_strategy
Type
string
Description
An enum indicating the invoice strategy for the order. Valid values are:
invoice_borrower, invoice_client, invoice_client_credit_card, invoice_later.
Name
loan_type
Type
string
Description
An enum indicating the loan type of the order. Valid values are:
203k, asset_valuation, conventional, fha, other, portfolio, renovation, reo, sba_504, sba_504_and_sba_7a, sba_7a, sba_capline, usda, va.
Name
occupancy_type
Type
string
Description
An enum indicating the occupancy type of the order. Valid values are:
investment, primary_residence, second_home.
Name
transaction_type
Type
string
Description
An enum indicating the transaction typeof the order. Valid values are:
collateral_valuation, commercial_construction_purchase, commercial_construction_refinance, construction, construction_purchase, construction_refinance, construction_school_daycare, home_equity, liquidation, other, purchase, refinance.

Deprecation Warnings

Name
point_of_contact
Type
object
Description
It is being deprecated in favor of points_of_contact.
Name
parties->email
Type
string
Description
It is being deprecated in favor of parties->emails.

Request

GET

/api/v1/orders/{order_id}

curl --location --request GET 'http://localhost:3000/api/v1/orders/ce8cdcfe-2eec-468c-86d7-55b40a430025' \
  --header 'X-API-KEY: {api_key}' \
  --header 'Accept: application/json'

Response

{
  "id": "ce8cdcfe-2eec-468c-86d7-55b40a430025",
  "address": {
    "address_one": "1424 Tongass Ave",
    "address_two": "",
    "city": "Ketchikan",
    "county_id": "23ef8377-ca8b-4a4c-824b-7d067149b812",
    "state_id": "0d5d8d49-061a-4fed-8dcc-1fcc184aefb9",
    "zip": "99901"
  },
  "allowed_transitions": [
    "assign",
    "hold",
    "request_cancel"
  ],
  "borrower": {
    "id": "2739b1b4-fdc5-4f39-b6a7-b8592ef963e5",
    "email": null,
    "first_name": "test",
    "last_name": "test",
    "phone": null
  },
  "client": {
    "id": "5f188c48-0bd9-4416-9120-a907fecfd9c5",
    "name": "ABC Bank"
  },
  "client_emails": null,
  "co_borrowers": [],
  "company": {
    "id": "d52663d2-54f2-4fd9-b515-e830de8e3885",
    "name": "Appraisal Desk Test, Inc."
  },
  "complex_property": null,
  "contract_price": null,
  "decimal_balance": "0.0",
  "due_date": "02/28/2025",
  "estate_held_type": null,
  "fha_case_number": "",
  "file_number": "CXP-00003787",
  "full_address": "1424 Tongass Ave, Ketchikan, AK 99901",
  "green_certified": false,
  "invoice_strategy": "invoice_client",
  "lender": {
    "id": "5f188c48-0bd9-4416-9120-a907fecfd9c5",
    "name": "ABC Bank"
  },
  "loan_amount": "0.0",
  "loan_number": "123123123123",
  "loan_type": "conventional",
  "occupancy_type": null,
  "parties": [
    {
      "id": "4c969279-34fa-4a06-a1f1-5873bf17e0c2",
      "email": "kathy+abcbank@email.com",
      "emails": [
        "kathy+abcbank@email.com"
      ],
      "name": "kathy ABC BANK",
      "phone": null,
      "phones": [
        null
      ],
      "poc": false,
      "role": "Client Manager"
    },
    {
      "id": "e5861842-031c-4c6c-aad5-759869498805",
      "email": "kpolak@email.com",
      "emails": [
        "kpolak@email.com"
      ],
      "name": "Kathy Client",
      "phone": "(773) 313-5725",
      "phones": [
        "(773) 313-5725"
      ],
      "poc": false,
      "role": "Loan Officer"
    },
    {
      "id": "8c9fa21d-81f8-4452-83e7-58f8315a0d35",
      "email": "chicagokasia@email.com",
      "emails": [
        "chicagokasia@email.com"
      ],
      "name": "Kathy Client",
      "phone": null,
      "phones": [
        null
      ],
      "poc": false,
      "role": "Client Manager"
    },
    {
      "id": "130e65b7-c13c-4f81-8a86-b97b4a559755",
      "email": "borrower@email.com",
      "emails": [
        "borrower@email.com"
      ],
      "name": "test test",
      "phone": "1233211234",
      "phones": [
        "1233211234"
      ],
      "poc": true,
      "role": "borrower"
    },
    {
      "id": "b3e79b60-7cd2-4037-9a20-5cf92693bd95",
      "email": "mary@email.com",
      "emails": [
        "mary@email.com"
      ],
      "name": "Mary Doe",
      "phone": "1233211234",
      "phones": [
        "1233211234"
      ],
      "poc": true,
      "role": "co_borrower"
    },
    {
      "id": "a848ec38-a230-4cbe-a91f-72fd9d2a8a9e",
      "email": "john.doe@email.com",
      "emails": [
        "john.doe@email.com"
      ],
      "name": "John Doe",
      "phone": null,
      "phones": [],
      "poc": false,
      "role": "buyer_agent"
    },
    {
      "id": "b6494113-70f7-40cc-8897-a3ab1d8131fe",
      "email": "john.doe2@email.com",
      "emails": [
        "john.doe2@email.com"
      ],
      "name": "John Doe 2",
      "phone": null,
      "phones": [],
      "poc": false,
      "role": "Seller agent"
    }
  ],
  "point_of_contact": {
    "id": "130e65b7-c13c-4f81-8a86-b97b4a559755",
    "emails": [
      "borrower@email.com"
    ],
    "first_name": "test",
    "last_name": "test",
    "name": "test test",
    "phone": "1233211234"
  },
  "points_of_contact": [
    {
      "id": "130e65b7-c13c-4f81-8a86-b97b4a559705",
      "emails": [
        "borrower@email.com"
      ],
      "first_name": "test",
      "last_name": "test",
      "name": "test test",
      "phone": "1233211234"
    },
    {
      "id": "b3e79b60-7cd2-4037-9a20-5cf92693bd95",
      "emails": [
        "mary@email.com"
      ],
      "first_name": "Mary",
      "last_name": "Doe",
      "name": "Mary Doe",
      "phone": "1233211234"
    }
  ],
  "products": [
    {
      "id": "30537535-e29c-4180-92ed-4f631535e065",
      "name": "test desktop 1004"
    }
  ],
  "property_type": {
    "id": "a9fee2ec-3732-455b-90df-47b744d8ce45",
    "name": "SFR",
    "slug": "sfr"
  },
  "special_instructions": "<div class=\"trix-content\">\n <div><br>* Please select an appraiser who has a 6 foot ladder or a selfie stick in order to get photos of attic or crawlspace.<br><br></div><div>* Please have the appraiser ask the client on the call to book appraisal if there are boxes, shelves or any items blocking access to any areas they need, so that they cannot get the photos they need to do a full FHA appraisal. Please have appraiser tell the client that they must move those items before they arrive.</div>\n</div>\n",
  "status": {
    "id": "4c5c86fb-86fa-4b4b-afdf-25e25d2d0b75",
    "name": "Unassigned"
  },
  "total_fee": "0.0",
  "transaction_type": "refinance"
}

post/api/v1/orders

Create an order

This endpoing will create an order. You are supposed to request the /configurations first to get the required information to create an order.

Attributes

Name
address
Type
object required
Description
The property address.
Show child attributes
Name
borrower
Type
object required
Description
The loan borrower.
Show child attributes
Name
point_of_contact
Type
object
Description
The point of contact for the appraisal inspection.
Show child attributes
Name
due_date
Type
string required
Description
The due date of the order, e.g. 2022-10-10T10:00.
Name
green_certified
Type
string required
Description
Indicates whether the property is green certified, e.g. true, false.
Name
loan_type
Type
string required
Description
The loan type enum
conventional, fha, usda, reo, asset_valuation, other
Name
fha_case_number
Type
string
Description
The FHA Case Number.
Name
transaction_type
Type
string required
Description
The transaction type enum
refinance, purchase, home_equity, construction, other
Name
loan_amount
Type
string
Description
The loan amount.
Name
contract_price
Type
number
Description
The contract price.
Name
special_instructions
Type
string
Description
Special instructions for the order.
Name
payment_method
Type
string required
Description
The payment method enum
payment_link, invoice, credit_card
Name
complex_property
Type
boolean
Description
Whether the property is complex or not.
Name
product_ids
Type
array required
Description
An array of product ids to be added to the order. You should retrieve these from the configurations endpoint.
Name
client_user_ids
Type
array required
Description
An array of client user ids to be added to the order. You should retrieve these from the configurations endpoint.
Name
occupancy_type
Type
string
Description
The occupancy type enum
primary_residence, second_home, investment
Name
estate_held_type
Type
string
Description
The estate held type enum
fee_simple, lease_hold

Request

POST

/api/v1/orders

curl -G https://app.collateralxp.com/api/v1/orders \
  -H "X-Api-Key: {api_key}"
  --data-raw '{
      "address": {
          "street_1": "6103 W Montrose",
          "city": "Chicago",
          "state": "IL",
          "zip": "61643"
      },
      "borrower": {
          "first_name": "John",
          "last_name": "Doe"
      },
      "due_date": "2022-10-10T10:00",
      "green_certified": "true",
      "loan_type": "conventional",
      "transaction_type": "refinance",
      "payment_method": "invoice",
      "property_type_id": "a9fee2ec-3732-455b-90df-47b744d8ce4f",
      "company_id": "d52663d2-54f2-4fd9-b515-e830de8e3888",
      "occupancy_type": "primary_residence",
      "estate_held_type": "fee_simple",
      "product_ids": [
          "d08fd0e8-fd05-4ae2-9aea-6340637ff525"
      ],
      "point_of_contact": {
          "name": "Jane Doe",
          "phone": "123123123",
          "emails": [
              "test@email.com",
              "another@email.com"
          ]
      },
      "requested_by": {
          "client_id": "95b5b914-13f3-403d-b19e-c3b7539b11e7",
          "lender_id": "95b5b914-13f3-403d-b19e-c3b7539b11e7"
      }
  }'

Response

{
  "id": "d54008ce-90e5-4012-8a10-4fcbc786ae5f",
  "allowed_transitions": [
    "assign",
    "hold",
    "request_cancel"
  ],
  "borrower": {
    "id": "a72a8739-fcf8-45e2-9a46-55bbb4d33516",
    "co_first_name": null,
    "co_last_name": null,
    "email": null,
    "first_name": "John",
    "last_name": "Doe",
    "phone": null
  },
  "company": {
    "id": "d52663d2-54f2-4fd9-b515-e830de8e3888",
    "name": "eValuation ZONE, Inc."
  },
  "complex_property": null,
  "contract_price": null,
  "due_date": "10/10/2022",
  "green_certified": true,
  "fha_case_number": null,
  "file_number": "CXP-00001698",
  "full_address": "6103 W Montrose, Chicago, IL 61643",
  "invoice_strategy": "invoice_client",
  "loan_amount": null,
  "loan_number": null,
  "loan_type": "conventional",
  "occupancy_type": "primary_residence",
  "estate_held_type": "fee_simple",
  "point_of_contact": {
    "id": "d7e90ad2-7d8b-4d5c-8081-88b8ed287829",
    "email": ["test@email.com", "another@email.com"],
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "123123123"
  },
  "products": [
    {
      "id": "d08fd0e8-fd05-4ae2-9aea-6340637ff525",
      "name": "CONV SFR (FNMA 1004 URAR)"
    }
  ],
  "property_type": {
    "id": "a9fee2ec-3732-455b-90df-47b744d8ce4f",
    "name": "SFR",
    "slug": "sfr"
  },
  "special_instructions": null,
  "status": {
    "id": "4c5c86fb-86fa-4b4b-afdf-25e25d2d0b7e",
    "name": "Unassigned"
  },
  "transaction_type": "refinance"
}

PUT/api/v1/orders/{order_id}/subject_address

Update order address

This endpoing will update the order address. You are supposed to request the /orders-list first to get the order_id to update an order.

Attributes

Name: address_one
Type: string
Description: The principal address of the property.

Name: address_two
Type: string
Description: The secondary address of the property.

Name: city
Type: string
Description: The city of the property.

Name: state
Type: string
Description: The state of the property.

Name: county
Type: string
Description: The county of the property.

Name: zip
Type: string
Description: The zip of the property.

Name: latitude
Type: string
Description: The latitude of the property.

Name: longitude
Type: string
Description: The longitude of the property.

Request

PUT

/api/v1/orders/{order_id}/subject_address

curl --location --request PUT 'https://app.collateralxp.com/api/v1/orders/{order_id}/subject_address' \
    --header 'X-API-KEY: {api_key}' \
    --header 'Content-Type: application/json' \
    --data '{
      "city": "Chicago",
      "state": "IL",
      "county": "Cook County",
      "zip": "60634",
      "latitude": 42.196010649999999,
      "longitude": -87.7799362,
      "address_one": "6103 W Montrose Ave",
      "address_two": ""
    }'

Response

{
  "success": true
}

PUT/api/v1/orders/{order_id}/hold

Hold

This endpoint requests holds the order.

Request

PUT

/api/v1/orders/{order_id}/hold

curl --location --request PUT 'https://app.collateralxp.com/api/v1/orders/{order_id}/hold' \
  --header 'X-API-KEY: {api_key}' \
  --form 'reason="Stop the presses!"'

Response

{
  "success": true
}

PUT/api/v1/orders/{order_id}/resume

Resume

This endpoint requests resumes an on hold order.

Request

PUT

/api/v1/orders/{order_id}/resume

curl --location --request PUT 'https://app.collateralxp.com/api/v1/orders/{order_id}/resume' \
  --header 'X-API-KEY: {api_key}'

Response

{
  "success": true
}

POST/api/v1/orders/{order_id}/follow_up

Request follow-up order

This endpoing will request to create a follow-up order.

Attributes

Name
due_date
Type
string required
Description
Due date of the follow-up order
Name
dont_assign
Type
boolean required
Description
If the follow-up order will have the same vendor/appraiser as the subject order
Name
product_ids
Type
array required
Description
The product ids of the follow-up order. You should retrieve these from the order endpoint.
Name
point_of_contact
Type
object
Description
The point of contact for the appraisal inspection.
Show child attributes

Request

POST

/api/v1/orders

curl -G https://app.collateralxp.com/api/v1/orders \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {api_key}"
  --data-raw '{
    "follow_up": {
      "due_date": "2024-01-23 09:53:53 -0300",
      "dont_assign": true,
      "product_ids": [
        "d08fd0e8-fd05-4ae2-9aea-6340637ff525",
        "28fd1577-8db4-4fac-bb44-b8a2f8b9c101"
      ],
      "point_of_contact": {
        "first_name": "John",
        "last_name": "Doe",
        "phone": "615-336-4068",
        "emails": [
          "john.doe@email.com",
          "another.john@email.com"
        ]
      }
    }
  }'

Response

{
  "id": "d4bac54f-df4c-47ba-8c7a-99c0360aa069",
  "address": {
    "address_one": "MyString",
    "address_two": "MyString",
    "city": "MyString",
    "county_id": "7273ab25-7c37-407f-8c73-9c8e1a2d23af",
    "state_id": "ceca4e4a-2f51-4870-ad4c-abeaa5d4aa65",
    "zip": "MyString"
  },
  "allowed_transitions": [
    "accept",
    "request_cancel"
  ],
  "borrower": {
    "id": "7ef7280c-1895-48b2-9adb-caf2c13824bf",
    "email": null,
    "first_name": "MyString",
    "last_name": "MyString",
    "phone": null
  },
  "client": {
    "id": "f3e69e31-ee9b-4d3f-b6f1-004e2030e310",
    "name": "Will, Flatley and Marvin"
  },
  "client_emails": null,
  "co_borrowers": [],
  "company": {
    "id": "8ae37bbd-f121-4889-a63c-daf7277f97cf",
    "name": "Brown, Fahey and Stark"
  },
  "complex_property": null,
  "contract_price": null,
  "due_date": "02/26/2024",
  "estate_held_type": null,
  "fha_case_number": null,
  "file_number": "CXP-00000001",
  "full_address": "MyString, MyString MyString, MyString1 MyString",
  "invoice_strategy": "invoice_later",
  "lender": {
    "id": "697b89ea-cbe5-433e-b030-e8144cd4243a",
    "name": "Koch, Wilkinson and Torp"
  },
  "loan_amount": "0.0",
  "loan_number": "abc-1",
  "loan_type": "conventional",
  "occupancy_type": null,
  "parties": [
    {
      "email": "bridgett.hamill@jacobi-corkery.test",
      "name": "John Doe",
      "phone": "567-954-3751",
      "poc": false,
      "role": "Sample"
    },
    {
      "email": "poc@email.com",
      "name": "John Doe",
      "phone": "615-336-4068",
      "poc": true,
      "role": "point_of_contact"
    },
    {
      "email": null,
      "name": "MyString MyString",
      "phone": null,
      "poc": false,
      "role": "borrower"
    }
  ],
  "point_of_contact": {
    "id": "86672269-d529-41ee-8e3f-bf8954707ca9",
    "emails": [
      "poc@email.com"
    ],
    "first_name": "John",
    "last_name": "Doe",
    "name": "John Doe",
    "phone": "615-336-4068"
  },
  "products": [
    {
      "id": "69c7fb25-11b6-4c9f-a855-9fe487c30587",
      "name": "Drawer dishwasher1"
    }
  ],
  "property_type": {
    "id": "60c2ff66-046e-4042-af61-aaf24b621b8d",
    "name": "Marco McCullough",
    "slug": "marco_mccullough"
  },
  "special_instructions": null,
  "status": {
    "id": "16320244-c544-48ee-8d29-ddce4b66ecd7",
    "name": "Pending"
  },
  "total_fee": "0.0",
  "transaction_type": "refinance"
}