cURL Integation Guide

Welcome to the ReSMS cURL integration guide.

This guide explains how you can interact with the ReSMS API using simple cURL commands from your terminal or scripts.

Features

Send SMS: Send text messages to phone numbers.
Send OTP: Generate and send one-time passwords (OTP) for user verification.
Verify OTP: Validate OTP codes entered by users.

Setup

First, you need to get an API key on ReSMS Dashboard .

Send SMS

You can send an SMS using a simple POST request:


curl --location 'https://api.resms.dev/sms' \
--header 'x-api-key: re_12345' \
--header 'Content-Type: application/json' \
--data '{
    "to": "+33612345678",
    "message": "Welcome to ReSMS!"
}'

Parameters

Field	Type	Required	Description
`to`	String	✅	The phone number of the recipient, in international format (E.164)
`message`	String	✅	The SMS content (160 characters max)
`senderId`	String	❌	The alphanumeric sender name displayed

Response

Success Response


{
  "data": {
    "messageId": "msg_12345"
  }
}

Error Response


{
  "message": "Invalid phone number",
  "name": "PHONE_NUMBER_PARSING_FAILED"
}

Possible errors:

Name	Message
COUNTRY_DETECTION_FAILED	Unable to detect country code from phone number
PHONE_NUMBER_PARSING_FAILED	Invalid phone number
INSUFFICIENT_SMS_QUOTA	Failed to update message status
MESSAGE_STATUS_UPDATE_FAILED	Failed to update message status

Send OTP

Here’s how to send an OTP verification code to a phone number:


curl --location 'https://api.resms.dev/otp' \
--header 'x-api-key: re_12345' \
--header 'Content-Type: application/json' \
--data '{
    "to": "+33612345678",
    "message": "Here is your code: {CODE}"
}'

Parameters

Field	Type	Required	Description	Default Value
`to`	String	✅	The phone number of the recipient, in international format (E.164)
`message`	String	✅	The SMS content (160 characters max). It must contain `{CODE}`.
`senderId`	String	❌	The alphanumeric sender name displayed
`codeType`	String (`"numeric"`\| `"alpha"`)	❌	The type of OTP code to generate	`"numeric"`
`codeLength`	Number	❌	The length of the OTP code	6
`validityMinutes`	Number	❌	The validity period of the OTP in minutes.	5

Example with all parameters:


curl --location 'https://api.resms.dev/otp' \
--header 'x-api-key: re_12345' \
--header 'Content-Type: application/json' \
--data '{
    "to": "+33612345678",
    "message": "Your verification code is {CODE}. Valid for 10 minutes.",
    "senderId": "MyApp",
    "codeType": "numeric",
    "codeLength": 6,
    "validityMinutes": 10
}'

Response

Success Response


{
  "data": {
    "phoneNumber": "+33612345678",
    "expiresAt": "2025-07-20T15:30:00Z"
  }
}

Error Response


{
  "message": "Message template must contain {CODE} placeholder",
  "name": "INVALID_MESSAGE_TEMPLATE"
}

Possible errors:

Code	HTTP Status	Message
`INVALID_MESSAGE_TEMPLATE`	400	Message template must contain `{CODE}` placeholder
`INVALID_CODE_LENGTH`	400	Code length must be between 4 and 16
`INVALID_VALIDITY_DURATION`	400	Validity duration must be between 1 minute and 1440 minutes (24 hours)
`TOO_MANY_OTP_REQUESTS`	429	Too many OTP requests for this phone number

Verify OTP

To verify an OTP code entered by the user:


curl --location 'https://api.resms.dev/otp/verify' \
--header 'x-api-key: re_12345' \
--header 'Content-Type: application/json' \
--data '{
    "to": "+33612345678",
    "code": "123456"
}'

Parameters

Field	Type	Required	Description
`to`	String	✅	The phone number the OTP was sent to, in international format (E.164)
`code`	String	✅	The verification code entered by the user

Response

Success Response


{
  "data": {
    "otpId": "otp_12345",
    "phoneNumber": "+33612345678",
    "verifiedAt": "2025-07-20T15:25:00Z"
  }
}

Error Response


{
  "message": "OTP not found",
  "name": "OTP_NOT_FOUND"
}

Possible errors:

Code	HTTP Status	Message
`OTP_NOT_FOUND`	404	OTP not found
`OTP_INVALID`	400	OTP is invalid
`OTP_EXPIRED`	400	OTP has expired
`OTP_ALREADY_VERIFIED`	400	OTP already verified
`INVALID_OTP_CODE`	400	Invalid OTP code

Have feedback, found a bug, or want to suggest a feature?

Open an issue on GitHub
Or chat with us directly on Discord — we’re happy to help!