API Keys Documentation

Introduction

Texify v2 is a comprehensive SMS platform. Base URL: http://api.texify.org/api/v1. Use API keys for programmatic access; JWT is used for dashboard access.

API Key Authentication

Header	Type	Description	Mandatory
X-API-Key	String	Texify API key for programmatic access	Yes
Idempotency-Key	String	Prevents duplicate sends (24h TTL)	Optional
Content-Type	String	application/json	Yes

API Key Scopes

Scope	Description
send_sms	Send SMS messages
read_messages	View message history and details
read_delivery	Check delivery status of messages
manage_contacts	Create, update, and delete contacts
read_contacts	View contacts and groups
use_templates	Create and use message templates
read_balance	Check SMS credit balance
create_scheduled	Schedule messages for later
read_scheduled	View scheduled messages
read_analytics	Access analytics and reports

POST

/messages/send

Send SMS to one or more recipients. Recipients can be phone numbers, contact IDs, or group IDs. Provide either message or templateId. Supports idempotency to prevent duplicates. Sender ID must be alphanumeric and ≤11 characters.

Request sample

POST /messages/send
Headers:
  X-API-Key: txf_your_key
  Content-Type: application/json
  Idempotency-Key: unique_request_id (optional)

Body (raw message):
{
  "message": "Hello! This is a test message.",
  "recipients": ["+233244000000", "contact_id_1", "group_id_2"],
  "senderId": "MyCompany"
}

Body (using template):
{
  "templateId": "template_id",
  "variables": { "companyName": "Acme Corp" },
  "recipients": ["contact_id_1", "group_id_2", "+233244000003"],
  "senderId": "MyCompany"
}

Response sample

200 OK
{
  "status": "success",
  "message": "SMS sent successfully",
  "data": {
    "batches": 2,
    "totalRecipientCount": 5,
    "totalCreditsUsed": 5,
    "results": [
      {
        "messageId": "60d5ec49f1b2c8b5f8c5e8a1",
        "recipientCount": 3,
        "invalidPhones": [],
        "creditsUsed": 3,
        "segmentation": {
          "encoding": "GSM-7",
          "segments": 1,
          "charCount": 42
        }
      },
      {
        "messageId": "60d5ec49f1b2c8b5f8c5e8a2",
        "recipientCount": 2,
        "invalidPhones": [],
        "creditsUsed": 2,
        "segmentation": {
          "encoding": "GSM-7",
          "segments": 1,
          "charCount": 40
        }
      }
    ]
  }
}

GET

/messages/:messageId

Retrieve a single message and per-recipient delivery details.

Request sample

GET /messages/60d5ec49f1b2c8b5f8c5e8a1
Headers:
  X-API-Key: txf_your_key

Response sample

200 OK
{
  "status": "success",
  "data": {
    "_id": "60d5ec49f1b2c8b5f8c5e8a1",
    "message": "Hello! This is a test message.",
    "senderId": "MyCompany",
    "encoding": "GSM-7",
    "recipientCount": 2,
    "totalCreditsUsed": 2,
    "status": "sent",
    "recipients": [
      {
        "phoneNumber": "+233244000000",
        "status": "delivered",
        "deliveredAt": "2024-01-15T10:30:00Z",
        "creditsUsed": 1
      }
    ],
    "createdAt": "2024-01-15T10:25:00Z"
  }
}

GET

/messages

List messages with pagination, status, and date filters.

Request sample

GET /messages?page=1&limit=20&status=sent&dateFrom=2024-01-01
Headers:
  X-API-Key: txf_your_key

Response sample

200 OK
{
  "status": "success",
  "data": [
    {
      "_id": "60d5ec49f1b2c8b5f8c5e8a1",
      "message": "Hello!",
      "recipientCount": 2,
      "totalCreditsUsed": 2,
      "status": "sent",
      "createdAt": "2024-01-15T10:25:00Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 45, "pages": 3 }
}

GET

/balance

Returns credits, thresholds, auto top-up, and pricing tiers.

Request sample

GET /balance
Headers:
  X-API-Key: txf_your_key

Response sample

200 OK
{
  "status": "success",
  "data": {
    "credits": 5000,
    "lowBalanceThreshold": 100,
    "autoTopUp": { "enabled": false, "threshold": 50, "amount": 100 },
    "pricingTiers": [ { "id": "tier_1", "name": "Starter", "credits": 200, "price": 10 } ]
  }
}

POST

/contacts

Create a contact with tags, groups, and custom fields.

Request sample

POST /contacts
Headers:
  X-API-Key: txf_your_key
  Content-Type: application/json

Body:
{
  "phoneNumber": "+233244000000",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "tags": ["vip", "customer"],
  "groups": ["group_id_1", "group_id_2"],
  "customFields": { "birthday": "1990-01-15", "city": "Accra" }
}

Response sample

200 OK
{
  "status": "success",
  "message": "Contact created successfully",
  "data": {
    "_id": "contact_id",
    "phoneNumber": "+233244000000",
    "firstName": "John",
    "lastName": "Doe",
    "fullName": "John Doe",
    "email": "john@example.com",
    "tags": ["vip", "customer"],
    "status": "active",
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

GET

/contacts

List contacts with pagination, status, tags/groups, and search filters. Supports limit up to 1200 for bulk operations. When status=active, contacts with missing/empty status are treated as active.

Request sample

GET /contacts?page=1&limit=50&status=active&search=John
Headers:
  X-API-Key: txf_your_key

Response sample

200 OK
{
  "status": "success",
  "data": {
    "pagination": { "page": 1, "limit": 50, "total": 200, "pages": 4 },
    "contacts": [ { "_id": "contact_id", "fullName": "John Doe", "phoneNumber": "+233244000000" } ]
  }
}

POST

/groups

Create a contact group.

Request sample

POST /groups
Headers:
  X-API-Key: txf_your_key
  Content-Type: application/json

Body:
{ "name": "VIP Customers", "description": "Our premium customer segment" }

Response sample

200 OK
{ "status": "success", "message": "Group created" }

GET

/groups

List groups with pagination. Supports limit up to 1200 for bulk operations.

Request sample

GET /groups?page=1&limit=50
Headers:
  X-API-Key: txf_your_key

Response sample

200 OK
{ "status": "success", "data": { "pagination": { "page": 1, "limit": 50, "total": 10 }, "groups": [ { "_id": "group_id", "name": "VIP Customers" } ] } }

POST

/templates

Create a message template with variables.

Request sample

POST /templates
Headers:
  X-API-Key: txf_your_key
  Content-Type: application/json

Body:
{
  "name": "Welcome Message",
  "message": "Hello {{firstName}}, welcome to {{companyName}}!",
  "description": "Welcome message for new customers"
}

Response sample

200 OK
{
  "status": "success",
  "message": "Template created successfully",
  "data": {
    "_id": "template_id",
    "name": "Welcome Message",
    "message": "Hello {{firstName}}, welcome to {{companyName}}!",
    "variables": ["firstName", "companyName"],
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

GET

/templates

List templates with pagination.

Request sample

GET /templates?page=1&limit=50
Headers:
  X-API-Key: txf_your_key

Response sample

200 OK
{ "status": "success", "data": { "pagination": { "page": 1, "limit": 50, "total": 100 }, "templates": [ { "_id": "template_id", "name": "Welcome Message" } ] } }

GET

/templates/:id

Retrieve a single template.

Request sample

GET /templates/template_id
Headers:
  X-API-Key: txf_your_key

Response sample

200 OK
{ "status": "success", "data": { "_id": "template_id", "name": "Welcome Message" } }

POST

/templates/preview

Preview a template with provided variables.

Request sample

POST /templates/preview
Headers:
  X-API-Key: txf_your_key
  Content-Type: application/json

Body:
{
  "message": "Hello {{firstName}}, your balance is {{balance}}",
  "variables": { "firstName": "John", "balance": "100" }
}

Response sample

200 OK
{
  "status": "success",
  "data": {
    "originalMessage": "Hello {{firstName}}, your balance is {{balance}}",
    "renderedMessage": "Hello John, your balance is 100",
    "variables": ["firstName", "balance"],
    "providedVariables": ["firstName", "balance"],
    "missingVariables": [],
    "isComplete": true
  }
}

POST

/templates/:id/render

Render a stored template with dynamic variables.

Request sample

POST /templates/template_id/render
Headers:
  X-API-Key: txf_your_key
  Content-Type: application/json

Body:
{ "variables": { "firstName": "Jane", "companyName": "Acme Corp" } }

Response sample

200 OK
{
  "status": "success",
  "data": {
    "templateId": "template_id",
    "templateName": "Welcome Message",
    "originalMessage": "Hello {{firstName}}, welcome to {{companyName}}!",
    "renderedMessage": "Hello Jane, welcome to Acme Corp!",
    "variables": ["firstName", "companyName"],
    "providedVariables": { "firstName": "Jane", "companyName": "Acme Corp" }
  }
}

POST

/scheduled

Create a scheduled message (phones, contacts, or groups). Sender ID must be alphanumeric and ≤11 characters.

Request sample

POST /scheduled
Headers:
  X-API-Key: txf_your_key
  Content-Type: application/json

Body (phones):
{
  "message": "Your appointment is tomorrow at 10 AM",
  "senderId": "MyClinic",
  "scheduledFor": "2024-01-20T09:00:00Z",
  "recipientType": "phones",
  "phones": ["+233244000000", "+233244000001"]
}

Response sample

200 OK
{
  "status": "success",
  "message": "Scheduled message created successfully",
  "data": {
    "scheduledMessage": {
      "_id": "scheduled_id",
      "message": "Your appointment is tomorrow at 10 AM",
      "scheduledFor": "2024-01-20T09:00:00Z",
      "status": "pending",
      "estimatedRecipients": 2,
      "estimatedCredits": 2
    },
    "estimates": { "recipients": 2, "segments": 1, "credits": 2, "encoding": "GSM-7" },
    "invalidPhones": []
  }
}

GET

/scheduled

List scheduled messages with pagination and status filters.

Request sample

GET /scheduled?page=1&limit=20&status=pending
Headers:
  X-API-Key: txf_your_key

Response sample

200 OK
{
  "status": "success",
  "data": [ { "_id": "scheduled_id", "status": "pending" } ],
  "meta": { "page": 1, "limit": 20, "total": 10, "pages": 1 }
}

GET

/scheduled/:id

Retrieve a scheduled message by id.

Request sample

GET /scheduled/scheduled_id
Headers:
  X-API-Key: txf_your_key

Response sample

200 OK
{ "status": "success", "data": { "_id": "scheduled_id", "status": "pending" } }

PATCH

/scheduled/:id

Update message text, time, or sender. Sender ID must be alphanumeric and ≤11 characters.

Request sample

PATCH /scheduled/scheduled_id
Headers:
  X-API-Key: txf_your_key
  Content-Type: application/json

Body:
{ "message": "Updated message text", "scheduledFor": "2024-01-21T09:00:00Z", "senderId": "NewSender" }

Response sample

200 OK
{ "status": "success", "message": "Scheduled message updated" }

POST

/scheduled/:id/cancel

Cancel a pending scheduled message.

Request sample

POST /scheduled/scheduled_id/cancel
Headers:
  X-API-Key: txf_your_key

Response sample

200 OK
{ "status": "success", "message": "Scheduled message cancelled" }