API Documentation

Integrate GearSMS API to automate OTP verification with real SIM-based non-VoIP numbers. Ideal for developers and businesses needing fast, secure, and scalable SMS verification

Base URL:

https://app.gearsms.com/api/v1

Authentication

Authorize your requests by including your secret API key in the X-API-Key request header. All requests must be made over HTTPS.

HEADER X-API-Key

Value: Your-Secret-API-Key

Example: X-API-Key: gs_live_abcdef1234567890

Check Balance

Retrieve the current balance of your GearSMS account.

GET https://app.gearsms.com/api/v1/balance

Authentication: Your-Secret-API-Key

200 Success

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "Balance retrieved successfully",
  "data": {
    "user": "developer@example.com",
    "balance": 125.5
  }
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key or Missing Header"
}
                                    

Webhooks

Webhooks allow you to receive real-time HTTP POST notifications when an SMS code is received.

Configure your Webhook URL in your API Settings.

Delivery Behavior

Our system attempts to deliver the webhook notification immediately after an SMS is received.

Method: POST (JSON payload)
Timeout: 5 seconds
Retries: None (single delivery attempt)
User-Agent: GearSMS-Webhook/1.0

Payload Description

Field	Type	Description
event	String	The event type (currently `sms_received`)
orderId	String	The unique identifier for the order
number	String	The phone number that received the SMS
service	String	The name of the service (e.g., Google, WhatsApp)
sms	String	The full content of the received SMS message
pin	String	The extracted verification code/pin from the message
source	String	The service tier source (S1, S2, GLOBAL, or LTR)
timestamp	String	ISO 8601 timestamp of the event

Example: sms_received event

POST Your Configured URL

Payload Example

{
  "event": "sms_received",
  "orderId": "65f2a1b...",
  "number": "+12025550123",
  "service": "Google",
  "sms": "Your verification code is 123456",
  "pin": "123456",
  "source": "S1",
  "timestamp": "2026-03-26T14:30:00Z"
}
                                    

Temp Numbers S1

S1 offers high-quality US-based numbers from major carriers, ideal for services with strict verification requirements. You can also filter numbers by US state for localized verification.

All S1 numbers are Non-VoIP and support a 15:15-minute reservation window.

1. Get States

Retrieve a list of available US states and their 2-letter codes for selection during number request.

GET https://app.gearsms.com/api/v1/temp-s1/states

Authentication: Your-Secret-API-Key

200 Success

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "States retrieved successfully",
  "data": [
    {
      "code": "AK",
      "name": "Alaska"
    },
    {
      "code": "AL",
      "name": "Alabama"
    },
    {
      "code": "CA",
      "name": "California"
    }
  ]
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key"
}
                                    

2. Get Services

List all available services for S1 with your user-specific pricing applied.

GET https://app.gearsms.com/api/v1/temp-s1/services

Authentication: Your-Secret-API-Key

200 Success

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "S1 services retrieved successfully",
  "data": [
    {
      "name": "Google",
      "price": 0.5,
      "available": 1000
    },
    {
      "name": "Tinder",
      "price": 0.7,
      "available": 500
    }
  ]
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key"
}
                                    

3. Request Number

Purchase a temporary number. You can optionally specify a state code from the States endpoint.

POST https://app.gearsms.com/api/v1/temp-s1/order

Authentication: Your-Secret-API-Key

Request Body (JSON Example): { "service": "Google", "state": "TX" }

200 Success

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "S1 number purchased successfully",
  "data": {
    "id": "65f2a1...",
    "number": "+12025550111",
    "service": "Google",
    "status": "pending",
    "expiresAt": "2026-03-26T15:00:00Z",
    "balance": 24.5
  }
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key"
}
                                    

Request Body Properties

Property	Type	Required	Description
service	`string`	Yes	The name of the service (e.g., "Google", "Tinder").
state	`string`	No	2-letter US state code from the States endpoint.

4. Check SMS Status

Poll this endpoint to receive the SMS for an active S1 order.

GET https://app.gearsms.com/api/v1/temp-s1/check-sms/:orderId

Authentication: Your-Secret-API-Key

200 Success

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "SMS status retrieved",
  "data": {
    "id": "65f2a1...",
    "status": "completed",
    "sms": "G-123456 is your code",
    "pin": "123456",
    "expiresAt": "2026-03-26T15:00:00Z",
    "balance": 24.5
  }
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key"
}
                                    

5. Get Number Details

Retrieve the current status and number information for an active S1 order.

GET https://app.gearsms.com/api/v1/temp-s1/number-details/:orderId

Authentication: Your-Secret-API-Key

200 Success

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "Order details retrieved successfully",
  "data": {
    "id": "65f2a1...",
    "number": "+12025550111",
    "service": "Google",
    "status": "completed",
    "sms": "G-123456 is your code",
    "pin": "123456",
    "expiresAt": "2026-03-26T15:00:00Z",
    "balance": 24.5
  }
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key"
}
                                    

Request Params Properties

Property	Type	Required	Description
orderId	`string`	Yes	The unique ID of your active S1 order.

6. Reject Number

Reject a number if it is not receiving SMS. This will cancel the order and issue an immediate refund.

POST https://app.gearsms.com/api/v1/temp-s1/cancel/:orderId

Authentication: Your-Secret-API-Key

200 Success

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "Order cancelled successfully",
  "data": {
    "id": "65f2a1...",
    "number": "2025550111",
    "service": "Google",
    "status": "rejected",
    "refunded": true,
    "refundAmount": 0.5,
    "balance": 25.5
  }
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key"
}
                                    

Request Params Properties

Property	Type	Required	Description
orderId	`string`	Yes	The unique ID of the order to cancel/reject.

Temp Numbers S2

The S2 pool provides specialized US numbers with support for area code selection. This service is optimized for high-volume automated verifications and supports dynamic reservation windows.

1. Reservation Windows

Reservation windows for S2 services vary by provider and service (e.g., 5, 10, or 15+ minutes). It is critical to monitor the expiresAt field in the API response for the precise expiration timestamp.

Pro Tip: Always calculate the remaining time by comparing the current system time with the expiresAt value returned when you request a number.

2. Service Specific Rules

Important Operational Notes:

Non-rejection Services: The following services do not allow manual rejection. A refund is automatically issued only after the number's timer expires: Cash App, Citibank, Go2Bank, GoBank, Green Dot, One Finance, Snapchat, Survey Junkie, Walmart Family Mobile, Walmart Money Card, Wells Fargo, WhatsApp.
Non-reported Services: The following services do not allow manual reporting. You must wait for the number's timer to expire for an automatic refund: Cash App, Citibank, Go2Bank, GoBank, Green Dot, One Finance, Snapchat, Survey Junkie, Walmart Family Mobile, Walmart Money Card, WhatsApp.
Always Charged: You will be charged for the following services whether a code is received or not: Wells Fargo.

3. Get Services

Retrieve a list of all available services in the S2 pool with your specific pricing.

GET https://app.gearsms.com/api/v1/temp-s2/services

Authentication: Your-Secret-API-Key

200 Success

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "S2 services retrieved successfully",
  "data": [
    {
      "code": "Google",
      "name": "Google",
      "price": 0.5
    },
    {
      "code": "Telegram",
      "name": "Telegram",
      "price": 0.4
    }
  ]
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key"
}
                                    

4. List Area Codes

Retrieve a list of available 3-digit US area codes for S2 numbers. You can use these codes in the areacode parameter when requesting a number.

GET https://app.gearsms.com/api/v1/temp-s2/area-codes

Authentication: Your-Secret-API-Key

200 Success

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "S2 area codes retrieved successfully",
  "data": [
    {
      "areaCode": "201",
      "state": "NJ"
    },
    {
      "areaCode": "212",
      "state": "NY"
    },
    {
      "areaCode": "310",
      "state": "CA"
    }
  ]
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key"
}
                                    

5. Request Number

Order a new temporary number from the S2 pool. You can specify an area code and a preferred carrier (e.g., T-Mobile, Verizon, AT&T).

POST https://app.gearsms.com/api/v1/temp-s2/order

Authentication: Your-Secret-API-Key

Request Body Example: { "service": "Google", "areacode": "212", "carrier": "vz" }

200 Success

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "Number purchased successfully",
  "data": {
    "id": "65f456def7890abc123",
    "number": "2272585038",
    "service": "airbnb",
    "price": 0.5,
    "status": "pending",
    "expiresAt": "2024-03-26T15:55:00Z",
    "balance": 24.5
  }
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key"
}
                                    

Request Body Properties

Property	Type	Required	Description
service	`string`	Yes	The name of the service (e.g., "Google", "WhatsApp").
areacode	`string`	No	Optional 3-digit US area code. (+65% markup)
carrier	`string`	No	Optional carrier (`tmo`, `vz`, `att`). (+25% markup)

6. Check SMS Status

Check for incoming SMS messages for an active S2 order. This is the primary way to receive your verification code.

GET https://app.gearsms.com/api/v1/temp-s2/check-sms/:orderId

Authentication: Your-Secret-API-Key

200 Success

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "SMS status retrieved",
  "data": {
    "id": "69c7ad1a2f32f64010789387",
    "number": "2272585038",
    "service": "airbnb",
    "status": "completed",
    "price": 0.38,
    "sms": "Your code is 123456",
    "pin": "123456",
    "expiresAt": "2024-03-26T16:00:00Z",
    "balance": 24.12
  }
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key"
}
                                    

Request Params Properties

Property	Type	Required	Description
orderId	`string`	Yes	The unique ID of your active S2 order.

7. Reject Number

Cancel an active order if you haven't received a code yet. Note that some services are non-refundable.

POST https://app.gearsms.com/api/v1/temp-s2/cancel/:orderId

Authentication: Your-Secret-API-Key

200 Success

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "Order cancelled and refunded.",
  "data": {
    "id": "69c82acb37795b41530471e5",
    "number": "8143501458",
    "service": "tinder",
    "status": "cancelled",
    "refunded": true,
    "refundAmount": 0.75,
    "balance": 99.19
  }
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key"
}
                                    

Request Params Properties

Property	Type	Required	Description
orderId	`string`	Yes	The unique ID of the order to cancel/reject.

8. Reactivate / Reuse Number

If you need another code for the same service on a previously used number, you can attempt to reactivate it. Success depends on the number still being available in the pool.

POST https://app.gearsms.com/api/v1/temp-s2/reactivate/:orderId

Authentication: Your-Secret-API-Key

200 Success

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "Number reactivated successfully",
  "data": {
    "id": "69c7ad1a2f32f64010789387",
    "number": "2272585038",
    "service": "airbnb",
    "status": "pending",
    "price": 0.5,
    "expiresAt": "2024-03-26T16:00:00Z",
    "balance": 25.0
  }
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key"
}
                                    

Request Params Properties

Property	Type	Required	Description
orderId	`string`	Yes	The unique ID of the original S2 order you wish to reactivate.

Note: Reactivating a number will charge your account the same amount as a new purchase. Success depends on the number still being available in the provider's pool.

9. Report Number

Report a number if it is not receiving SMS or if the code provided is invalid. Note that some services do not allow manual reporting.

POST https://app.gearsms.com/api/v1/temp-s2/report/:orderId

Authentication: Your-Secret-API-Key

200 Success

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "Order reported successfully",
  "data": {
    "id": "69c82acb37795b41530471e5",
    "number": "8143501458",
    "service": "tinder",
    "status": "reported",
    "refunded": true,
    "refundAmount": 0.75,
    "balance": 99.19
  }
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key"
}
                                    

Request Params Properties

Property	Type	Required	Description
orderId	`string`	Yes	The unique ID of the order to report.

Temp Numbers Global

The Global pool offers SMS verification numbers from over 100 countries worldwide. Ideal for international services and localized testing.

1. Get Countries

Retrieve a list of supported countries and their corresponding IDs for the Global pool.

GET https://app.gearsms.com/api/v1/temp-global/countries

Authentication: Your-Secret-API-Key

200 Success

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "Global countries retrieved successfully",
  "data": [
    {
      "ID": 1,
      "name": "United States",
      "short_name": "US"
    }
  ]
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key"
}
                                    

2. List Services

Get a list of available services and their current pricing for a specific country.

GET https://app.gearsms.com/api/v1/temp-global/services

Authentication: Your-Secret-API-Key

Query: ?country=1 (Use Country ID from Section 1)

200 Success

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "Global services retrieved successfully",
  "data": [
    {
      "code": "1",
      "name": "Google",
      "price": 0.46,
      "stock": 1500,
      "success_rate": 95
    },
    {
      "code": "2",
      "name": "Telegram",
      "price": 0.36,
      "stock": 800,
      "success_rate": 88
    }
  ]
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key"
}
                                    

3. Check Stock

Verify real-time stock availability for a specific service and country.

GET https://app.gearsms.com/api/v1/temp-global/stock

Authentication: Your-Secret-API-Key

Query: ?country=1&service=Google

200 Success

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "Global stock retrieved successfully",
  "data": {
    "stock": 500
  }
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key"
}
                                    

4. List Area Codes

Retrieve available 3-digit phone area codes for a country and service.

GET https://app.gearsms.com/api/v1/temp-global/area-codes

Authentication: Your-Secret-API-Key

Query: ?country=1&service=Google

200 Success

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "Global area codes retrieved successfully",
  "data": [
    "201",
    "202",
    "212",
    "310"
  ]
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key"
}
                                    

5. Request Number

Order a temporary number from a specific country for your chosen service. Optional parameters available for area code targeting.

POST https://app.gearsms.com/api/v1/temp-global/order

Authentication: Your-Secret-API-Key

Body (JSON): { "service": "Google", "country": 1, "areacode": "212" }

200 Success

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "Global number purchased successfully",
  "data": {
    "id": "GLOB_123456",
    "number": "+12125550123",
    "service": "Google",
    "price": 0.46,
    "status": "pending",
    "expiresAt": "2024-03-26T15:50:00.000Z",
    "balance": "98.54"
  }
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "No numbers available"
}
                                    

Dynamic Timers & Status

Global orders provide an expiresAt timestamp. Always use this ISO string for your countdown as timers may vary by country/provider.

Note: Some numbers may return a status of activating immediately after purchase. This indicates the provider is preparing the line. Please continue polling the check-status endpoint until the status becomes pending or completed.

6. Check SMS Status

Poll this endpoint to receive the SMS for an active Global order.

GET https://app.gearsms.com/api/v1/temp-global/check-sms/:orderId

Authentication: Your-Secret-API-Key

200 Ready

Waiting

Activating

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "SMS status retrieved",
  "data": {
    "status": "completed",
    "sms": "Your code is 123456",
    "pin": "123456",
    "expiresAt": "2024-03-26T16:00:00Z"
  }
}
                                    

{
  "success": true,
  "statusCode": 200,
  "message": "Still waiting for SMS",
  "data": {
    "status": "pending",
    "sms": null,
    "pin": null,
    "expiresAt": "2024-03-26T16:00:00Z"
  }
}
                                    

{
  "success": true,
  "statusCode": 200,
  "message": "Number is activating",
  "data": {
    "status": "activating",
    "sms": null,
    "pin": null,
    "expiresAt": "2024-03-26T16:00:00Z"
  }
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key"
}
                                    

7. Reject Number

Cancel an active Global order and receive a refund if no SMS has been received.

POST https://app.gearsms.com/api/v1/temp-global/cancel/:orderId

Authentication: Your-Secret-API-Key

200 Success

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "Order cancelled and refunded successfully",
  "data": {
    "id": "GLOB_123456",
    "service": "Google",
    "status": "rejected",
    "balance": 25.5
  }
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key"
}
                                    

8. Reuse Number

Request another SMS code for an existing Global order. This will create a new order record for the same number.

POST https://app.gearsms.com/api/v1/temp-global/reuse/:orderId

Authentication: Your-Secret-API-Key

200 Success

400 Failed

{
  "success": true,
  "statusCode": 200,
  "message": "Global reactivation requested successfully",
  "data": {
    "id": "NEW_GLOB_456",
    "service": "Google",
    "status": "pending",
    "number": "+12125550123",
    "expiresAt": "2024-03-26T15:50:00.000Z"
  }
}
                                    

{
  "success": false,
  "message": "Reuse option is not available for this number."
}
                                    

Long-term Numbers

Rent dedicated numbers for extended periods (3, 7, 14, or 30 days) to receive multiple SMS codes for the same service over time.

1. List Rental Services

Retrieve a list of services available for long-term rental with their starting prices.

GET https://app.gearsms.com/api/v1/long-term-numbers/services

Authentication: Your-Secret-API-Key

200 Success

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "Rental services retrieved successfully",
  "data": [
    {
      "code": "Google",
      "name": "Google",
      "available": true
    },
    {
      "code": "Telegram",
      "name": "Telegram",
      "available": true
    }
  ]
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key"
}
                                    

2. Get Available Durations

Retrieve a list of supported rental durations. These codes should be used for the duration parameter in pricing and ordering.

GET https://app.gearsms.com/api/v1/long-term-numbers/durations

Authentication: Your-Secret-API-Key

200 Success

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "Rental durations retrieved successfully",
  "data": [
    {
      "code": "3days",
      "name": "3 Days"
    },
    {
      "code": "7days",
      "name": "7 Days"
    },
    {
      "code": "14days",
      "name": "14 Days"
    },
    {
      "code": "30days",
      "name": "30 Days"
    }
  ]
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key"
}
                                    

3. Get Area Codes

Retrieve a list of available 3-digit US area codes for long-term rentals. You can use these in the areaCode parameter when checking price or ordering.

Selecting an Area Code is optional. If selected, our system will apply a flat $2.50 surcharge to the rental price.

GET https://app.gearsms.com/api/v1/long-term-numbers/area-codes

Authentication: Your-Secret-API-Key

200 Success

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "Rental area codes retrieved successfully",
  "data": [
    {
      "areaCode": "201",
      "state": "NJ"
    },
    {
      "areaCode": "212",
      "state": "NY"
    },
    {
      "areaCode": "310",
      "state": "CA"
    }
  ]
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key"
}
                                    

4. Check Rental Pricing

Get the exact price for a rental based on service, duration, and optional area code.

GET https://app.gearsms.com/api/v1/long-term-numbers/price

Authentication: Your-Secret-API-Key

Query: ?serviceCode=Google&duration=30days&areaCode=212

200 Success

400 Failed

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "Rental price retrieved successfully",
  "data": {
    "service": "Google",
    "price": 45.0
  }
}
                                    

{
  "success": false,
  "message": "Invalid service or duration specified."
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key"
}
                                    

Parameters

Property	Type	Required	Description
serviceCode	`string`	Yes	Service identifier (e.g., Google).
duration	`string`	Yes	Available: `3days`, `7days`, `14days`, `30days`.
areaCode	`string`	No	3-digit US area code. (Optional, $2.50 fee applies)

5. Request Rental Number

Purchase a dedicated long-term rental number. This will deduct the balance immediately.

POST https://app.gearsms.com/api/v1/long-term-numbers/order

Authentication: Your-Secret-API-Key

Body (JSON): { "service": "Google", "duration": "30days", "areaCode": "212" }

200 Success

400 Failed

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "Long-term number rented successfully",
  "data": {
    "id": "RENT_65f...",
    "number": "+12025550333",
    "service": "Google",
    "duration": "30days",
    "price": 45.0,
    "status": "active",
    "expiresAt": "2024-04-26T12:00:00Z",
    "balance": "155.00"
  }
}
                                    

{
  "success": false,
  "message": "Insufficient balance to complete the rental."
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key"
}
                                    

6. Check SMS Messages

Fetch all SMS messages received by your active rental number.

GET https://app.gearsms.com/api/v1/long-term-numbers/check-sms/:orderId

Authentication: Your-Secret-API-Key

200 Success

Expired

401 Unauthorized

{
  "success": true,
  "statusCode": 200,
  "message": "SMS received",
  "data": {
    "id": "69c7e1...",
    "number": "+12025550333",
    "service": "Google",
    "status": "active",
    "expiresAt": "2024-04-26T12:00:00Z",
    "messages": [
      {
        "text": "G-123456 is your code",
        "date_time": "2024-04-26T11:00:00.000Z",
        "pin": "123456"
      }
    ]
  }
}
                                    

{
  "success": true,
  "statusCode": 200,
  "message": "Rental has expired",
  "data": {
    "status": "expired",
    "expiresAt": "2024-03-20T10:00:00Z",
    "messages": [
      {
        "text": "Old message content",
        "date_time": "2024-03-20T09:00:00.000Z",
        "pin": ""
      }
    ]
  }
}
                                    

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid API Key"
}
                                    