Quick Start

Follow these steps to generate your API key, authenticate your requests, send your first SMS, and track its delivery status.

The NestSMS API allows your application to send SMS messages programmatically without manually using the NestSMS dashboard. You can integrate the API into websites, mobile applications, backend services, notification systems, OTP workflows, and other applications that need automated SMS delivery.

The basic integration flow is:

  1. Generate an API key.
  2. Add the API key to your request.
  3. Send an SMS using the send endpoint.
  4. Save the returned job_id.
  5. Use the job ID to track the message status.

Generate an API Key

Go to API Integration → API Token in the sidebar and click Add Token. Copy the key immediately — it will only be shown once.

Your API key identifies and authenticates your application when it communicates with the NestSMS API. Keep the key private and only use it in trusted server-side environments.

After generating your key, store it in your application's environment variables rather than directly inside your source code.

For example:

NESTSMS_API_KEY=your_api_key_here

This keeps your credentials separate from your application code and configuration.

Add the Key to Your Request

Include your API key using the X-API-Key header:

X-API-Key: your_api_key_here

Every authenticated API request should include your API key. The API uses this key to identify your account and authorize the request.

For example:

curl -X POST https://api.nestsms.com/api/v1/sms/send \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json"

The Content-Type header tells the API that the request body contains JSON data.

Send Your First SMS

Use the POST /api/v1/sms/send endpoint:

curl -X POST https://api.nestsms.com/api/v1/sms/send \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "9840123456",
    "message": "Hello from NestSMS!",
    "sender_id": "YourBrand"
  }'

The request contains three important message fields:

  • to — The recipient's phone number.
  • message — The SMS content you want to send.
  • sender_id — The sender name displayed for the SMS.

The POST method is used because you are submitting a new SMS request to the API.

You can replace the example recipient, message, and sender ID with the values required by your application.

For example:

{
  "to": "9840123456",
  "message": "Your verification code is 4521.",
  "sender_id": "YourBrand"
}

Save the job_id

The response includes a job_id. Use it with GET /api/v1/sms/status/:messageId to track delivery status.

{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "SMS sent successfully"
}

The job_id is the identifier associated with the SMS request. Store it in your application if you need to track the message later.

For example, your application can save the returned job ID together with an internal order ID, user ID, notification ID, or other relevant reference.

A typical integration flow looks like this:

Application
    |
    v
NestSMS API
    |
    v
SMS Request
    |
    v
job_id returned
    |
    v
Store job_id
    |
    v
Check SMS status

Keeping the job_id allows your application to reference the SMS request when checking its delivery status.

Authentication

NestSMS supports authentication through an API key. The API key can be provided using the recommended X-API-Key header or as a Bearer token through the Authorization header.

Method 1: X-API-Key Header

Send your API key in the X-API-Key header. This is the preferred method for all API requests.

fetch("https://api.nestsms.com/api/v1/sms/send", {
  method: "POST",
  headers: {
    "X-API-Key": "your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "9840123456",
    message: "Hello World",
  }),
});

This approach works well for server-side applications where the API request is generated by your backend.

The API key should not be included in code that is delivered directly to browsers or other untrusted clients.

Method 2: Authorization Bearer Token

Alternatively, pass your API key as a Bearer token in the Authorization header.

curl -X POST https://api.nestsms.com/api/v1/sms/send \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"to": "9840123456", "message": "Hello World"}'

The Bearer token is placed after the Bearer keyword in the Authorization header.

Choose one authentication method for your request rather than sending the same API key through multiple authentication headers.

Key Prefixes

  • nsms_live_ — Live key for production. Charges real balance.
  • nsms_test_ — Test key for development. No charges applied.

The key prefix helps distinguish the environment in which the key is intended to be used.

Use the test key when developing and testing your integration, and use the live key when your application is ready to send real SMS messages.

Recommended Integration Flow

For a typical backend integration, keep the API key on your server and let your application communicate with NestSMS from the backend.

User / Application
        |
        v
Your Backend
        |
        v
NestSMS API
        |
        v
SMS Network
        |
        v
Recipient

This keeps the API credential away from client-side code while allowing your backend to control when SMS messages are sent.

Environment Configuration

Instead of placing your API key directly inside your source files, define it as an environment variable.

NESTSMS_API_KEY=your_api_key_here

Your backend can then read the value from its environment when making an API request.

Avoid committing environment files containing real credentials to source control.

Testing Your Integration

Before connecting the API to a complete production workflow, test the integration with a simple SMS request.

A basic test should confirm that:

  • Your API key is accepted.
  • The SMS request is successfully submitted.
  • A job_id is returned.
  • Your application can store the job_id.
  • Your application can use the job ID to check message status.

Once these steps work correctly, you can connect the API to your application's actual notification, OTP, transaction, or messaging workflow.

Common Integration Checks

If your request is not working as expected, check the following:

  • Confirm that the API key is copied correctly.
  • Confirm that the correct authentication header is being used.
  • Check that the request uses POST /api/v1/sms/send.
  • Confirm that the request body contains the required SMS information.
  • Check that the recipient phone number is correct.
  • Confirm that the Content-Type is set to application/json.
  • Check that your application is using the correct API key environment.

Next Steps

Now that you understand the basics:

  1. View complete API Reference
  2. Learn about authentication
  3. Explore framework integrations
  4. Setup white-label platform

The API Reference provides the available endpoints and request details, while the authentication documentation provides additional information about API credentials.

Need help? Contact our support team at support@nestsms.com.