SMS Reminder API Documentation

Quick Start

Get started with the Remindlo API in 3 steps:

1. Get your API key from Dashboard → Settings → API Keys

2. List your campaigns to get campaign IDs

3. Add contacts and enroll them in campaigns

# Example: Add a contact
curl -X POST "https://api.remindlo.co.uk/v1/contacts" \
  -H "x-api-key: sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+447912345678",
    "first_name": "John",
    "marketing_consent": true
  }'

Authentication

All API requests require an API key passed in the x-api-key header:

x-api-key: sk_live_your_key_here

Important: Keep your API key secure. Never expose it in client-side code or public repositories.

Base URL

https://api.remindlo.co.uk/v1

Endpoints

GET /v1/campaigns

List all available SMS campaigns for your account.

curl -X GET "https://api.remindlo.co.uk/v1/campaigns" \
  -H "x-api-key: sk_live_xxx"

Response:

{
  "campaigns": [
    {
      "id": "uuid",
      "name": "Appointment Reminder",
      "type": "recurring",
      "status": "running"
    }
  ]
}

POST /v1/contacts

Create or update a contact. If a contact with the same phone or email exists, it will be updated.

Request Body

* At least one of phone or email is required.

curl -X POST "https://api.remindlo.co.uk/v1/contacts" \
  -H "x-api-key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+447912345678",
    "first_name": "John",
    "last_name": "Smith",
    "marketing_consent": true,
    "next_due_at": "2025-03-15",
    "campaign_ids": ["campaign-uuid"],
    "is_recurrent": true,
    "recurrent_interval_value": 12,
    "recurrent_interval_unit": "months"
  }'

Response:

{
  "success": true,
  "contact_id": "uuid",
  "action": "created",
  "contact": {
    "id": "uuid",
    "first_name": "John",
    "last_name": "Smith",
    "phone": "+447912345678",
    "marketing_consent": true,
    "next_due_at": "2025-03-15",
    "is_recurrent": true,
    "recurrent_interval_value": 12,
    "recurrent_interval_unit": "months"
  },
  "enrollments": [
    { "campaign_id": "campaign-uuid", "status": "enrolled" }
  ]
}

POST /v1/campaigns-enroll

Enroll an existing contact in a campaign. For one-off campaigns that are running, the message is queued immediately. For recurring campaigns, the scheduler handles sending.

Request Body

* Provide either contact_id (recommended) or customer_id. If both are provided, contact_id takes precedence.

curl -X POST "https://api.remindlo.co.uk/v1/campaigns-enroll" \
  -H "x-api-key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign-uuid",
    "contact_id": "contact-uuid"
  }'

Response:

{
  "enrollment_id": "uuid",
  "status": "enrolled"
}

Possible status values:

• enrolled — contact successfully enrolled

• already_enrolled — contact was already in this campaign

• skipped — enrollment skipped (e.g., contact has no phone, or campaign is not active)

POST /v1/messages

Send a one-time SMS to an existing contact. Requires a paid plan. The message is queued immediately and sent via the configured SMS provider.

Request Body

curl -X POST "https://api.remindlo.co.uk/v1/messages" \
  -H "x-api-key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "contact-uuid",
    "body": "Hi John, just a quick reminder about your appointment tomorrow at 2pm."
  }'

Response (202 Accepted):

{
  "success": true,
  "message_id": "uuid",
  "status": "queued",
  "contact_id": "contact-uuid",
  "parts": 1,
  "channel": "sms"
}

Error responses:

• 403 PLAN_REQUIRED — sending one-time messages requires a paid plan

• 404 CONTACT_NOT_FOUND — contact does not exist or has no phone number

• 429 SMS_LIMIT_EXCEEDED — SMS quota has been exceeded

GET /v1/contacts

List contacts with filtering and pagination.

Query Parameters

curl -X GET "https://api.remindlo.co.uk/v1/contacts?limit=10&search=john" \
  -H "x-api-key: sk_live_xxx"

GET /v1/contacts/:id

Get a single contact by ID, phone, or email.

# By ID
curl -X GET "https://api.remindlo.co.uk/v1/contacts/uuid" \
  -H "x-api-key: sk_live_xxx"

# By phone
curl -X GET "https://api.remindlo.co.uk/v1/contacts?phone=+447912345678" \
  -H "x-api-key: sk_live_xxx"

Error Handling

All errors return a consistent JSON format:

{
  "success": false,
  "error": {
    "code": "INVALID_PHONE_FORMAT",
    "message": "Phone number must be in E.164 format",
    "details": {
      "field": "phone",
      "value": "07912345678",
      "suggestion": "Use format +447912345678 for UK numbers"
    }
  }
}

Error Codes

Use Cases

AI Assistant Integration

Perfect for AI assistants (Claude, ChatGPT) to manage contacts via chat:

User: "Add John Smith, phone 07912345678, to the birthday campaign"
AI: [calls GET /v1/campaigns to find "Birthday" campaign]
AI: [calls POST /v1/contacts with campaign_ids]
AI: "Done! John Smith has been added and enrolled in the Birthday campaign."

CRM Integration

Sync contacts from your CRM system automatically when appointments are booked.

Zapier/Make Automation

Connect Remindlo to 5000+ apps using webhook integrations.

Code Examples

JavaScript / Node.js

const response = await fetch('https://api.remindlo.co.uk/v1/contacts', {
  method: 'POST',
  headers: {
    'x-api-key': 'sk_live_xxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phone: '+447912345678',
    first_name: 'John',
    marketing_consent: true
  })
});
const data = await response.json();
console.log(data.contact_id);

Python

import requests

response = requests.post(
    'https://api.remindlo.co.uk/v1/contacts',
    headers={'x-api-key': 'sk_live_xxx'},
    json={
        'phone': '+447912345678',
        'first_name': 'John',
        'marketing_consent': True
    }
)
print(response.json()['contact_id'])

PHP

$ch = curl_init('https://api.remindlo.co.uk/v1/contacts');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'x-api-key: sk_live_xxx',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'phone' => '+447912345678',
        'first_name' => 'John',
        'marketing_consent' => true
    ])
]);
$response = json_decode(curl_exec($ch), true);
echo $response['contact_id'];

Need Help?

Contact us at [email protected] for API support.