Introduction

Our API allows developers to integrate messaging and contact management capabilities directly into their applications. It provides RESTful endpoints designed for automation, system integrations, and scalable communication workflows.

All requests and responses are formatted in JSON, making the API easy to work with across different programming languages and platforms.

API Capabilities

The API is organised into two main verticals.

Contact Management

The Contact Management endpoints allow you to manage the recipients of your communications and keep your contact data synchronised with your internal systems.

Using these endpoints, you can:

Create contacts
Update contact information
Retrieve contact details
Manage your contact database programmatically

This allows seamless integration with CRMs, internal databases, sign-up flows, and other operational tools.

Transaction Messaging

The Transaction Messaging endpoints enable you to automate communication with your users through structured templates.

Key features include:

Creating and managing message templates
Sending templated messages
Triggering notifications and alerts automatically
Integrating messaging into existing business processes

Templates ensure consistent messaging and allow dynamic data to be inserted when sending messages.

Sender ID Requirement

Before messages can be sent through the API, a Sender ID must be configured in your account.

The Sender ID is the identity that appears to recipients when they receive your message.

To configure your Sender ID:

Log in to your account
Navigate to Settings
Create or configure your Sender ID
Use that Sender ID when sending messages via the API

Requests made without a valid Sender ID may be rejected.

API Overview

Base URL

All API requests should be made to:

https://api.circlehq.co

Authentication

Authentication is handled using an API Key. Include your API key in the request headers.

"x-api-key": YOUR_API_KEY

Your API key can be generated from your account settings.

Request & Response Format

All API requests and responses use JSON.

Success Response

{
	"statusCode": 200,  
	"message": "Request successful",
	"data": {

  }
}

Error Response

{
	"statusCode": 400,  
	"message": "Request failed",
	"errors": [{
	// Your errors here
	}]
}

Rate Limiting

To maintain system stability, the API enforces rate limits. If the limit is exceeded, a 429 Too Many Requests response will be returned.

When a rate limit is hit, refer to the response headers to determine when requests can resume.