API Documentation

1. Introduction

The 2fact.io API allows your application to receive SMS-based Two-Factor Authentication (2FA) codes securely using your dedicated number(s). Each organization receives its own API key and webhook URL.

2. Authentication

Each API request must include your API Key in the header:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Your API Key is found in your Dashboard → API Keys.

3. Base URL

https://api.2fact.io/v1/

4. Endpoint: List Purchased Numbers

GET /numbers
Authorization: Bearer YOUR_API_KEY

Example Response:

{
  "numbers": [
    {
      "phone": "+15105550123",
      "assigned_to": "production",
      "status": "active",
      "last_message": "Your Amazon OTP is 448921"
    }
  ]
}

5. Endpoint: Fetch Recent Messages

GET /messages?limit=50
Authorization: Bearer YOUR_API_KEY

Example Response:

{
  "messages": [
    {
      "id": "msg_001",
      "timestamp": "2025-01-01T14:22:00Z",
      "from": "Amazon",
      "to": "+15105550123",
      "message": "Your OTP is 338192"
    }
  ]
}

6. Incoming Webhooks

When your number receives an SMS, 2fact.io will POST the event to your webhook URL.

POST /your-webhook-endpoint
{
  "number": "+15105550123",
  "sender": "Amazon",
  "message": "Your OTP code is 004211",
  "received_at": "2025-02-01T10:00:00Z"
}

7. PHP Example – Verifying Requests

8. Curl Example – Get Numbers

curl --location "https://api.2fact.io/v1/numbers" \
  --header "Authorization: Bearer YOUR_API_KEY"

9. Support

For assistance, email support@2fact.io

2fact.io API Documentation