Order API V3 Request Order API

Route

POST

Purpose

Parameters

token string 200

Authentication token for Requester (PlanOworker token).

group_order_token string 201

Group order token to authenticate the user that uploaded the bull order.

billing_entity_slug string 300

Unique identifying slug of billing entity.

external_property_id string 400

Unique client property ID.
Max String Length: 255

property hash 500

Object containing property info

Show child params

property.location hash
Location data of the property.
property.property_type string
Property Type
property.bedrooms integer
property.bathrooms integer
property.price integer
property.square_footage integer

services array 600

Services ordered.

property_access hash 600

Object outlining the property access information

Show child params

property_access.vacant boolean
property_access.method_of_access string
property_access.access_code string
Max String Length: 255
property_access.lockbox_location string
Max String Length: 255
property_access.preferred_date string
property_access.cutoff_date string
property_access.onsite_contact_name string
Max String Length: 255
property_access.onsite_contact_email string
Max String Length: 254
property_access.onsite_contact_phone string

order_notes string 700

Any relevant notes for the order.
Max String Length: 1000

external_order_id string 800

Optional client order ID metadata if the client wishes to provide it to PlanOcore to make mapping webhooks easier.
Max String Length: 255

third_party_entity hash 900

Show child params

third_party_entity.name string
Max String Length: 255

metadata string 900

Optional client metadata.

Request Body Example: application/json

          {"token": "Sw543vdfgswWg98", "group_order_token": "Df443vdfgswWg26", "billing_entity_slug": "real_estate_company", "external_property_id": "XY-332211", "property": {"location": {"street": "123 Main St.", "street2": "unit 420", "city": "Denver", "state": "CO", "postal_code": "80918", "latitude": "95.784747", "longitude": "-43.848483"}, "property_type": "single_family", "bedrooms": 2, "bathrooms": 3, "price": 1500, "square_footage": 5000}, "services": [], "property_access": {"vacant": true, "method_of_access": "lockbox_code", "access_code": "1321", "lockbox_location": "Behind A/C", "preferred_date": "2022-12-30", "cutoff_date": "2022-12-31", "onsite_contact_name": "Jane Doe", "onsite_contact_email": "janedoe@company.com", "onsite_contact_phone": "1 555 555 5555"}, "order_notes": "These are the notes that never end, they go on and on my friend", "external_order_id": "j39djh3", "third_party_entity": {"name": "Babooshka Homes"}, "metadata": null}

Responses

action-successful 200

This status indicates that the request was successful. If the request returns data, it can be found in the data key.

  {"code": 200, "data": {}, "status": "action-successful", "message": "..."}

invalid-token 401

This status is returned when the authentication token passed is invalid.

  {"code": 401, "status": "invalid-token", "message": "..."}

session-expired 401

This status is returned a session is older than seven days or hasn't been used in 72 hours. The user will need to reauthenticate. We allow our users to save a remember_me preference which will make there sessions last indefinitely.

  {"code": 401, "status": "session-expired", "message": "..."}

client-required 401

This status is returned when the user makeing the request doesn't have a client, employee or liaison record. This means that they don't have any roles or permissions. Because we only allow our clients to register as a client, the user should be redirected to the PlanoAuth clients registration page where they can use the `/api/v1/users/client_register` API to register as a client. Eventhough the request will not be successful, this status will still return a `session` object because a session token is needed to register as a user.

  {"code": 401, "status": "client-required", "message": "...", "session": {}}

missing-param 400

This status is returned when a required param was not passed with the request.

  {"code": 400, "status": "missing-param", "message": "...", "missing_param": "email"}

invalid-param 400

This status is returned when a param was invalid when passed. For example, passing an id that doesn't exist or passing an invalid email address.

  {"code": 400, "status": "invalid-param", "message": "...", "invalid_param": "email"}

application-crash 500

This status is returned when there is an internal server error. Please try again later.

  {"code": 500, "errors": "...", "status": "application-crash", "message": "..."}

mandrill-email-failed 500

This status is returned when there was an issue using Mandrill to send an email. Any time this response is returned, there will be a notification in the production notifications tab so the dev team will be away of the failure. These errors will most likely correlate with a data issue and will need to be invesigated.

  {"code": 500, "errors": "...", "status": "mandrill-email-failed", "message": "..."}

invalid-content-type 400

This status is returned if the request was made with the incorrect content-type so the request params could not be read. For more infromation on content-type, please refer to https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type.

  {"code": 400, "status": "invalid-content-type", "message": "...", "content_type_passed": "application/json", "content_type_required": "text/plain"}

route-non-existent 500

Response returned when HTTP route does not exist.

  {"code": 500, "status": "route-non-existent", "message": "..."}

Uncommon Responses

The responses below are not very common.

no-params-decoded Uncommon

This status is returned the request body was decoded, but no params where found.

  {"code": 400, "status": "no-params-decoded", "message": "..."}

invalid-encoded-params Uncommon

This status is returned when the request body could not be decoded properly. This generally means that you are requesting a sensative_params API and your request body was not base64 encoded.

  {"code": 400, "errors": "...", "status": "invalid-encoded-params"}

route-not-found Uncommon

This status is returned when the route record being requested hasn't been deployed yet.

  {"code": 404, "path": "...", "status": "route-not-found", "message": "...", "http_method": "..."}

identify-request-error Uncommon

This status is returned when there is an internal server error before the route could be identified. Please try again later.

  {"code": 500, "errors": "...", "status": "identify-request-error", "message": "..."}

service-not-found Uncommon

This status is returned when the route's API service record being requested hasn't been deployed yet.

  {"code": 404, "status": "service-not-found", "message": "...", "route_id": "...", "api_service_key": "..."}