Partner API v1

Integrate your platform with GlobalConnect to obtain virtual phone numbers and receive SMS verification codes in real time.

Base URL

https://lucky-sms.com/SMSBOWER

The endpoint is also accessible at /api/partner. It accepts both GET and POST requests. For POST, send a application/json; charset=utf-8 body. For GET, pass all parameters as query-string fields.

Authentication

Every request must include the key field containing your Partner API key. Keys are issued and managed through the admin panel.

{
  "action": "...",
  "key": "your_api_key_here"
}

If the key is missing or invalid the server returns HTTP 401:

{"status":"ERROR","message":"Invalid key"}

GET POST GET_SERVICES

Returns the list of available countries, operators, and services together with the number of phone numbers available for each service.

Request

{
  "action": "GET_SERVICES",
  "key": "your_api_key"
}

Response

{
  "status": "SUCCESS",
  "countryList": [
    {
      "country": "england",
      "operatorMap": {
        "Hutchison 3G UK Ltd": {
          "tg": 4,
          "google": 2
        }
      }
    }
  ]
}

The numbers in operatorMap represent how many phone numbers are currently available for that service code.

GET POST GET_NUMBER

Requests a phone number for a specific service. The number is reserved for your activation session and remains valid for 60 minutes.

Request fields

Request example

POST https://lucky-sms.com/SMSBOWER
Content-Type: application/json; charset=utf-8

{
  "action": "GET_NUMBER",
  "key": "your_api_key",
  "country": "england",
  "operator": "Hutchison 3G UK Ltd",
  "service": "tg",
  "sum": "20.00",
  "exceptionPhoneSet": ["447472190082", "447472190099"]
}

Success response

{
  "number": "447472190082",
  "activationId": 36532,
  "status": "SUCCESS",
  "call": 0,
  "voice": 0
}

• number – phone number without leading +
• activationId – ulong; use this in subsequent FINISH_ACTIVATION and GETSMS calls

No numbers available

{"status":"NO_NUMBERS"}

GET POST FINISH_ACTIVATION

Sent from your server to this server to close an activation session and report the outcome.

Request fields

Request example

POST https://lucky-sms.com/SMSBOWER
Content-Type: application/json; charset=utf-8

{
  "action": "FINISH_ACTIVATION",
  "key": "your_api_key",
  "activationId": 36532,
  "status": 3
}

Response

{"status":"SUCCESS"}

POST PUSH_SMS — Incoming SMS notification

When a Push URL is configured for your API key, this server will POST every incoming SMS to that URL as application/json; charset=utf-8 immediately after receiving it.

If your server returns a response with "status": "SUCCESS", the message is marked as delivered and no further attempts are made.

If any other response (or a network error) is received, the server will retry every 10 seconds. Retries stop as soon as one of the following conditions is met:

• Your server responds with "status": "SUCCESS".
• The activation is closed via FINISH_ACTIVATION with any terminal status code (1, 3, 4, or 5).

While the activation remains pending (no FINISH_ACTIVATION received), PUSH_SMS continues to retry regardless of how many attempts have been made.

Fields sent by this server (to your Push URL)

Example request (from this server to your endpoint)

POST https://your-server.com/agent/api/sms
Content-Type: application/json; charset=utf-8

{
  "key": "your_api_key",
  "action": "PUSH_SMS",
  "smsId": "36532",
  "phone": "447472190082",
  "phoneFrom": "Microsoft",
  "text": "Microsoft access code: 5015",
  "call": 0,
  "voice": 0
}

Expected response from your server

{"status":"SUCCESS"}

GET Manual SMS Polling

If no Push URL is configured for your key, you can manually poll for incoming SMS messages using this endpoint.

Endpoint

GET https://lucky-sms.com/SMSBOWER/getsms/?apiKey={apiKey}&id={activationId}

Parameters

Responses

SMS available:

{
  "status": "SUCCESS",
  "messages": [
    {
      "smsId": "abc123",
      "phone": "447472190082",
      "phoneFrom": "Microsoft",
      "text": "Microsoft access code: 5015",
      "receivedAt": "2024-01-15T12:34:56+00:00"
    }
  ]
}

No SMS yet:

{"status":"WAIT_CODE"}

Activation expired:

{"status":"EXPIRED"}

Activation Statuses

Use these status codes in the FINISH_ACTIVATION request:

Error Responses