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.

Agents

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

Fields

Field	Type	Description	Writable?
id	`ObjectId`	The ID of the agent this resource represents.	No
email	`String`	The email of the agent. This is unique and used for login credentials	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

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.

Fields

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

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'

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	Description	Required?
name	`String`	The new full name to update the lead with	No
email	`String`	The new email to update the lead with	No
muted	`Boolean`	If true, Holmes will be muted if it is not already. If false, Holmes will be unmuted if not already.	No

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.