NAV Navbar
curl

Introduction

Welcome to the Structurely Holmes API! You can use our API to view, update, query both leads and agent's accounts. This API is a work in progress and is not in a final state. API endpoints, authentication flows, and availability may be subject to change at any time. If you are intestested in working with us via our API please contact us at info@structurely.com

Authentication

All requests to the API in must include the header X-Api-Authorization with your API key. There will soon be a OAuth2 flow for obtaining bearer tokens to use in the Authorization header. To get an API key please contact us.

Overview

Endpoints

All endpoints are hosted by the domain api.structurely.com. All requests must use https. Any request with the protocol http will be redirected to https with the status code 301. The path for the api will always start with /v1. Every resource endpoint will start with https://api.structurely.com/v1.

Types

Type Description
ObjectId A 24 byte hexadecimal string. See ObjectId.
Boolean A JSON boolean represented by either true or false.
Integer A plain integer. May be restricted by an interval (i.e. Intenger[0,), Integer[0,10], Integer(0,100]).
Float A floating point number.
String A plain string. When used as a url or query parameter, it must be url escaped.
DateTime A date time string that can be parsed into a time zone aware date time object.
List An array of values of either a primitive type or a schema. Usually has a type name defined (i.e. List<Agent>, List<Integer>)

Agents

The Agent resource represents an account in homechat. An agent has settings and owns leads.

Schemas

Agent

Field Type Description Readable? Writable?
id ObjectId The ID of the agent this resource represents. Yes No
email String The email of the agent. This is unique and used for login credentials Yes No

List Agents

curl 'https://api.structurely.com/v1/agents?userId=1025&email=john.richards191919%40example.com' \
  -H 'X-Api-Authorization: myapikey'

The above command returns JSON structured like this:

{
    "_metadata": {
        "collection": "agents",
        "limit": 10,
        "offset": 0,
        "total": 1
    },
    "agents": [
        {
            "id": "5b92de82f434f50034330e46",
            "email": "john.richards191919@example.com"
        }
    ]
}

This endpoint returns a list of agents sorted and/or filtered by the given parameters. This request requires the user_id parameter which refers to a third party integration user id (e.g. liondesk).

HTTP Request

GET https://api.structurely.com/v1/agents

Query Parameters

Parameter Type Description Required? Default
userId[1] String,Integer The third party user id Yes None
limit Integer[1,100] The number of results to return No 10
offset Integer[0,) Indicates the number of results to skip No 0
sort[2] String A comma separated list of fields to sort by No email
email[3] String A partial or full email to search No None
  1. This field expects the request to be coming from a system that has already integrated with Homechat. This field is expected to be removed in the near future and is only here to assist in finding an agent in Homechat that has an account in a different system.
  2. The sort string allows multiple fields with left to right precedence with optional - or + for controlling ascending and descending order
  3. String search fields use a case insensitive partial filter that can match any part of the string

Leads

The Lead resource represents a single contact possibly with a conversation in homechat. This conversation includes messages by agents, the lead, and Holmes.

Schemas

Lead

Field Type Description Readable? Writable?
id ObjectId The ID of the lead this resource represents. Yes No
name String The full name of the lead Yes Yes
email String The email of the lead Yes Yes
phone String The phone number of the lead or the format +15551234567 Yes No
firstContact Float The number of seconds after the unix epoch since first contact was made with this lead Yes No
lastContact Float The number of seconds after the unix epoch since the latest contact was made with this lead Yes No
muted Boolean Indicates whether Holmes is muted in the conversation or not. Yes Yes

List Leads

curl 'https://api.structurely.com/v1/leads?ownerId=59275069dec26a0d20fcc41e&name=john' \
  -H 'X-Api-Authorization: myapikey'

The above command returns JSON structured like this:

{
  "_metadata": {
    "collection": "leads",
    "limit": 10,
    "offset": 0,
    "total": 3
  },
  "leads": [
    {
      "id": "5b317f7f97f5a50048e1a516",
      "name": "John Doe",
      "email": "jdoe@example.com",
      "phone": "+15551234567",
      "firstContact": 1529970559.365,
      "lastContact": 1530572384.613,
      "muted": false
    },
    {
      "id": "5a8b7ce54aecff0034c31776",
      "name": "john doe",
      "email": "the.real.jdoe@example.com",
      "phone": "+15551112222",
      "firstContact": 1519090916.902,
      "lastContact": 1519090973.948,
      "muted": false
    },
    {
      "id": "5a690b0ef4a8dc00359afb57",
      "name": "John Harkin",
      "email": "jharkin@example.com",
      "phone": "+15557654321",
      "firstContact": 1516833549.595,
      "lastContact": 1516833576.27,
      "muted": true
    }
  ]
}

This endpoint returns a list of leads sorted and/or filtered by the given parameters. This request requires the ownerId parameter which refers to an agent id.

HTTP Request

GET https://api.structurely.com/v1/leads

Query Parameters

Parameter Type Description Required? Default
ownerId ObjectId The id of the agent that owns this lead Yes None
limit Integer[1,100] The number of results to return No 10
offset Integer[0,) Indicates the number of results to skip No 0
sort[1] String A comma separated list of fields to sort by No -lastContact
name[2] String A partial or full name to search No None
email[2] String A partial or full email to search No None
phone[2] String A partial or full phone number to search No None
  1. The sort string allows multiple fields with left to right precedence with optional - or + for controlling ascending and descending order
  2. String search fields use a case insensitive partial filter that can match any part of the string

Get Lead

curl 'https://api.structurely.com/v1/leads/5ab1973c62c5be0034c2102c' \
  -H 'X-Api-Authorization: myapikey'

The above command returns JSON structured like this:

{
  "id": "5ab1973c62c5be0034c2102c",
  "name": "John Doe",
  "email": "jdoe@example.com",
  "phone": "+15551234567",
  "firstContact": 1529970559.365,
  "lastContact": 1530572384.613,
  "muted": false
}

This endpoint returns a specific lead.

HTTP Request

GET https://api.structurely.com/v1/leads/<id>

URL Parameters

Parameter Description
id The ID of the lead to retrieve

Update Lead

curl 'https://api.structurely.com/v1/leads/5ab1973c62c5be0034c2102c' \
  -X PATCH \
  -H 'X-Api-Authorization: myapikey' \
  -H 'Content-Type: application/json' \
  -d '{ "muted": true }'

The above command returns JSON structured like this:

{
  "id": "5ab1973c62c5be0034c2102c",
  "name": "John Doe",
  "email": "jdoe@example.com",
  "phone": "+15551234567",
  "firstContact": 1529970559.365,
  "lastContact": 1530572384.613,
  "muted": true
}

This endpoint updates a specific lead and returns the modified lead object.

HTTP Request

PATCH https://api.structurely.com/v1/leads/<id>

URL Parameters

Parameter Description
id The ID of the lead to update

Body Parameters[^]

Parameter Type
name String
email String
muted Boolean

Conversations

The Conversation resource represents a conversational exchange with Aisa. This is distict from a lead because it interfaces directly with aisa rather than showing up for an agent in homechat.

Schemas

Conversation

Field Type Description Readable? Writable? Required? Default
id ObjectId The ID of the conversation this resource represents. Yes No No
settings ConversationSettings The settings for holmes per this conversation. Yes No Yes
slots List<ConversationSlot> A list of extracted or pre-filled values relating to the conversation. Yes No Yes
muted Boolean A boolean flag to tell Holmes whether or not this conversation is muted. A muted conversation can still receive messages but will generate no replies. Yes Yes No false
messages List<ConversationItem> A list of lead messages and system responses with the context value with each response. No No Yes

ConversationSettings

Field Type Description Readable? Writable? Required? Default
timeZone String The time zone the realtor and/or lead. (See list) Yes No Yes
holmesName String The name of conversation AI to use in responses. Yes No No Aisa

ConversationSlot

Field Type Description Readable? Writable? Required?
name[a] String The name of the slot. Yes No Yes
value[a] Any The value of the slot. Yes No Yes

ConversationItem

Field Type Description Readable? Writable? Required?
message Message A message the lead sent. No Yes Yes[1]
respone Message A respone sent by the system. No Yes Yes[1]
context[b] String The context set by the response in this conversation item. No Yes Yes[2]
  1. message and response are mutually exclusive. At least one is required to be present but not both.
  2. context is only required if the response field is used.

Message

Field Type Description Readable? Writable? Required?
text String The text of the message. No Yes Yes
received DateTime The time the message was sent or received. No Yes Yes

Slots and Contexts

Slots

Name Type Description
name String The name of the lead.
email String The email of the lead.
phone String The phone number of the lead.
address String The address of the property a buyer lead is interested in.
selling_address String The address of the property a seller lead is trying to sell.
lead_types List A list of types of leads. Can be any combination of buyer, seller, or renter.
lead_source String The source of the lead. Can be any string.
agent_name String The name of the agent Holmes is messaging on the behalf of.
agent_phone String The phone of the agent.
agent_email String The email of the agent.
agency_name String The name of the agency the agent works for or Holmes is messaging on the behalf of.
office_location String The general location of the realtor office the system is representing.

Contexts

Name
general
expect_address
expect_agent_status
expect_appointment
expect_baths
expect_beds
expect_call_availability
expect_contingency
expect_email
expect_financing_status
expect_lead_type
expect_listing_appointment
expect_location
expect_name
expect_phone
expect_price
expect_selling_address
expect_showing_appointment
expect_timeframe

Create Conversation

curl 'https://api.structurely.com/v1/conversations' \
  -X POST \
  -H 'X-Api-Authorization: myapikey' \
  -H 'Content-Type: application/json' \
  -d '{ "settings": { "time_zone": "America/Chicago" }, "slots": [{ "name": "email", "value": "jdoe@example.com" }], "messages": [{ "response": { "text": "Hello, what is your name?", "received": "2018-12-08T15:20:00.000Z" }, "context": "expect_name }, { "message": { "text": "John", "received": "2018-12-08T16:34:00.000Z" } }] }'

The above command returns JSON structured like this:

{
    "id": "5c09a4416241ea2c293275b8",
    "settings": {
        "holmesName": "Aisa",
        "timeZone": "America/Chicago"
    },
    "slots": [
        {
            "name": "email",
            "value": "jdoe@example.com"
        }
    ],
    "muted": false
}

This endpoint creates and returns a new conversation object.

HTTP Request

POST https://api.structurely.com/v1/conversations

Body Parameters[^]

Parameter Type
settings ConversationSettings
slots List<ConversationSlot>
muted Boolean
messages List<ConversationItem>

Get Conversation

curl 'https://api.structurely.com/v1/conversations/5c09a4416241ea2c293275b8' \
  -H 'X-Api-Authorization: myapikey'

The above command returns JSON structured like this:

{
    "id": "5c09a4416241ea2c293275b8",
    "settings": {
        "holmesName": "Aisa",
        "timeZone": "America/Chicago"
    },
    "slots": [
        {
            "name": "name",
            "value": "John Doe"
        },
        {
            "name": "email",
            "value": "jdoe@example.com"
        },
        {
            "name": "phone",
            "value": "+15551234567"
        },
        {
            "name": "address",
            "value": "123 Main St."
        },
        {
            "name": "agent_name",
            "value": "Andi Agent"
        },
        {
            "name": "lead_types",
            "value": [
                "buyer"
            ]
        }
    ],
    "muted": false
}

This endpoint returns a specific conversation.

HTTP Request

GET https://api.structurely.com/v1/conversations/<id>

URL Parameters

Parameter Description
id The ID of the conversation to retrieve

Update Conversation

curl 'https://api.structurely.com/v1/conversations/5c09a4416241ea2c293275b8' \
  -X PATCH \
  -H 'X-Api-Authorization: myapikey' \
  -H 'Content-Type: application/json' \
  -d '{ "muted": true }'

The above command returns JSON structured like this:

{
    "id": "5c09a4416241ea2c293275b8",
    "settings": {
        "holmesName": "Aisa",
        "timeZone": "America/Chicago"
    },
    "slots": [
        {
            "name": "email",
            "value": "jdoe@example.com"
        }
    ],
    "muted": true
}

This endpoint updates and returns a specific conversation object.

HTTP Request

PATCH https://api.structurely.com/v1/conversations/<id>

URL Parameters

Parameter Description
id The ID of the conversation to update

Body Parameters[^]

Parameter Type
muted Boolean

Create Message

curl 'https://api.structurely.com/v1/conversations/5c09a4416241ea2c293275b8/messages'
  -X POST \
  -H 'X-Api-Authorization: myapikey' \
  -H 'Content-Type: application/json' \
  -d '{ "text": "Hello World", "received": "2018-12-09T11:44:00.000Z" }'

> The above command returns JSON structured like this:

```json
{
    "id": "5c09a45e6241ea2c293275bf",
    "text": "Hello World",
    "received": "2018-12-09T11:44:00.000Z"
}

This endpoint creates a new lead message for the conversation for us to extract and classify.

HTTP Request

POST https://api.structurely.com/v1/conversations/<id>/messages

URL Parameters

Parameter Description
id The ID of the conversation to retrieve

Body Parameters[^]

Parameter Type
text String
received DateTime

Create Response

curl 'https://api.structurely.com/v1/conversations/5c09a4416241ea2c293275b8/responses'
  -X POST \
  -H 'X-Api-Authorization: myapikey' \
  -H 'Content-Type: application/json' \
  -d '{ "text": "Hello There", "received": "2018-12-09T11:44:00.000Z" }'

> The above command returns JSON structured like this:

```json
{
    "id": "5c09a4416241ea2c293275b5",
    "text": "Hello There",
    "received": "2018-12-09T11:44:00.000Z"
}

This endpoint creates a new system response for the conversation. This does nothing in our system other than act as a send receipt notifying us that an outbound message was sent on behalf of the system/realtor.

HTTP Request

POST https://api.structurely.com/v1/conversations/<id>/responses

URL Parameters

Parameter Description
id The ID of the conversation to retrieve

Body Parameters[^]

Parameter Type
text String
received DateTime

Errors

The Holmes API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request was invalid.
401 Unauthorized -- No API key provided.
403 Forbidden -- Your API key is invalid.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access an endpoint with an invalid method.
500 Internal Server Error -- We had a problem with our server. Try again later.
502 Bad Gateway -- Our backend services are unavailable. Please try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
504 Gateway Timeout -- Our backend services are taking too long to respond. Please try again later.