CircleLoop Developer API Documentation API Reference

Using this API and its relevent documentation you can create apps that can utalise CircleLoop's abilities.

API Endpoint
https://api.circleloop.co.uk/v1
Schemes: https
Version: 0.0.1

Authentication

Key & Secret

This is used to authenticate any request made to the API. Using your provided key and secret, the secret should follow the key and be wrapped in a Base64 format.

type
basic
name
Authorization
in
header
scopes
write

Modify information via the API

read

Read information retuened by the API

Users

Get and put information about a single or multiple users.

Users

Get information about your user

GET /my/user

This endpoint will return a user object with relevent information regarding this user

200 OK
User

Response was successful

404 Not Found

User couldn't be found, it might not exist or may have been deleted

409 Conflict

Invalid data, check the authorization token is correct

500 Internal Server Error

An internal error occured

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
  "clientID": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
  "fullName": "Joe Bloggs",
  "email": "joe@example.com",
  "created": 1573057488,
  "defaultNumber": "441234501234"
}
Key & Secret read
Users

Update information about your user

PUT /my/user

This endpoint will enable you to update select properties regarding a single user.

Put User

Define what information to update on this user. Not all fields are required however, at least one field is required to validate a change.

Request Content-Types: application/json
Request Example
{
  "fullName": "Joe Bloggs",
  "email": "joe@example.com",
  "snoozeExpires": 1573057488,
  "voicemail": "voicemail",
  "outOfHours": false,
  "teams": [
    "abcd0000-7ab7-1234-8abc-3ebd0123456f"
  ]
}
200 OK
User

Response was successful

404 Not Found

Something is missing in the body or an ID is missing

409 Conflict

Either the body or ID is conflicted

500 Internal Server Error

An internal error has occured

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
  "clientID": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
  "fullName": "Joe Bloggs",
  "email": "joe@example.com",
  "created": 1573057488,
  "defaultNumber": "441234501234"
}
Key & Secret write
Users

Get information about all users within your client

GET /my/users

This endpoint will return an array of objects with the same information as if you were getting a single user.

200 OK
Users

200 response

404 Not Found

Users couldn't be found, they might not exist or may have been deleted

409 Conflict

Invalid data, check the authorization token is correct

500 Internal Server Error

An internal error occured

Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
    "clientID": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
    "fullName": "Joe Bloggs",
    "email": "joe@example.com",
    "created": 1573057488,
    "defaultNumber": "441234501234"
  }
]
Key & Secret read
Users

Get information about a specific user

GET /user

This endpoint will return a user object with relevent information regarding this user

id: string
in query

Get a information about a user from their ID.

200 OK
User

Response was successful

404 Not Found

Something is missing in the body or an ID is missing

409 Conflict

Either the body or ID is conflicted

500 Internal Server Error

An internal error has occured

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
  "clientID": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
  "fullName": "Joe Bloggs",
  "email": "joe@example.com",
  "created": 1573057488,
  "defaultNumber": "441234501234"
}
Key & Secret read
Users

Update information about a specific user

PUT /user

This endpoint will return a user object with relevent information regarding this user

Put User

Define what information to update on this user. Not all fields are required however, at least one field is required to validate a change.

id: string
in query

Update a information about a user from their ID. Ensure this is a valid ID value from within your client.

Request Content-Types: application/json
Request Example
{
  "fullName": "Joe Bloggs",
  "email": "joe@example.com",
  "snoozeExpires": 1573057488,
  "voicemail": "voicemail",
  "outOfHours": false,
  "teams": [
    "abcd0000-7ab7-1234-8abc-3ebd0123456f"
  ]
}
200 OK
User

Response was successful

404 Not Found

Something is missing in the body or an ID is missing

409 Conflict

Either the body or ID is conflicted

500 Internal Server Error

An internal error has occured

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
  "clientID": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
  "fullName": "Joe Bloggs",
  "email": "joe@example.com",
  "created": 1573057488,
  "defaultNumber": "441234501234"
}
Key & Secret write

Teams

Get your teams and update specific information

Teams

Get all teams within this client

GET /my/teams

This will return an array of all teams within the authorised client. The array returned will include the teams unique ID, name of the team and the members within this team.

id: string
in path

The unique ID of the requested Contact

200 OK
Teams

Request was returned successfully

404 Not Found

Something couldn't be found during the request, more information can be found in the query response

409 Conflict

There was an invalid response during this query

500 Internal Server Error

An internal error occured, try your request again

Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "ID": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
    "name": "Sales Team",
    "members": [
      "abcd0000-7ab7-1234-8abc-3ebd0123456f"
    ]
  }
]
Key & Secret read
Teams

Get a specific team within this client

GET /team/{id}

This will return a single team within the authorised client. The information object will include the teams unique ID, name of the team and the members within this team.

id: string
in path

The unique ID of the requested Team

200 OK
Team

Data was returned successfully

404 Not Found

Something couldn't be found during the request, more information can be found in the query response

409 Conflict

There was an invalid response during this query

500 Internal Server Error

An internal error occured, try your request again

Response Content-Types: application/json
Response Example (200 OK) 
{
  "ID": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
  "name": "Sales Team",
  "members": [
    "abcd0000-7ab7-1234-8abc-3ebd0123456f"
  ]
}
Key & Secret read
Teams

Admins only - Update a specific team within this client

PUT /team/{id}

This will allow you to update a specific team within the authorised client. The endpoint will allow you to change the teams name, its Out of Hours option, how it handles voicemail and who is in this team.

Put Team

Define what information to update on this team. Not all fields are required however, at least one field is required to validate a change.

"voicemail" accepts "voicemail", "ring_out" or "voicemail_no_message"

id: string
in query

The unique ID of the requested Team

Request Content-Types: application/json
Request Example
{
  "name": "Sales Team",
  "outOfHours": false,
  "voicemail": "ring_out",
  "members": [
    "abcd0000-7ab7-1234-8abc-3ebd0123456f"
  ]
}
200 OK
Team

The task completed successfully

404 Not Found

Something couldn't be found during the request, more information can be found in the query response

409 Conflict

There was an invalid response during this query

500 Internal Server Error

An internal error occured, try your request again

Response Content-Types: application/json
Response Example (200 OK) 
{
  "ID": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
  "name": "Sales Team",
  "members": [
    "abcd0000-7ab7-1234-8abc-3ebd0123456f"
  ]
}
Key & Secret write

Menus

Get your menus and update specific information

Menus

Get all menus within this client

GET /my/menus

This will return an array of all menus within the authorised client. The array returned will include the menus unique ID, name of the menu and call extensions defined within the menu.

200 OK
Menus

Data was returned successfully

404 Not Found

Something couldn't be found during the request, more information can be found in the query response

409 Conflict

There was an invalid response during this query

500 Internal Server Error

An internal error occured, try your request again

Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "ID": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
    "name": "Main Office",
    "extensions": {
      "1": {
        "userID": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
        "display": "Joe Bloggs"
      },
      "6": {
        "teamID": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
        "display": "Sales Team"
      }
    }
  }
]
Key & Secret read
Menus

Get a specific menu within this client

GET /menu/{id}

This will return a single menu within the authorised client. The object returned will include the menus unique ID, name of the menu and call extensions defined within the menu.

id: string
in path

The unique ID of the requested Menu

200 OK
Menu

Data was returned successfully

404 Not Found

Something couldn't be found during the request, more information can be found in the query response

409 Conflict

There was an invalid response during this query

500 Internal Server Error

An internal error occured, try your request again

Response Content-Types: application/json
Response Example (200 OK) 
{
  "ID": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
  "name": "Main Office",
  "extensions": {
    "1": {
      "userID": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
      "display": "Joe Bloggs"
    },
    "6": {
      "teamID": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
      "display": "Sales Team"
    }
  }
}
Key & Secret read
Menus

Admins only - Update a specific menu within this client

PUT /menu/{id}

This will allow you to update a specific menu within the authorised client. The endpoint will allow you to change the menus name, its Out of Hours option, how it handles voicemail and what extensions it can have attached to it.

Put Menu

Define what information to update on this menu. Not all fields are required however, at least one field is required to validate a change.

"voicemail" accepts "voicemail", "ring_out" or "voicemail_no_message"

id: string
in path

The unique ID of the requested Menu

Request Content-Types: application/json
Request Example
{
  "name": "Main Office",
  "outOfHours": false,
  "voicemail": "voicemail",
  "extensions": [
    {
      "id": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
      "value": 1
    }
  ]
}
200 OK
Menu

The task completed successfully

404 Not Found

Something couldn't be found during the request, more information can be found in the query response

409 Conflict

There was an invalid response during this query

500 Internal Server Error

An internal error occured, try your request again

Response Content-Types: application/json
Response Example (200 OK) 
{
  "ID": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
  "name": "Main Office",
  "extensions": {
    "1": {
      "userID": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
      "display": "Joe Bloggs"
    },
    "6": {
      "teamID": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
      "display": "Sales Team"
    }
  }
}
Key & Secret write

Contacts

Get your contacts, add and update specific information

Contacts

Get all user contacts

GET /my/contacts

This will return an array of all contacts attached to this user. The array will include the contacts unique ID, name, potential phone numbers and email addresses, as well as its soruce.

200 OK
Contacts

Request was returned successfully

404 Not Found

Something couldn't be found during the request, more information can be found in the query response

409 Conflict

There was an invalid response during this query

500 Internal Server Error

An internal error occured, try your request again

Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "ID": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
    "fullName": "Joe Bloggs",
    "phoneNumbers": [
      {
        "numberE164": "441234501234",
        "label": "Direct Dial"
      }
    ],
    "emails": [
      {
        "email": "joe@example.com",
        "label": "Personal"
      }
    ],
    "source": "circleloop"
  }
]
Key & Secret read
Contacts

Get a contact

GET /contact/{id}

This will return a signle contact attached to this user based off its ID. The object will include the contacts unique ID, name, potential phone numbers and email addresses, as well as its soruce.

id: string
in path

The unique ID of the requested Contact

200 OK
Contact

Request was returned successfully

404 Not Found

Something couldn't be found during the request, more information can be found in the query response

409 Conflict

There was an invalid response during this query

500 Internal Server Error

An internal error occured, try your request again

Response Content-Types: application/json
Response Example (200 OK) 
{
  "ID": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
  "fullName": "Joe Bloggs",
  "phoneNumbers": [
    {
      "numberE164": "441234501234",
      "label": "Direct Dial"
    }
  ],
  "emails": [
    {
      "email": "joe@example.com",
      "label": "Personal"
    }
  ],
  "source": "circleloop"
}
Key & Secret read
Contacts

Update a contact

PUT /contact/{id}

This will allow you to make changes to a contact based off its unique ID. The object will include the contacts unique ID, name, potential phone numbers and email addresses, as well as its soruce.

Put Contact

Define what information to update on this contact. Not all fields are required however, at least one field is required to validate a change.

id: string
in path

The unique ID of the requested Contact

Request Content-Types: application/json
Request Example
{
  "firstName": "Joe",
  "lastName": "Bloggs",
  "companyName": "CircleLoop",
  "jobTitle": "Customer Success",
  "source": "MyCRM",
  "phoneNumbers": [
    {
      "numberE164": "441234501234",
      "label": "Home"
    }
  ],
  "emails": [
    {
      "email": "joe@example.com",
      "label": "Personal"
    }
  ]
}
200 OK
Contact

Request was returned successfully

404 Not Found

Something couldn't be found during the request, more information can be found in the query response

409 Conflict

There was an invalid response during this query

500 Internal Server Error

An internal error occured, try your request again

Response Content-Types: application/json
Response Example (200 OK) 
{
  "ID": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
  "fullName": "Joe Bloggs",
  "phoneNumbers": [
    {
      "numberE164": "441234501234",
      "label": "Direct Dial"
    }
  ],
  "emails": [
    {
      "email": "joe@example.com",
      "label": "Personal"
    }
  ],
  "source": "circleloop"
}
Key & Secret write
Contacts

Delete a contact

DELETE /contact/{id}

This will allow you to delete a contact based off its unique ID.

id: string
in path

The unique ID of the requested Contact

200 OK
Delete Contact

Request was returned successfully

404 Not Found

Something couldn't be found during the request, more information can be found in the query response

409 Conflict

There was an invalid response during this query

500 Internal Server Error

An internal error occured, try your request again

Response Content-Types: application/json
Response Example (200 OK) 
{
  "message": "Contact with ID abcd0000-7ab7-1234-8abc-3ebd0123456f has been deleted"
}
Key & Secret read
Contacts

Create a contact

POST /contact

This will allow you to create a contact. It requires a "firstName" string, "lastName" string and a "phoneNumbers" array. It can also accept an "emails" array, "jobTitle" string, "companyName" string and "source" string.

Put Contact

Define what information to post for this contact.

Request Content-Types: application/json
Request Example
{
  "firstName": "Joe",
  "lastName": "Bloggs",
  "companyName": "CircleLoop",
  "jobTitle": "Customer Success",
  "source": "MyCRM",
  "phoneNumbers": [
    {
      "numberE164": "441234501234",
      "label": "Home"
    }
  ],
  "emails": [
    {
      "email": "joe@example.com",
      "label": "Personal"
    }
  ]
}
200 OK
Contact

Request was returned successfully

404 Not Found

Something couldn't be found during the request, more information can be found in the query response

409 Conflict

There was an invalid response during this query

500 Internal Server Error

An internal error occured, try your request again

Response Content-Types: application/json
Response Example (200 OK) 
{
  "ID": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
  "fullName": "Joe Bloggs",
  "phoneNumbers": [
    {
      "numberE164": "441234501234",
      "label": "Direct Dial"
    }
  ],
  "emails": [
    {
      "email": "joe@example.com",
      "label": "Personal"
    }
  ],
  "source": "circleloop"
}
Key & Secret write

Clients

Get and put information about a selected client

Clients

Get information about your client

GET /my/client

This endpoint will return a single object containing select information about your client, including their ID and name.

200 OK
Client

200 response

404 Not Found

Client couldn't be found, they might not exist or may have been deleted

409 Conflict

Invalid data, check the authorization token is correct

500 Internal Server Error

An internal error occured

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
  "name": "CircleLoop"
}
Key & Secret read
Clients

Update your client

PUT /my/client

This endpoint will only accept a name string. To use this endpoint, the users level must be an admin.

200 OK
Client

200 response

404 Not Found

Client couldn't be found, they might not exist or may have been deleted

409 Conflict

Invalid data, check the authorization token is correct

500 Internal Server Error

An internal error occured

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
  "name": "CircleLoop"
}
Key & Secret write

Analytics

Get analytical data from certain areas

Analytics

Number Summary

GET /analytics/numbers-summary

This will return statistical data for all phone numbers within your client. You must be an Admin to complete this request.

from: number
in query

Unix timestamp of the date the analytics data should begin

to: number
in query

Unix timestamp of the date the analytics data should end

span: string
in query

This defines how your data is presented. Either by "day", "week" or "month".

timezone: string
in query

This defines what timezone you data should be presented. For example; "Europe/London".

200 OK
Number Analytics Summary

200 response

404 Not Found

Information couldn't be found, it might not exist or may have been deleted

409 Conflict

Invalid data, check the authorization token is correct

500 Internal Server Error

An internal error occured

Response Content-Types: application/json
Response Example (200 OK) 
{
  "data": [
    {
      "numberE164": "441234501234",
      "total": 91,
      "inbound": 4,
      "outbound": 84,
      "missed": 3,
      "tcd": 10978,
      "acd": 125,
      "ttta": 40,
      "tta": 10
    }
  ]
}
Key & Secret read
Analytics

Specific Number Analytics

GET /analytics/search-number/{number}

This will return statistical data for a specific phone number within your client. You must be an Admin to complete this request.

number: string
in path

(no description)

from: number
in query

Unix timestamp of the date the analytics data should begin

to: number
in query

Unix timestamp of the date the analytics data should end

span: string
in query

This defines how your data is presented. Either by "day", "week" or "month".

timezone: string
in query

This defines what timezone you data should be presented. For example; "Europe/London".

200 OK
Number Search Analytics

200 response

404 Not Found

Information couldn't be found, it might not exist or may have been deleted

409 Conflict

Invalid data, check the authorization token is correct

500 Internal Server Error

An internal error occured

Response Content-Types: application/json
Response Example (200 OK) 
{
  "data": [
    {
      "from": "2020-09-26T23:00:00.000Z",
      "to": "2020-09-27T22:59:59.999Z",
      "fromMs": 1601161200000,
      "toMs": 1601247599999,
      "label": "Sun 27th",
      "inbound": 5,
      "outbound": 9,
      "missed": 0
    }
  ],
  "totals": {
    "numberE164": "441234501234",
    "total": 14,
    "inbound": 5,
    "outbound": 9,
    "missed": 0,
    "acd": 94,
    "tcd": 2627,
    "tta": 4
  }
}
Key & Secret read
Analytics

Team Summary

GET /analytics/teams-summary

This will return statistical data for all teams within your client. You must be an Admin to complete this request.

from: number
in query

Unix timestamp of the date the analytics data should begin

to: number
in query

Unix timestamp of the date the analytics data should end

span: string
in query

This defines how your data is presented. Either by "day", "week" or "month".

timezone: string
in query

This defines what timezone you data should be presented. For example; "Europe/London".

200 OK
Team Analytics Summary

200 response

404 Not Found

Information couldn't be found, it might not exist or may have been deleted

409 Conflict

Invalid data, check the authorization token is correct

500 Internal Server Error

An internal error occured

Response Content-Types: application/json
Response Example (200 OK) 
{
  "data": [
    {
      "teamID": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
      "name": "Joe Bloggs",
      "total": 91,
      "inbound": 4,
      "outbound": 84,
      "missed": 3,
      "tcd": 10978,
      "acd": 125,
      "ttta": 40,
      "tta": 10
    }
  ]
}
Key & Secret read
Analytics

User Summary

GET /analytics/users-summary

This will return statistical data for all users within your client. You must be an Admin to complete this request.

from: number
in query

Unix timestamp of the date the analytics data should begin

to: number
in query

Unix timestamp of the date the analytics data should end

span: string
in query

This defines how your data is presented. Either by "day", "week" or "month".

timezone: string
in query

This defines what timezone you data should be presented. For example; "Europe/London".

200 OK
User Analytics Summary

200 response

404 Not Found

Information couldn't be found, it might not exist or may have been deleted

409 Conflict

Invalid data, check the authorization token is correct

500 Internal Server Error

An internal error occured

Response Content-Types: application/json
Response Example (200 OK) 
{
  "data": [
    {
      "userID": "abcd0000-7ab7-1234-8abc-3ebd0123456f",
      "fullName": "Joe Bloggs",
      "total": 91,
      "inbound": 4,
      "outbound": 84,
      "missed": 3,
      "tcd": 10978,
      "acd": 125,
      "ttta": 40,
      "tta": 10
    }
  ]
}
Key & Secret read