Developer

Manage API keys and integrate EchoCue into your applications

Your API Keys

Create and manage API keys for programmatic access

Name	API Key	Status	Created	Actions
Loading API keys...

Base URL

All API requests should be made to the following base URL:

https://api.echocue.com:5501/v1

Authentication

All API requests must include your API key and API secret in the request headers. You can create and manage your API credentials from the tab.

Required Headers

Authorization: Bearer <API_KEY>
X-API-SECRET: <API_SECRET>
Content-Type: application/json

Keep your API credentials secure

Never expose your API key or secret in client-side code or public repositories. Use environment variables or secure key management systems.

GET /api/device/list

List all devices with pagination

Query Parameters

Parameter	Type	Required	Description
`page`	integer	Optional	Page number (default: 1)
`limit`	integer	Optional	Items per page (default: 20, max: 100)
`status`	string	Optional	Filter by status: active, inactive

Example Request

curl -X GET \
  'https://api.echocue.com:5501/v1/api/device/list?page=1&limit=20' \
  -H 'Authorization: Bearer your_api_key_here' \
  -H 'X-API-SECRET: your_api_secret_here'

Success Response

{
  "status_id": 200,
  "message": "Success",
  "data": {
    "devices": [...],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45
    }
  }
}

GET /api/device/export

Export devices as CSV or JSON

Query Parameters

Parameter	Type	Required	Description
`format`	string	Optional	Export format: csv, json (default: json)
`include_inactive`	boolean	Optional	Include inactive devices (default: false)

Example Request

curl -X GET \
  'https://api.echocue.com:5501/v1/api/device/export?format=csv' \
  -H 'Authorization: Bearer your_api_key_here' \
  -H 'X-API-SECRET: your_api_secret_here'

GET /api/device/:device_id

Get single device details

Path Parameters

Parameter	Type	Required	Description
`device_id`	integer	Required	The unique device identifier

Example Request

curl -X GET \
  'https://api.echocue.com:5501/v1/api/device/123' \
  -H 'Authorization: Bearer your_api_key_here' \
  -H 'X-API-SECRET: your_api_secret_here'

Success Response

{
  "status_id": 200,
  "data": {
    "device_id": 123,
    "name": "My Device",
    "status": "active"
  }
}

GET /api/device/:device_id/health

Get device health status

Example Request

curl -X GET \
  'https://api.echocue.com:5501/v1/api/device/123/health' \
  -H 'Authorization: Bearer your_api_key_here' \
  -H 'X-API-SECRET: your_api_secret_here'

Success Response

{
  "status_id": 200,
  "data": {
    "health_score": 95,
    "last_sync": "2024-01-15T10:30:00Z"
  }
}

GET /api/device/:device_id/stats

Get device performance statistics

Success Response

{
  "status_id": 200,
  "data": {
    "sent": 1250,
    "failed": 15,
    "pending": 5
  }
}

GET /api/device/:device_id/usage

Get device usage against plan limits

Success Response

{
  "status_id": 200,
  "data": {
    "used": 500,
    "limit": 1000,
    "remaining": 500
  }
}

GET /api/device/:device_id/rate-limit

Get current rate limit status

Success Response

{
  "status_id": 200,
  "data": {
    "requests_remaining": 55,
    "reset_at": "2024-01-15T10:31:00Z"
  }
}

POST /api/device/batch/register

Batch register devices (max 10)

Request Body

Parameter	Type	Required	Description
`devices`	array	Required	Array of device objects to register (max 10)

POST /api/device/batch/delete

Batch delete devices (max 50)

Request Body

Parameter	Type	Required	Description
`device_ids`	array	Required	Array of device IDs to delete (max 50)

POST /api/device/batch/update-status

Batch activate/deactivate devices

Request Body

Parameter	Type	Required	Description
`device_ids`	array	Required	Array of device IDs
`status`	string	Required	New status: active, inactive

GET /api/project/list

List all workspaces

Example Request

curl -X GET \
  'https://api.echocue.com:5501/v1/api/project/list' \
  -H 'Authorization: Bearer your_api_key_here' \
  -H 'X-API-SECRET: your_api_secret_here'

Success Response

{
  "status_id": 200,
  "data": {
    "projects": [
      {
        "project_id": 1,
        "name": "My Workspace",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

GET /api/contact/list

List contacts with pagination

Query Parameters

Parameter	Type	Required	Description
`page`	integer	Optional	Page number (default: 1)
`limit`	integer	Optional	Items per page (default: 20, max: 100)

Example Request

curl -X GET \
  'https://api.echocue.com:5501/v1/api/contact/list?page=1&limit=20' \
  -H 'Authorization: Bearer your_api_key_here' \
  -H 'X-API-SECRET: your_api_secret_here'

GET /api/contact/:contact_id

Get single contact with details

Example Request

curl -X GET \
  'https://api.echocue.com:5501/v1/api/contact/456' \
  -H 'Authorization: Bearer your_api_key_here' \
  -H 'X-API-SECRET: your_api_secret_here'

GET /api/contact/types

Get all contact types

Example Request

curl -X GET \
  'https://api.echocue.com:5501/v1/api/contact/types' \
  -H 'Authorization: Bearer your_api_key_here' \
  -H 'X-API-SECRET: your_api_secret_here'

POST /api/contact/search

Search contacts by name/details

Request Body

Parameter	Type	Required	Description
`query`	string	Required	Search query string

POST /api/contact/create

Create new contact

Request Body

Parameter	Type	Required	Description
`name`	string	Required	Contact name
`phone`	string	Required	Phone number in E.164 format
`email`	string	Optional	Email address

POST /api/contact/update

Update existing contact

Request Body

Parameter	Type	Required	Description
`contact_id`	integer	Required	Contact ID to update

POST /api/contact/delete

Delete contact

Request Body

Parameter	Type	Required	Description
`contact_id`	integer	Required	Contact ID to delete

GET /api/template/list

List templates with pagination

Query Parameters

Parameter	Type	Required	Description
`channel`	string	Optional	Filter by channel: sms, whatsapp
`page`	integer	Optional	Page number (default: 1)
`limit`	integer	Optional	Items per page (default: 20)

Example Request

curl -X GET \
  'https://api.echocue.com:5501/v1/api/template/list?channel=sms' \
  -H 'Authorization: Bearer your_api_key_here' \
  -H 'X-API-SECRET: your_api_secret_here'

GET /api/template/:template_id

Get single template

Example Request

curl -X GET \
  'https://api.echocue.com:5501/v1/api/template/74' \
  -H 'Authorization: Bearer your_api_key_here' \
  -H 'X-API-SECRET: your_api_secret_here'

GET /api/notification/list

List notifications with filtering

Query Parameters

Parameter	Type	Required	Description
`status`	string	Optional	Filter by status: pending, sent, delivered, failed
`delivery_type`	string	Optional	Filter by type: sms, whatsapp

GET /api/notification/:notification_id

Get notification details

Example Request

curl -X GET \
  'https://api.echocue.com:5501/v1/api/notification/12345' \
  -H 'Authorization: Bearer your_api_key_here' \
  -H 'X-API-SECRET: your_api_secret_here'

POST /api/notification/cancel

Cancel pending notification

Request Body

Parameter	Type	Required	Description
`notification_id`	integer	Required	ID of the notification to cancel

GET /api/thread/list

List message threads

Example Request

curl -X GET \
  'https://api.echocue.com:5501/v1/api/thread/list' \
  -H 'Authorization: Bearer your_api_key_here' \
  -H 'X-API-SECRET: your_api_secret_here'

GET /api/thread/:thread_id/messages

Get messages for a thread

Example Request

curl -X GET \
  'https://api.echocue.com:5501/v1/api/thread/789/messages' \
  -H 'Authorization: Bearer your_api_key_here' \
  -H 'X-API-SECRET: your_api_secret_here'

POST /api/sms/send

Send SMS message (supports templates with variables)

Request Body

Parameter	Type	Required	Description
`recipient_contact`	string	Required	Phone number in E.164 format
`message`	string	Required*	Message content (required if template_id not set)
`template_id`	string	Optional	Template ID to use
`variables`	object	Optional	Template variables

Example Request

curl -X POST \
  'https://api.echocue.com:5501/v1/api/sms/send' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your_api_key_here' \
  -H 'X-API-SECRET: your_api_secret_here' \
  -d '{
    "recipient_contact": "+14155551234",
    "message": "Hello from EchoCue!"
  }'

POST /api/sms/send/bulk

Send bulk SMS (max 100 messages)

Request Body

Parameter	Type	Required	Description
`messages`	array	Required	Array of message objects (max 100)

POST /api/whatsapp/send

Send WhatsApp message

Request Body

Parameter	Type	Required	Description
`recipient_contact`	string	Required	WhatsApp phone number
`message`	string	Required	Message content

Example Request

curl -X POST \
  'https://api.echocue.com:5501/v1/api/whatsapp/send' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your_api_key_here' \
  -H 'X-API-SECRET: your_api_secret_here' \
  -d '{
    "recipient_contact": "+14155551234",
    "message": "Hello via WhatsApp!"
  }'

Response

Success Response (200 OK)

{
  "status_id": 200,
  "message": "Successfully scheduled sms notification",
  "data": {
    "notification_id": 12345,
    "template_id": null,
    "template_vars": null,
    "message": "Hello from EchoCue! This is a test message."
  }
}

Error Response

{
  "status_id": 400,
  "message": "Invalid phone number format",
  "data": null
}

Error Codes

Status Code	Description
`200`	Success - Message queued for delivery
`400`	Bad Request - Invalid parameters (check phone number format, message content)
`401`	Unauthorized - Invalid or missing API key or secret
`402`	Payment Required - Insufficient credits
`403`	Forbidden - API key is disabled or account is suspended
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Try again later

POST /notification/template/api/get

Retrieve message templates with variables for dynamic content

About Templates

Templates allow you to create reusable message formats with dynamic variables. Variables are defined using double curly braces like {{variable_name}}. When sending a message using a template, you provide values for these variables through the variables parameter in the Send SMS endpoint.

Request Headers

Header	Required	Description
`Authorization`	Required	Bearer token with your API key: `Bearer <API_KEY>`
`X-API-SECRET`	Required	Your EchoCue API secret
`Content-Type`	Required	Must be `application/json`

Request Body

Parameter	Type	Required	Description
`page`	integer	Optional	Page number for pagination (default: 1)
`limit`	integer	Optional	Number of templates per page (default: 10, max: 100)

Code Examples

curl -X POST \
  'https://api.echocue.com:5501/v1/notification/template/api/get' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your_api_key_here' \
  -H 'X-API-SECRET: your_api_secret_here' \
  -d '{
    "page": 1,
    "limit": 10
  }'

Response

Success Response (200 OK)

{
  "status_id": 200,
  "message": "Successfully fetched template(s)",
  "data": [
    {
      "template_id": 74,
      "template_guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "user_id": 12,
      "code": "WELCOME_MSG",
      "name": "Welcome Message",
      "description": "Welcome new customers",
      "body": "Hi {{first_name}}, welcome to our service!",
      "channel": "sms",
      "is_system": 0,
      "status": "active",
      "created_at": "2024-01-15 10:30:00",
      "updated_at": "2024-01-15 10:30:00"
    }
  ]
}

GET /api/stats/notifications

Get notification statistics

Query Parameters

Parameter	Type	Required	Description
`period`	string	Optional	Time period: day, week, month

Example Request

curl -X GET \
  'https://api.echocue.com:5501/v1/api/stats/notifications?period=week' \
  -H 'Authorization: Bearer your_api_key_here' \
  -H 'X-API-SECRET: your_api_secret_here'

Success Response

{
  "status_id": 200,
  "data": {
    "sent": 1250,
    "delivered": 1200,
    "failed": 50,
    "pending": 25
  }
}

GET /api/stats/credits

Get credit balance

Example Request

curl -X GET \
  'https://api.echocue.com:5501/v1/api/stats/credits' \
  -H 'Authorization: Bearer your_api_key_here' \
  -H 'X-API-SECRET: your_api_secret_here'

Success Response

{
  "status_id": 200,
  "data": {
    "balance": 5000,
    "used_this_month": 1250
  }
}

Rate Limits

API requests are subject to rate limiting to ensure fair usage and system stability.

Requests per minute

Requests per day

10,000

If you need higher limits, please contact support.

Need Help?

If you have questions about the API or need assistance with your integration, we're here to help.

Contact Support

Developer

Your API Keys

Base URL

Authentication

Required Headers

Query Parameters

Example Request

Success Response

Query Parameters

Example Request

Path Parameters

Example Request

Success Response

Example Request

Success Response

Success Response

Success Response

Success Response

Request Body

Request Body

Request Body

Example Request

Success Response

Query Parameters

Example Request

Example Request

Example Request

Request Body

Request Body

Request Body

Request Body

Query Parameters

Example Request

Example Request

Query Parameters

Example Request

Request Body

Example Request

Example Request

Request Body

Example Request

Request Body

Request Body

Example Request

Response

Success Response (200 OK)

Error Response

Error Codes

Request Headers

Request Body

Code Examples

Response

Success Response (200 OK)

Query Parameters

Example Request

Success Response

Example Request

Success Response

Rate Limits

Need Help?

Create New API Key

API Key Created!

Delete API Key?

Edit API Key