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'

{
    "_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

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.
The sort string allows multiple fields with left to right precedence with optional - or + for controlling ascending and descending order
String search fields use a case insensitive partial filter that can match any part of the string

The userId parameter will be removed in the future. Because of the way the system is set up currently, this parameter must be used until changes can be made to the API. Users will be notified before these changes are made to the API.

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 in the format `+15551234567`.	Yes	No
readiness	`String`	The readiness of the lead. Can be one of the following values: `active`, `just_looking`, `researching`, or an empty string.	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
conversation	`LeadConversation`	The conversation metadata object for this lead.	Yes	No

LeadConversation

Field	Type	Description	Readable?	Writable?
collection	`String`	Always the value `lead.conversation`.	Yes	No
total	`Integer`	The total number of messages sent by the lead, Holmes, and the agent.	Yes	No
next^[1]	`String`	The url for the next 100 or fewer messages in the sequence.	Yes	No

If this object is not part of a response in a sequence, the next value will be the url for the latest 100 messages for this lead conversation.

LeadMessage

Field	Type	Description	Readable?	Writable?
id	`ObjectId`	The ID of the message for this conversation.	Yes	No
received	`Float`	The unix timestamp this message was received/sent.	Yes	No
text	`String`	The text of the message that was sent or received.	Yes	No
type^[1]	`String`	The type of the message. It will either be `message`, `response`, or `agentMessage`.	Yes	No

The type message is set if the message was sent by the lead. The type response is set if the message was sent by Holmes. The type agentMessage is set if the message was sent by the agent from homechat.

List Leads

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

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

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

The sort string allows multiple fields with left to right precedence with optional - or + for controlling ascending and descending order
String search fields use a case insensitive partial filter that can match any part of the string

The ownerId parameter will be removed in the future. Because of the way the system is set up currently, this parameter must be used until changes can be made to the API. Users will be notified before these changes are made to the API.

Get Lead

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

{
  "id": "5ab1973c62c5be0034c2102c",
  "name": "John Doe",
  "email": "jdoe@example.com",
  "phone": "+15551234567",
  "readiness": "researching",
  "firstContact": 1529970559.365,
  "lastContact": 1530572384.613,
  "muted": false,
  "conversation": {
    "collection": "lead.conversation",
    "next": "https://api.structurely.com/v1/leads/5ab1973c62c5be0034c2102c/conversation",
    "total": 108
  }
}

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

Get Lead Conversation

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

{
  "_metadata": {
    "collection": "lead.conversation",
    "next": "https://api.structurely.com/v1/leads/5ab1973c62c5be0034c2102c/conversation?before=1540400827.866",
    "total": 108
  },
  "conversation": [
    {
      "id": "5bd0a6bbbfd5b5002268f971",
      "received": 1540400827.866,
      "text": "It's always helpful to have financing figured out early in the process!",
      "type": "response"
    },
    ,
    ,
    ,
    {
      "id": "5c018167def58d0021d267cd",
      "received": 1543602535.414,
      "text": "Thank's for all the help. I'm really excited to see this home tomorrow.",
      "type": "message"
    }
  ]
}

This endpoint returns a specific lead's conversaton. It will return no more than 100 messages at a time. The _metadata.next value gives the url that will return the next batch of messages in the sequence. If there are no more messages _metadata.next will be null. If the before parameter is used, the next batch will be before the earliest message and if after is used, the next batch will be after the latest message. If there is no parameter defined the latest 100 messages are returned and the _metadata.next url will be for the previous batch with a before parameter. The _metadata.total value returns the total number of messages in the conversation.

HTTP Request

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

URL Parameters

Parameter	Description
id	The ID of the lead to retrieve the conversation for

Query Parameters

Parameter	Type	Description	Required?	Default
before^[1]	`Float`	The unix timestamp all messages must have been received before	No	None
after^[1]	`Float`	The unix timestamp all messages must have been received after	No	None

The before and after parameters are mutually exclusive. Neither is required but only one may be present.

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 }'

{
  "id": "5ab1973c62c5be0034c2102c",
  "name": "John Doe",
  "email": "jdoe@example.com",
  "phone": "+15551234567",
  "readiness": "just_looking",
  "firstContact": 1529970559.365,
  "lastContact": 1530572384.613,
  "muted": true,
  "conversation": {
    "collection": "lead.conversation",
    "next": "https://api.structurely.com/v1/leads/5ab1973c62c5be0034c2102c/conversation",
    "total": 108
  }
}

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`
stages	`List<String>`	A list of stages this conversation is currently in.	Yes	No	No
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
leadTypes	`List<String>`	The lead types that will be supported in this conversation. Possible values are `buyer`, `seller`, and `renter`	Yes	No	No	`['buyer', 'seller']`

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]

message and response are mutually exclusive. At least one is required to be present but not both.
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
_metadata^[1]	`MessageMetaData`	An optional metadata object to set the outgoing context for a response.	No	Yes	No

_metadata is only used when creating a response object.

MessageMetaData

Field	Type	Description	Readable?	Writable?	Required?
context	`String`	The outgoing context of this response. Used by Holmes to classify messages sent after this response.	No	Yes	No

Slots, Contexts, and Stages

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 lead types this lead is considered as. 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.
readiness	String	The readiness of the lead. Can be one of the following values: `active`, `just_looking`, `researching`, or an empty string.

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

Stages

Name	Description
not_responded	The lead has not responded in this conversation.
responded	The lead has responded in this conversation.
not_interested	The lead has indicated no interest or opted out of communication in this conversation.
interested	The lead has responded and has not been classified as not interested.
needs_follow_up	The lead has reached a conclusion in the conversation that requires further follow-up.

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" } }] }'

{
    "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'

{
    "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 }'

{
    "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" }'

{
    "_metadata": {
        "conversation": "5c09a4416241ea2c293275b8",
        "messages": 2,
        "responses": 1
    },
    "message": {
        "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 '{ "_metadata": { "context": "expect_showing_appointment" }, "text": "Hello There", "received": "2018-12-09T11:44:00.000Z" }'

{
    "_metadata": {
        "conversation": "5c09a4416241ea2c293275b8",
        "context": "expect_showing_appointment",
        "messages": 2,
        "responses": 2
    },
    "response": {
        "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
_metadata	`MessageMetaData`
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.

Introduction

Authentication

Overview

Endpoints

Types

Agents

Schemas

Agent

List Agents

HTTP Request

Query Parameters

Leads

Schemas

Lead

LeadConversation

LeadMessage

List Leads

HTTP Request

Query Parameters

Get Lead

HTTP Request

URL Parameters

Get Lead Conversation

HTTP Request

URL Parameters

Query Parameters

Update Lead

HTTP Request

URL Parameters

Body Parameters[^]

Conversations

Schemas

Conversation

ConversationSettings

ConversationSlot

ConversationItem

Message

MessageMetaData

Slots, Contexts, and Stages

Slots

Contexts

Stages

Create Conversation

HTTP Request

Body Parameters[^]

Get Conversation

HTTP Request

URL Parameters

Update Conversation

HTTP Request

URL Parameters

Body Parameters[^]

Create Message

HTTP Request

URL Parameters

Body Parameters[^]

Create Response

HTTP Request

URL Parameters

Body Parameters[^]

Errors

Body Parameters^{[^]}

Body Parameters^{[^]}

Body Parameters^{[^]}

Body Parameters^{[^]}

Body Parameters^{[^]}