Pairfon API

Send and receive SMS programmatically through your Pairfon-connected devices.

Base URL

https://api.pairfon.com

Authentication

All API requests require authentication via an API key sent as a Bearer token.

API Key Authentication

Get your API key from your Pairfon dashboard under API & Webhooks. Include it in the Authorization header of every request. 

Authorization: Bearer YOUR_API_KEY

SMS

Send and retrieve SMS messages through your connected devices.

POST /chat/send Send an SMS message ▼

Queue an SMS message to be sent through one of your connected devices.

Request Body

ParameterTypeDescription
device_fingerprintrequiredstringThe unique identifier of the device to send from
phonerequiredstringRecipient phone number (e.g., +1234567890)
messagerequiredstringThe SMS message text
sim_slotrequiredstringSIM slot to send from: SIM1 or SIM2

Example Request

curl -X POST https://api.pairfon.com/chat/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "device_fingerprint": "abc123",
    "phone": "+1234567890",
    "message": "Hello from Pairfon!",
    "sim_slot": "SIM1"
  }'

Response

{
  "message": "SMS queued.",
  "queueId": "msg_abc123"
}
GET /chat/messages Get message history ▼

Retrieve paginated message history between a device and a phone number.

Query Parameters

ParameterTypeDescription
device_fingerprintrequiredstringDevice identifier
phonerequiredstringContact phone number
pageoptionalintegerPage number (default: 1)
limitoptionalintegerMessages per page (default: 50, max: 100)

Example Request

curl "https://api.pairfon.com/chat/messages?device_fingerprint=abc123&phone=%2B1234567890" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "messages": [
    {
      "id": 1,
      "direction": "outbound",
      "message": "Hello from Pairfon!",
      "phone": "+1234567890",
      "sim_slot": "SIM1",
      "status": "delivered",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "pages": 1
}
GET /chat/conversations List conversations ▼

Get a list of unique conversations (phone numbers) for a device, with the latest message in each.

Query Parameters

ParameterTypeDescription
device_fingerprintrequiredstringDevice identifier

Example Request

curl "https://api.pairfon.com/chat/conversations?device_fingerprint=abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "conversations": [
    {
      "phone": "+1234567890",
      "lastMessage": "Hello!",
      "lastMessageAt": "2025-01-15T10:30:00Z",
      "direction": "inbound",
      "messageCount": 15
    }
  ]
}
GET /zapier/inbound-sms Get inbound SMS (polling) ▼

Retrieve the latest inbound SMS messages. Designed for polling-based integrations (Zapier, Make, Pabbly).

Query Parameters

ParameterTypeDescription
device_fingerprintoptionalstringFilter by specific device
sim_slotoptionalstringFilter by SIM slot (SIM1 or SIM2)

Example Request

curl "https://api.pairfon.com/zapier/inbound-sms?device_fingerprint=abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

[
  {
    "id": 101,
    "phone": "+1987654321",
    "message": "Hey, got your text!",
    "sim_slot": "SIM1",
    "device_fingerprint": "abc123",
    "received_at": "2025-01-15T10:35:00Z"
  }
]
GET /zapier/latest-sms Get latest inbound SMS ▼

Retrieve the most recent inbound SMS message. Returns a single object instead of an array.

Query Parameters

ParameterTypeDescription
device_fingerprintoptionalstringFilter by specific device
sim_slotoptionalstringFilter by SIM slot (SIM1 or SIM2)

Example Request

curl "https://api.pairfon.com/zapier/latest-sms?device_fingerprint=abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "33fec033-1019-43f6-92bb-ed9d5f72f74a",
  "phone": "+1987654321",
  "message": "Hey, got your text!",
  "sim_slot": "SIM1",
  "device_fingerprint": "abc123",
  "received_at": "2025-01-15T10:35:00Z"
}
POST /zapier/send-sms Send SMS (integrations) ▼

Send an SMS through a Pairfon device. Designed for automation platforms (Zapier, Make, Pabbly).

Request Body

ParameterTypeDescription
device_fingerprintrequiredstringDevice to send from
phonerequiredstringRecipient phone number
messagerequiredstringSMS message text
sim_slotoptionalstringSIM1 or SIM2 (defaults to SIM1)

Example Request

curl -X POST https://api.pairfon.com/zapier/send-sms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "device_fingerprint": "abc123",
    "phone": "+1234567890",
    "message": "Automated message via Pairfon",
    "sim_slot": "SIM1"
  }'

Response

{
  "id": 42,
  "message": "SMS queued successfully.",
  "phone": "+1234567890",
  "device_fingerprint": "abc123",
  "sim_slot": "SIM1"
}

Devices

Manage and retrieve information about your connected devices.

GET /chat/devices List devices ▼

Retrieve all devices linked to your account.

Example Request

curl "https://api.pairfon.com/chat/devices" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "devices": [
    {
      "device_fingerprint": "abc123",
      "device_name": "Samsung Galaxy S24",
      "status": "active",
      "selected_sim": "BOTH"
    }
  ]
}
GET /device/list List devices (detailed) ▼

Retrieve a detailed list of devices with admin-level information.

Example Request

curl "https://api.pairfon.com/device/list" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "devices": [
    {
      "device_fingerprint": "abc123",
      "device_name": "Samsung Galaxy S24",
      "status": "active",
      "selected_sim": "BOTH",
      "user_id": 5,
      "fcm_token": "fcm_token_value"
    }
  ]
}
DELETE /device/delete/:device_fingerprint Delete a device ▼

Remove a device from your account.

URL Parameters

ParameterTypeDescription
device_fingerprintrequiredstringThe device identifier to delete

Example Request

curl -X DELETE "https://api.pairfon.com/device/delete/abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "message": "Device deleted successfully."
}

Webhooks

Configure webhook URLs to receive real-time notifications when SMS messages arrive.

GET /webhooks/inbound-sms Get webhook configuration ▼

Retrieve your current inbound SMS webhook configuration.

Example Request

curl "https://api.pairfon.com/webhooks/inbound-sms" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "webhooks": [
    {
      "id": 1,
      "url": "https://example.com/webhook",
      "active": true
    }
  ]
}
PUT /webhooks/inbound-sms Configure webhooks ▼

Set up or update your inbound SMS webhook URLs.

Request Body

ParameterTypeDescription
webhooksrequiredarrayArray of webhook objects with url and active fields

Example Request

curl -X PUT https://api.pairfon.com/webhooks/inbound-sms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhooks": [
      {
        "url": "https://example.com/webhook",
        "active": true
      }
    ]
  }'

Response

{
  "message": "Webhook settings saved",
  "webhooks": [
    {
      "id": 1,
      "url": "https://example.com/webhook",
      "active": true
    }
  ]
}

Errors

The API uses standard HTTP status codes to indicate success or failure.

StatusMeaning
200Success
400Bad request - missing or invalid parameters
401Unauthorized - invalid or missing API key
403Forbidden - insufficient permissions (e.g., wrong SIM slot)
404Not found - resource does not exist
429Rate limited - too many requests (100/min general, 15/15min auth)
500Server error

Rate Limits

ScopeLimitWindow
General API100 requests1 minute
Authentication15 requests15 minutes
Rate limit headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset) are included in every response.