SigNet API Documentation

SigNet API Reference

Complete reference for integrating with the SigNet messaging platform

Overview

The SigNet API provides a comprehensive platform for SMS messaging and phone number management. This RESTful API allows you to send messages, manage phone numbers, and handle billing operations programmatically.

Base URL

https://api.signet.callocean.com

Quick Start

1. Get your credentials

Visit the API Keys page to get your authentication credentials.

2. Authenticate

curl -X POST https://api.signet.callocean.com/login \
  -H "Content-Type: application/json" \
  -d '{"email": "your-email", "password": "your-password"}'

3. Use the JWT token

curl -X GET https://api.signet.callocean.com/billing/balance \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Authentication

SigNet API uses JWT (JSON Web Tokens) for authentication. All API requests must include a valid JWT token in the Authorization header.

Login

POST /login
Content-Type: application/json

{
  "email": "your-email@example.com",
  "password": "your-password"
}

Using the Token

Authorization: Bearer YOUR_JWT_TOKEN

Health Check

Check the operational status of the SigNet API.

API Health Status

GET /health
Content-Type: application/json

Response:
{
  "status": "OK"
}

Account Management

Create and manage user accounts on the SigNet platform.

Create Account

POST /accounts
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "YourStrongP@ssword1!",
  "name": "User Name"
}

Response:
{
  "accountId": "550e8400-e29b-41d4-a716-446655440000"
}

Password Requirements: Minimum 8 characters, 1 uppercase, 1 lowercase, 1 number, 1 symbol.

Messages

Send and manage SMS messages through the SigNet platform.

Send Message

POST /messages
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "from": "+1234567890",
  "to": "+0987654321",
  "body": "Hello from SigNet!"
}

Send Bulk Messages

Send multiple SMS messages in a single request. Supports up to 10,000 messages with synchronous balance validation and asynchronous processing.

Broadcast to Multiple Recipients

POST /messages/bulk
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "recipients": ["+15551234567", "+15559876543", "+15555555555"],
  "from": "+15557654321",
  "body": "Broadcast message to all recipients"
}

Response (202 Accepted):
{
  "message": "Bulk SMS request accepted for processing",
  "messageCount": 3,
  "estimatedCost": 9,
  "status": "processing"
}

Individual Messages Array

POST /messages/bulk
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "messages": [
    {
      "to": "+15551234567",
      "from": "+15557654321",
      "body": "Hello John!"
    },
    {
      "to": "+15559876543",
      "from": "+15557654321",
      "body": "Hello Jane!"
    }
  ]
}

Validation:
• Maximum 10,000 messages per request
• Synchronous balance validation before processing
• All "from" numbers must be owned by your account
• Messages processed asynchronously through existing SMS pipeline
• Track individual delivery status through message endpoints

Insufficient Funds Response (400):
{ "message": "Insufficient funds", "required": 5000, "available": 3000, "shortfall": 2000, "estimatedMessages": 1000 }

Phone Numbers

Search, purchase, and manage phone numbers for your messaging needs.

Search Available Numbers

GET /phonenumbers/search?state=CA&areaCode=555&limit=10&tier=BASIC
Authorization: Bearer YOUR_JWT_TOKEN

List Owned Numbers

GET /phonenumbers
Authorization: Bearer YOUR_JWT_TOKEN

Response:
{
  "phoneNumbers": [
    {
      "phoneNumber": "+15551234567",
      "status": "active",
      "tier": "BASIC"
    }
  ],
  "hasMore": false
}

Get Number Details

GET /phonenumbers/%2B15551234567
Authorization: Bearer YOUR_JWT_TOKEN

Response:
{
  "phoneNumber": "+15551234567",
  "accountId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "active",
  "tier": "BASIC",
  "forwardingWebhookUrl": "https://your.webhook/handler"
}

Purchase Number

POST /phonenumbers/purchase
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "phoneNumber": "+15551234567",
  "tier": "BASIC"
}

Delete/Release Number

POST /phonenumbers/delete
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "phoneNumber": "+15551234567"
}

Response:
{
  "message": "Phone number +15551234567 has been successfully deleted."
}

Update Forwarding Settings

PUT /phonenumbers/%2B15551234567/forwarding
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "webhookUrl": "https://your.webhook/handler"
}

Billing

Manage billing, payments, and usage tracking.

Add Payment Method

Adds a payment method (credit card) to the user's payment profile with comprehensive validation and verification. Sets billingStatus to 'active' on success.

POST /billing/add-card
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "cardNumber": "4242424242424242",
  "expMonth": 12,
  "expYear": 2030,
  "cvc": "123",
  "cardholderName": "John Doe",
  "email": "john@example.com",
  "phone": "5551234567",
  "billingAddress": {
    "line1": "123 Main St",
    "line2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "US"
  }
}

Response:
{
  "message": "Payment method added successfully."
}

Validation Rules:
• cardNumber: 13-19 digits
• expMonth: 1-12
• expYear: Current year or future
• cvc: 3-4 digits
• phone: Exactly 10 digits (gets +1 prefix)
• postal_code: Exactly 5 digits
• state: 2-character state code
• All fields are required

Card Verification: Performs CVC check, address verification (AVS), and ZIP code validation before saving. Ensure PCI DSS compliance when handling raw card details.

Update Payment Method

Updates the user's payment method with a new credit card. Performs the same comprehensive validation and verification as add-card. Automatically replaces the current default payment method.

PUT /billing/update-card
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "cardNumber": "4000056655665556",
  "expMonth": 8,
  "expYear": 2028,
  "cvc": "456",
  "cardholderName": "Jane Smith",
  "email": "jane@example.com",
  "phone": "5559876543",
  "billingAddress": {
    "line1": "456 Oak Ave",
    "line2": "Suite 200",
    "city": "Los Angeles",
    "state": "CA",
    "postal_code": "90210",
    "country": "US"
  }
}

Response:
{
  "message": "Card updated successfully."
}

Process:
1. Validates new card details
2. Creates and verifies new payment method
3. Sets as new default payment method
4. Removes old payment method from Stripe
5. Updates account records

Setup Payment Intent

POST /billing/setup-intent
Authorization: Bearer YOUR_JWT_TOKEN

Response:
{
  "clientSecret": "seti_1234567890abcdef_secret_xyz"
}

Attach Payment Method

POST /billing/attach-payment-method
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "paymentMethodId": "pm_1234567890abcdef"
}

List Payment Methods

GET /billing/payment-methods
Authorization: Bearer YOUR_JWT_TOKEN

Response:
{
  "paymentMethods": [
    {
      "id": "pm_1234567890abcdef",
      "brand": "visa",
      "last4": "4242",
      "expMonth": 12,
      "expYear": 2030,
      "isDefault": true
    }
  ]
}

Delete Payment Method

DELETE /billing/payment-methods
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "paymentMethodId": "pm_1234567890abcdef"
}

Note: You cannot delete the default payment method. Set another card as default first.

Top Up Account

POST /billing/top-up
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "amount": 1000
}

Response:
{
  "message": "Successfully added $10.00 to your account",
  "newBalance": 2500
}

Amount: Specified in cents (e.g., 1000 = $10.00)

Get Usage History

GET /billing/usage?limit=10&type=message
Authorization: Bearer YOUR_JWT_TOKEN

Response:
{
  "transactions": [
    {
      "id": "txn_1234567890",
      "type": "message",
      "amount": -2,
      "description": "SMS to +15551234567",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ],
  "hasMore": false
}

Auto-Replenishment Settings

Configure automatic top-ups when your balance falls below a threshold.

Get Auto-Replenishment Settings

GET /billing/auto-replenish
Authorization: Bearer YOUR_JWT_TOKEN

Response:
{
  "enabled": true,
  "amount": 2000,
  "threshold": 500
}

Update Auto-Replenishment Settings

PUT /billing/auto-replenish
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "enabled": true,
  "amount": 2000,
  "threshold": 500
}

Response:
{
  "message": "Auto-replenish settings updated",
  "enabled": true,
  "amount": 2000,
  "threshold": 500
}

Parameters:
• enabled: Boolean to enable/disable auto-replenishment
• amount: Top-up amount in cents ($5.00-$100.00 = 500-10000)
• threshold: Balance threshold in cents ($0.00-$20.00 = 0-2000)
Note: Requires a default payment method to be configured.

Webhooks

Configure webhooks to receive real-time notifications about messages and events.

Configure Webhook

POST /numbers/+15551234567/forwarding
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

{
  "webhookUrl": "https://your-app.com/webhook",
  "webhookSecret": "your-secret-key"
}