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 [email protected].

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": "[email protected]",
        "reference_id": "1234"
      },
      {
        "type": "agent",
        "name": "Jane Doe",
        "email": "[email protected]",
        "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": "[email protected]"
          }
        ]
      },
      {
        "name": "Uptown",
        "reference_id": "43531",
        "additional_recipients": [
          {
            "name": "Mark Jones",
            "email": "[email protected]"
          }
        ]
      }
    ]'

Syncing an office mainly requires an office name.

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.

Associate Office with Agent

curl "https://keybox.payload.co/<path>/api/agents/<id_of_agent>" \
    -X PUT \
    -u secret_key_3bW9JMZtPVDOfFNzwRdfE: \
    -H "Content-Type: application/json" \
    -d '{
      "offices": [
          { "id": "offc_oPTpPxARKqQDE0YTmxevhUym" }
      ]
    }'

To associate your agents with the office, update the offices array on the agent object as shown in the example.

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 protected]",
        "buyer_name": "full_name",
        "reference_id": "34532",
        "amount": 2500,
        "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_1Bx9mhCzY3noDQbqwFBMTABvx",
  "object": "user",
  "account_id": "accnt_1DBfWr965LdfZaGZRtvCo5QGz",
  "agent_commission_method_id": "string",
  "agent_fees_method_id": "string",
  "attrs": {},
  "created_at": "2021-07-02 19:44:46",
  "current": false,
  "email": "[email protected]",
  "modified_at": "2021-07-02 19:44:46",
  "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_1hOayVhtueYzKUAgjQUVTjjhF",
  "object": "account",
  "attrs": {},
  "created_at": "2021-07-02 19:44:46",
  "earnest_deposit_accounts": [],
  "modified_at": "2021-07-02 19:44:46",
  "name": "string",
  "offices": [],
  "org_id": "string",
  "path": "string",
  "payload_client_key": "string",
  "integrations": {
    "DocuSign": {
      "enabled": true
    },
    "DotLoop": {
      "enabled": false
    }
  },
  "modules": {
    "agent_commission": {
      "enabled": true
    },
    "agent_fees": {
      "enabled": true,
      "processing_id": "string"
    },
    "dashboard": {
      "enabled": false,
      "standard_login": false
    },
    "earnest_money": {
      "enabled": false
    }
  }
}

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 required	The account name
`offices` list	Array of associated Office objects
`org_id` string readonly	The Payload org id associated with the account
`path` string required	The root url path for the account
`payload_client_key` string readonly	Payload client key for account

integrations:

DocuSign:
`enabled` bool	Toggle Docusign integration

DotLoop:
`enabled` bool	Toggle DotLoop integration

modules:

agent_commission:
`enabled` bool readonly	Toggle the agent commission dashboard module

agent_fees:
`enabled` bool readonly	Toggle the agent fee dashboard module
`processing_id` string readonly	The receiving processing account for agent fees

dashboard:
`enabled` bool	Toggle the agent dashboard
`standard_login` bool	Enable standard login access to dashboard

earnest_money:
`enabled` bool	Toggle earnest dashboard module

Properties

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

Nested Objects

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

Example

{
  "id": "prop_MXGEydwszNisIz2IfzDJxJ64",
  "object": "property",
  "agent_id": "usr_1SDghs4T3TlZlV4p6rFYzWoq4",
  "amount": 396.18,
  "attrs": {},
  "buyer_email": "[email protected]",
  "buyer_name": "full_name",
  "created_at": "2021-07-02 19:44:46",
  "escrow_account_id": "1VTLNb7Lt7f6DpVG0tlBfwP6u",
  "modified_at": "2021-07-02 19:44:46",
  "office_id": "offc_h97S9ObJ6cc8ENtcrMIY9WUw",
  "pay_link_url": "string",
  "property_name": "string",
  "received_at": "2021-07-02 19:44:46",
  "reference_id": "string",
  "sent_at": "2021-07-02 19:44:46",
  "status": "pending",
  "transaction_status": "string"
}

Attributes	Description
`id` string readonly	Object ID
`object` string readonly	Value: property
`agent_id` id	None
`amount` number	The amount of the earnest money deposit
`attrs` json	Custom object attributes
`buyer_email` email	The email of the buyer
`buyer_name` full_name	The name of the buyer
`created_at` datetime readonly	Timestamp object was created
`escrow_account_id` id	None
`modified_at` datetime readonly	Timestamp object was last updated
`office_id` id readonly: update	None
`pay_link_url` string	The payment link sent to the buyer
`property_name` string required	The name or address of the property
`received_at` datetime	The timestamp the payment was received
`reference_id` string	An optional reference id
`sent_at` datetime	The timestamp the request was sent to the buyer
`status` string	Values: pending sent received
`transaction_status` string	The status of the associated Payload transaction

Offices

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

Nested Objects

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

Example

{
  "id": "offc_26sLXM28PsNg5zr09XCMwCPBT",
  "object": "office",
  "account_id": "accnt_urD3D9YZ35xDARtxpMUv6YKD",
  "attrs": {},
  "created_at": "2021-07-02 19:44:46",
  "modified_at": "2021-07-02 19:44:46",
  "name": "string",
  "reference_id": "string",
  "additional_recipients": [
    {
      "email": "[email protected]",
      "name": "string"
    }
  ]
}

Attributes	Description
`id` string required	Object ID
`object` string readonly	Value: office
`account_id` id readonly	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

Overview

API Structure

User

Account

Property

Office

Getting Started

Authentication

API Endpoint

Data import

Syncing Agents

Syncing Offices

Associate Office with Agent

Syncing Properties

Object reference

Users

Accounts

Properties

Offices