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.

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
  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.

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
  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 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.