NAV
Shell

Overview

Example Request

curl https://keybox.payload.co/<path>/api \
    -u secret_key_3bW9JMZtPVDOfFNzwRdfE:

The Keybox APIs use a RESTful API design to expose the underlying data model of the Keybox platform. You can explore the object structure below and for a full object reference, see the Object Reference section.

The Keybox API incorporates the object model primarily for Agents, Offices, and Properties. For payments, deposits, and receipt data and APIs, please refer to the Payload API Documentation.

API Structure

Keybox's API design incorporates a variety of concepts to create a simple, robust, and intuitive object structure. Below outlines the primary objects in the api and defines the object hierarchy.

account
- name: Brokerage
- path: brokerage
- users:
    ├── agent 1
    ├── agent 2
    ├── admin 1
    └── agent 3
- offices
    ├── office 1
    └── office 2
- properties
    ├── 123 Main St
    └── 454 Baker St

Getting Started

Authentication

# Curl supports HTTP basic authentication with the `-u` command
# To use the `-u` command, add a `:` onto the API key.
curl "https://keybox.payload.co/<path>/api/accounts" \
    -u secret_key_3bW9JMZtPVDOfFNzwRdfE:

Authentication with Keybox uses a simple API secret key. The secret key is passed as the username field in an HTTP Basic Auth header. Your secret key is available from your dashboard in the API Keys section under settings.

API Keys

The Keybox API is currently in private beta. To request access, reach out to your account manager or directly to keybox@payload.co.

API Endpoint

Keybox API base endpoint

https://keybox.payload.co/<path>/api

Every Keybox account has a unique url. This is set when your Keybox account is initially setup and can be configured from your settings within the Keybox admin dashboard.

Follow the url structure below to access the Keybox API replacing the <path> with your unique Keybox path.


Data import

Bulk operations can be performed for an initial data import. Each object includes a reference_id field that can be set to reference an external record or identifier. Also, all objects include a field called attrs that can be used for various custom attributes.

Syncing Agents

curl "https://keybox.payload.co/<path>/api/users" \
    -X POST \
    -u secret_key_3bW9JMZtPVDOfFNzwRdfE: \
    -H "Content-Type: application/json" \
    -d '[
      {
        "type": "agent",
        "name": "John Smith",
        "email": "john@testbroker.com",
        "reference_id": 1234
      },
      {
        "type": "agent",
        "name": "Jane Doe",
        "email": "jane@testbroker.com"
        "reference_id": 3456
      }
    ]'

Sync your agent roster by submitting a POST api request to /users with the user type of agent.

If you have the agent dashboard enabled from your Keybox dashboard settings, by creating the user record an invite email will be sent to the agent's email that they can use to setup their dashboard account.

Syncing Offices

curl "https://keybox.payload.co/<path>/api/offices" \
    -X POST \
    -u secret_key_3bW9JMZtPVDOfFNzwRdfE: \
    -H "Content-Type: application/json" \
    -d '[
      {
        "name": "Downtown",
        "reference_id": 34532,
        "additional_recipients": [
          {
            "name": "Mary Smith",
            "email": "mary@testbroker.com"
          }
        ],
        "agents": [
            { "id": "usr_oPTpPxARKqQDE0YTmxevhUym" }
        ]
      },
      {
        "name": "Uptown",
        "reference_id": 43531,
        "additional_recipients": [
          {
            "name": "Mark Jones",
            "email": "mark@testbroker.com"
          }
        ]
      }
    ]'

Syncing an office mainly requires an office name. To associate your agents with the office, an agents array can be passed along with the office as shown in the example.

If you have office admins or certain emails that should receive payment receipts for all transactions for a certain office, the office endpoint accepts an additional_recipients array.

Syncing Properties

curl "https://keybox.payload.co/<path>/api/properties" \
    -X POST \
    -u secret_key_3bW9JMZtPVDOfFNzwRdfE: \
    -H "Content-Type: application/json" \
    -d '[
      {
        "property_name": "123 Example St, New York, NY 10001",
        "buyer_email": "email@address.com",
        "buyer_name": "full_name",
        "reference_id": 34532,
        "amount": 12345,
        "agent_id": "usr_oPTpPxARKqQDE0YTmxevhUym",
        "office_id": "offc_Js8YK4G4Kj88aMI9WbewU9YO"
      }
    ]'

If there's an external database of existing pending deals, you can sync in the property and buyer details into the properties endpoint.

If your agents are using the agent dashboard you can specify the agent_id for a property and that will make that property available under that agent's dashboard.


Object reference

See below for a full reference section of the available API objects, defined fields, data types, permissions, and associated object references.

Users

https://keybox.payload.co/<path>/api/users

Nested Objects

https://keybox.payload.co/<path>/api/users/{id}/account

https://keybox.payload.co/<path>/api/users/{id}/offices

Example

{
  "id": "usr_UvWmaW2qTnbOmfRdFiaLfSKH",
  "object": "user",
  "account_id": "accnt_1Yxgstu8G5hozKXoGq2v8I6a2",
  "agent_commission_method_id": "string",
  "agent_fees_method_id": "string",
  "attrs": {},
  "created_at": "2021-05-17 20:58:27",
  "current": false,
  "email": "email@address.com",
  "modified_at": "2021-05-17 20:58:27",
  "name": "string",
  "offices": [],
  "payload_customer_id": "string",
  "payout_approval_access": true,
  "phone": "(123) 456-7890",
  "reference_id": "string",
  "status": "added",
  "type": "agent"
}
Attributes Description
id
string readonly
Object ID
object
string readonly
Value: user
account_id
id readonly: update
None
agent_commission_method_id
string
The Payload token for the agent's commission method
agent_fees_method_id
string
The Payload token for the agent's fee method
attrs
json
Custom object attributes
created_at
datetime readonly
Timestamp object was created
current
bool readonly
The session user
email
email required
Email address of the user
modified_at
datetime readonly
Timestamp object was last updated
name
string required
Full name of the user
offices
list
Array of associated Office objects
payload_customer_id
string readonly
The Payload customer id
payout_approval_access
bool readonly
Admin only: flag for user with payout approval access
phone
phone
Phone number of the user
reference_id
string
An optional external reference id
status
string readonly
Values: added invited active
type
string required
Values: agent admin

Accounts

https://keybox.payload.co/<path>/api/accounts

Nested Objects

https://keybox.payload.co/<path>/api/accounts/{id}/earnest_deposit_accounts

https://keybox.payload.co/<path>/api/accounts/{id}/offices

Example

{
  "id": "accnt_KBcxGI0K71vYTQ7E9DFxKKoX",
  "object": "account",
  "attrs": {},
  "created_at": "2021-05-17 20:58:27",
  "earnest_deposit_accounts": [],
  "modified_at": "2021-05-17 20:58:27",
  "name": "string",
  "offices": [],
  "org_id": "string",
  "path": "string",
  "payload_client_key": "string",
  "integrations": {
    "DocuSign": {
      "enabled": false
    },
    "DotLoop": {
      "enabled": false
    }
  },
  "modules": {
    "agent_commission": {
      "enabled": false
    },
    "agent_fees": {
      "enabled": true,
      "processing_id": "string"
    },
    "dashboard": {
      "enabled": false,
      "standard_login": true
    },
    "earnest_money": {
      "enabled": true
    }
  }
}
Attributes Description
id
string readonly
Object ID
object
string readonly
Value: account
attrs
json
Custom object attributes
created_at
datetime readonly
Timestamp object was created
earnest_deposit_accounts
list
Array of associated Escrow Account objects
modified_at
datetime readonly
Timestamp object was last updated
name
string
The account name
offices
list
Array of associated Office objects
org_id
string
None
path
string required
The root url path for the account
payload_client_key
string readonly
None
integrations:  
DocuSign:  
enabled
bool
Toggle Docusign integration
 
DotLoop:  
enabled
bool
Toggle DotLoop integration
 
 
modules:  
agent_commission:  
enabled
bool
None
 
agent_fees:  
enabled
bool
None
processing_id
string
None
 
dashboard:  
enabled
bool
None
standard_login
bool
None
 
earnest_money:  
enabled
bool
None
 
 

Properties

https://keybox.payload.co/<path>/api/properties

Nested Objects

https://keybox.payload.co/<path>/api/properties/{id}/office

Example

{
  "id": "prop_cPaj16D8007ifnYfidgwFcOA",
  "object": "property",
  "agent_email": "email@address.com",
  "agent_name": "full_name",
  "amount": 291.38,
  "attrs": {},
  "buyer_email": "email@address.com",
  "buyer_name": "full_name",
  "created_at": "2021-05-17 20:58:27",
  "escrow_account_id": "24yZwQDwgO4ZnvDYntGzqMKXi",
  "item_id": "string",
  "item_id_type": "string",
  "modified_at": "2021-05-17 20:58:27",
  "office_id": "offc_XpQhFEicg5oeh36dkiAflvTU",
  "pay_link_url": "string",
  "property_name": "string",
  "received_at": "2021-05-17 20:58:27",
  "sent_at": "2021-05-17 20:58:27",
  "status": "string",
  "transaction_status": "string"
}
Attributes Description
id
string readonly
Object ID
object
string readonly
Value: property
agent_email
email
None
agent_name
full_name
None
amount
number
None
attrs
json
Custom object attributes
buyer_email
email
None
buyer_name
full_name
None
created_at
datetime readonly
Timestamp object was created
escrow_account_id
id
None
item_id
string
None
item_id_type
string
None
modified_at
datetime readonly
Timestamp object was last updated
office_id
id readonly: update
None
pay_link_url
string
None
property_name
string required
None
received_at
datetime
None
sent_at
datetime
None
status
string
None
transaction_status
string
None

Offices

https://keybox.payload.co/<path>/api/offices

Nested Objects

https://keybox.payload.co/<path>/api/offices/{id}/account

Example

{
  "id": "offc_1UUfOlmxXdDpCoccgU1DWhlBA",
  "object": "office",
  "account_id": "accnt_1VVvYSGqWgBttGpxy4W8AcxSH",
  "attrs": {},
  "created_at": "2021-05-17 20:58:27",
  "modified_at": "2021-05-17 20:58:27",
  "name": "string",
  "reference_id": "string",
  "additional_recipients": [
    {
      "email": "email@address.com",
      "name": "string"
    }
  ]
}
Attributes Description
id
string readonly
Object ID
object
string readonly
Value: office
account_id
id readonly: update
ID of the associated office
attrs
json
Custom object attributes
created_at
datetime readonly
Timestamp object was created
modified_at
datetime readonly
Timestamp object was last updated
name
string
Name of the office
reference_id
string
An optional external reference id
additional_recipients:  
email
email
Email of additional recipient
name
string
Name of additional recipient