API Documentation

Authentication

Most endpoints require authentication. This can typically be achieved in one of two ways:

  1. User API Key (api_key): A unique key associated with a specific user. When provided, the API operates within the context of that user.

Endpoints

GET Initialize Client /api/init/{api_key}

Retrieves essential data like countries and operators from the main server. This data can be used, for example, to populate selection fields in a user interface.

Authentication Details

The request must be authenticated using one of the following methods:

  • Provide a valid api_key for a specific user.

If authentication fails, or if the system API key is not configured on the server when it's required, an error will be returned.

Success Response

Status Code: 200 OK

Content:


{
    "status": "success",
    "data": {
        "countries": [
            {
                "id": 1,
                "name": "Country A",
                "phone_code": "1"
                // ... other country-specific fields
            },
            {
                "id": 2,
                "name": "Country B",
                "phone_code": "44"
                // ... other country-specific fields
            }
        ],
        "operators": [
            {
                "id": 101,
                "name": "Operator X",
                "country_id": 1
                // ... other operator-specific fields
            },
            {
                "id": 102,
                "name": "Operator Y",
                "country_id": 2
                // ... other operator-specific fields
            }
        ]
    }
}

Error Responses

Status Code Message Description
401 Unauthorized Authentication failed (e.g., invalid api_key
500 System configuration error The system API key is not configured on the server.
500 Service fetch failed An unexpected error occurred while trying to fetch data from the main service.
XXX (message from external service) The external service returned an error. XXX will be the status code from the external service.

GET Get Phone Number /api/get-number/{api_key}

Requests a phone number from the main server based on the provided criteria (country, operator). If successful, the number is assigned to the specified user, and relevant records (phone number, user summary, system summary) are updated. Operator information is also synced locally if new operator data is received.

Authentication Details

The request must be authenticated:

  • Using api_key: Provide a valid api_key for an active and approved user. The user_id parameter is ignored if api_key is used.

The user's manager (if any) must also be active.

Request Parameters

Parameter Type In Required Description
country_id integer Query Yes The ID of the country from which to request the number.
operator_id integer Query No The ID of the specific mobile operator. If omitted, an operator may be chosen automatically.
number_format string Query No Desired format for the returned phone number.
Possible values: full, national, remove_plus.
Defaults to the user's preference or full.

Success Response

Status Code: 200 OK

Content:


{
    "status": "success",
    "data": {
        "phone_number": "+1234567890" // Or formatted as per 'number_format'
    }
}

Error Responses

Status Code Message Description
400 user_id is required with api_key user_id was not provided when authenticating with api_key.
400 country_id is required The country_id parameter was missing.
401 Invalid api_key The provided api_key is invalid or does not belong to an active/approved user.
401 Missing or invalid credentials No valid authentication method (api_key or api_key + user_id) was provided.
403 Manager inactive. Contact support. The target user's manager is inactive.
404 Target user not found or inactive The user specified by user_id (with api_key) was not found, is inactive, or not approved.
404 No number received The external service did not return a phone number.
500 Could not fetch service data Failed to fetch prerequisite data (like country list for number formatting) from the main service.
500 Unable to get number An unexpected error occurred on the server while trying to get or process the phone number (e.g., external service call failed).

Webhook Configuration

Webhooks provide real-time notifications to your server when certain events occur within our system, such as the reception of an OTP. This allows for immediate processing of data without the need for continuous polling.

Setting Your Webhook URL

You can configure your webhook URL directly from your user profile settings. Navigate to your profile edit page and locate the "Webhook URL" field. Enter the URL where you wish to receive notifications.

Once set, our system will send POST requests to this URL whenever a relevant event occurs.

Supported Events and Payload Structure

Currently, the primary event supported is otp_received, which is triggered when an OTP is successfully received for one of your assigned phone numbers.

Event: otp_received

This event is sent when an OTP SMS is received for a phone number assigned to your account.

Method: POST

Content-Type: application/json

Payload Example:


{
    "event": "otp_received",
    "data": {
        "phone_number": "+1234567890",
        "otp_code": "123456",
        "provider": "SMS_GATEWAY_PROVIDER_NAME",
        "sms_text": "Your OTP is 123456. Do not share this code."
    }
}

Ensure your webhook endpoint is prepared to receive and process this JSON payload.