FullSMS System
Introduction
API server for the Fullsms service
Fullsms API helps you to better integrate our messaging services with your CRM and marketing campaigns.
To get access to this API, simply generate an API token in the webapp.
This documentation aims to provide all the information you need to work with our API.
Authenticating requests
All authenticated endpoints are marked with a required requires authentication badge in the documentation below. To authenticate requests, send a valid Access Token in the Authorization header, using Bearer authentication scheme (Bearer + Your token).You can retrieve your token by visiting your account, in the Settings click on the API tab and then click Generate API token.
Account
Get my Balance
requires authentication
Get the account current balance.
Example request:
curl --request GET \
--get "https://api.fullsms.com/account/balance" \
--header "Authorization: Bearer 20|YLuvWkTILYKhq365kCuXQW1aCqJe71BbKgzqsGlq" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.fullsms.com/account/balance"
);
const headers = {
"Authorization": "Bearer 20|YLuvWkTILYKhq365kCuXQW1aCqJe71BbKgzqsGlq",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"balance": 100
}
Example response (403, Authorization):
{
"status_code": 403,
"message": "Access Denied"
}
Example response (403, Authentication):
{
"status_code": 403,
"message": "Unauthenticated - Missing/Invalid API key"
}
Example response (500, Server Error):
{
"status_code": 500,
"message": "Internal Error"
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Get my Numbers
requires authentication
Get all available numbers.
Example request:
curl --request GET \
--get "https://api.fullsms.com/account/numbers" \
--header "Authorization: Bearer 20|YLuvWkTILYKhq365kCuXQW1aCqJe71BbKgzqsGlq" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.fullsms.com/account/numbers"
);
const headers = {
"Authorization": "Bearer 20|YLuvWkTILYKhq365kCuXQW1aCqJe71BbKgzqsGlq",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"total_numbers": 1,
"numbers": [
{
"number": "441111111111",
"country": "GB"
}
]
}
Example response (403, Authorization):
{
"status_code": 403,
"message": "Access Denied"
}
Example response (403, Authentication):
{
"status_code": 403,
"message": "Unauthenticated - Missing/Invalid API key"
}
Example response (500, Server Error):
{
"status_code": 500,
"message": "Internal Error"
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Get my Contact Lists
requires authentication
Get all contact lists belonging to this account including their details and subscribed contact count.
Example request:
curl --request GET \
--get "https://api.fullsms.com/account/lists" \
--header "Authorization: Bearer 20|YLuvWkTILYKhq365kCuXQW1aCqJe71BbKgzqsGlq" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.fullsms.com/account/lists"
);
const headers = {
"Authorization": "Bearer 20|YLuvWkTILYKhq365kCuXQW1aCqJe71BbKgzqsGlq",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"total_lists": 1,
"lists": [
{
"list_id": 7,
"name": "yourlistName",
"subscribe_word": null,
"subscribed_contacts": 1
}
]
}
Example response (403, Authorization):
{
"status_code": 403,
"message": "Access Denied"
}
Example response (403, Authentication):
{
"status_code": 403,
"message": "Unauthenticated - Missing/Invalid API key"
}
Example response (500, Server Error):
{
"status_code": 500,
"message": "Internal Error"
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Get my Sender IDs
requires authentication
Fetch all approved Custom Sender ID.
Example request:
curl --request GET \
--get "https://api.fullsms.com/account/senderids" \
--header "Authorization: Bearer 20|YLuvWkTILYKhq365kCuXQW1aCqJe71BbKgzqsGlq" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.fullsms.com/account/senderids"
);
const headers = {
"Authorization": "Bearer 20|YLuvWkTILYKhq365kCuXQW1aCqJe71BbKgzqsGlq",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"total_senderids": 1,
"senderids": [
"COPERATO"
]
}
Example response (403, Authorization):
{
"status_code": 403,
"message": "Access Denied"
}
Example response (403, Authentication):
{
"status_code": 403,
"message": "Unauthenticated - Missing/Invalid API key"
}
Example response (500, Server Error):
{
"status_code": 500,
"message": "Internal Error"
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Get my Templates
requires authentication
Fetch all templates available for the account.
Example request:
curl --request GET \
--get "https://api.fullsms.com/account/templates" \
--header "Authorization: Bearer 20|YLuvWkTILYKhq365kCuXQW1aCqJe71BbKgzqsGlq" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.fullsms.com/account/templates"
);
const headers = {
"Authorization": "Bearer 20|YLuvWkTILYKhq365kCuXQW1aCqJe71BbKgzqsGlq",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"total_templates": 1,
"templates": [
{
"template_id": 7,
"name": "yourTemplateName",
"content": "Hello World"
}
]
}
Example response (403, Authorization):
{
"status_code": 403,
"message": "Access Denied"
}
Example response (403, Authentication):
{
"status_code": 403,
"message": "Unauthenticated - Missing/Invalid API key"
}
Example response (500, Server Error):
{
"status_code": 500,
"message": "Internal Error"
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Send SMS
Send SMS to Contact Lists
requires authentication
This endpoint allows you to Send/Schedule a campaign to a contact lists.
Example request:
curl --request POST \
"https://api.fullsms.com/messages/send/to_lists" \
--header "Authorization: Bearer 20|YLuvWkTILYKhq365kCuXQW1aCqJe71BbKgzqsGlq" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"to_list_ids\": [
7
],
\"message\": \"Your Message\",
\"from\": \"441111111111\",
\"send_at\": \"2025-01-01 08:51:07\"
}"
const url = new URL(
"https://api.fullsms.com/messages/send/to_lists"
);
const headers = {
"Authorization": "Bearer 20|YLuvWkTILYKhq365kCuXQW1aCqJe71BbKgzqsGlq",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"to_list_ids": [
7
],
"message": "Your Message",
"from": "441111111111",
"send_at": "2025-01-01 08:51:07"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
Example response (200):
{
"status": "approved",
"campaign_id": "3e05699c-03ae-11ee-910d-0264ec2cd11b"
}
Example response (403, From Invalid Number):
{
"status_code": 403,
"message": "Number invalid, inactive or unknown"
}
Example response (403, Invalid Sender ID):
{
"status_code": 403,
"message": "Sender ID is not approved"
}
Example response (403, Authorization):
{
"status_code": 403,
"message": "Access Denied"
}
Example response (403, Authentication):
{
"status_code": 403,
"message": "Unauthenticated - Missing/Invalid API key"
}
Example response (404, Not Found):
{
"status_code": 404,
"status": "declined",
"message": "Template not found or not valid"
}
Example response (422, List not Found):
{
"message": "422 Unprocessable Content",
"errors": {
"to_list_ids.0": [
"List with this id could not be found"
]
},
"status_code": 422
}
Example response (422):
{
"message": "422 Unprocessable Content",
"errors": {
"message": [
"The message must be a string."
]
},
"status_code": 422
}
Example response (422, Low Balance):
{
"status_code": 422,
"status": "declined",
"reason": "balance_low",
"message": "Balance must be over $[current minimum for sending] to create or schedule new campaigns or messages"
}
Example response (500, Server Error):
{
"status_code": 500,
"message": "Internal Error"
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Send SMS to Numbers
requires authentication
This endpoint allows you to Send/Schedule SMS messages to one or more recipients.
Example request:
curl --request POST \
"https://api.fullsms.com/messages/send/to_numbers" \
--header "Authorization: Bearer 20|YLuvWkTILYKhq365kCuXQW1aCqJe71BbKgzqsGlq" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"to_numbers\": [
\"972541111111\",
\"972542222222\"
],
\"from\": \"COPERATO\",
\"template_id\": \"42\",
\"send_at\": \"2025-01-01 08:51:07\"
}"
const url = new URL(
"https://api.fullsms.com/messages/send/to_numbers"
);
const headers = {
"Authorization": "Bearer 20|YLuvWkTILYKhq365kCuXQW1aCqJe71BbKgzqsGlq",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"to_numbers": [
"972541111111",
"972542222222"
],
"from": "COPERATO",
"template_id": "42",
"send_at": "2025-01-01 08:51:07"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
Example response (200):
{
"status": "approved",
"campaign_id": "68a6ce95-03b2-11ee-910d-0264ec2cd11b",
"total_sent": 2,
"invalid": {
"count": 0,
"numbers": []
}
}
Example response (403, From Invalid Number):
{
"status_code": 403,
"message": "Number invalid, inactive or unknown"
}
Example response (403, Invalid Sender ID):
{
"status_code": 403,
"message": "Sender ID is not approved"
}
Example response (403, Authorization):
{
"status_code": 403,
"message": "Access Denied"
}
Example response (403, Authentication):
{
"status_code": 403,
"message": "Unauthenticated - Missing/Invalid API key"
}
Example response (404, Not Found):
{
"status_code": 404,
"status": "declined",
"message": "Template not found or not valid"
}
Example response (422):
{
"message": "422 Unprocessable Content",
"errors": {
"to_numbers.0": [
"Given number is invalid or could not receive messages"
]
},
"status_code": 422
}
Example response (422):
{
"message": "422 Unprocessable Content",
"errors": {
"message": [
"The message must be a string."
]
},
"status_code": 422
}
Example response (422, Low Balance):
{
"status_code": 422,
"status": "declined",
"reason": "balance_low",
"message": "Balance must be over $[current minimum for sending] to create or schedule new campaigns or messages"
}
Example response (500, Server Error):
{
"status_code": 500,
"message": "Internal Error"
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
OTP
Create OTP
requires authentication
Creates OTP and Send OTP code via SMS message to the recipientCreates OTP and Send OTP code via SMS message to the recipient.
Example request:
curl --request POST \
"https://api.fullsms.com/otp/create" \
--header "Authorization: Bearer 20|YLuvWkTILYKhq365kCuXQW1aCqJe71BbKgzqsGlq" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"to_number\": \"442222222222\",
\"brand\": \"Your Brand\",
\"from\": \"441111111111\"
}"
const url = new URL(
"https://api.fullsms.com/otp/create"
);
const headers = {
"Authorization": "Bearer 20|YLuvWkTILYKhq365kCuXQW1aCqJe71BbKgzqsGlq",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"to_number": "442222222222",
"brand": "Your Brand",
"from": "441111111111"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
Example response (200):
{
"status": "approved",
"otp_id": "35efec9e-b736-4aab-b6d7-52d9fc288984",
"otp_status": "in_progress"
}
Example response (403, Authorization):
{
"status_code": 403,
"message": "Access Denied"
}
Example response (403, Authentication):
{
"status_code": 403,
"message": "Unauthenticated - Missing/Invalid API key"
}
Example response (403, From Invalid Number):
{
"status_code": 403,
"message": "Number invalid, inactive or unknown"
}
Example response (403, Invalid Sender ID):
{
"status_code": 403,
"message": "Sender ID is not approved"
}
Example response (422):
{
"message": "422 Unprocessable Content",
"errors": {
"[field name]": [
"This [field name] is invalid."
]
},
"code": 422,
"status_code": 422
}
Example response (429, OTP Exists and Active):
{
"message": "Two active requests to the same number are not allowed. You may try again when 30 seconds has passed from the first OTP verification was created",
"code": 429,
"status_code": 429
}
Example response (429, OTP Create Limit):
{
"message": "You can create up-to [maximum] concurrent active OTP_IDs",
"code": 429,
"status_code": 429
}
Example response (500, Server Error):
{
"status_code": 500,
"message": "Internal Error"
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Verify OTP
requires authentication
Verify received OTP Code for errors.
Example request:
curl --request POST \
"https://api.fullsms.com/otp/verify" \
--header "Authorization: Bearer 20|YLuvWkTILYKhq365kCuXQW1aCqJe71BbKgzqsGlq" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"otp_id\": \"6a68fb58-9f58-450e-bf06-d5008977116a\",
\"code\": 626262
}"
const url = new URL(
"https://api.fullsms.com/otp/verify"
);
const headers = {
"Authorization": "Bearer 20|YLuvWkTILYKhq365kCuXQW1aCqJe71BbKgzqsGlq",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"otp_id": "6a68fb58-9f58-450e-bf06-d5008977116a",
"code": 626262
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
Example response (200):
{
"status": "approved"
}
Example response (403, Authorization):
{
"status_code": 403,
"message": "Access Denied"
}
Example response (403, Authentication):
{
"status_code": 403,
"message": "Unauthenticated - Missing/Invalid API key"
}
Example response (404, Not Found):
{
"status_code": 404,
"status": "declined",
"message": "OTP_ID does not exist"
}
Example response (422):
{
"message": "422 Unprocessable Content",
"errors": {
"[field name]": [
"This [field name] is invalid."
]
},
"code": 422,
"status_code": 422
}
Example response (422, Invalid Code):
{
"message": "422 Unprocessable Content",
"errors": {
"code": [
"This code is invalid."
]
},
"code": 422,
"status_code": 422
}
Example response (422, OTP not Active):
{
"message": "OTP is not active",
"status_code": 422
}
Example response (500, Server Error):
{
"status_code": 500,
"message": "Internal Error"
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Cancel OTP
requires authentication
Cancel existing active OTP.
Example request:
curl --request POST \
"https://api.fullsms.com/otp/cancel" \
--header "Authorization: Bearer 20|YLuvWkTILYKhq365kCuXQW1aCqJe71BbKgzqsGlq" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data "{
\"otp_id\": \"6a68fb58-9f58-450e-bf06-d5008977116a\"
}"
const url = new URL(
"https://api.fullsms.com/otp/cancel"
);
const headers = {
"Authorization": "Bearer 20|YLuvWkTILYKhq365kCuXQW1aCqJe71BbKgzqsGlq",
"Content-Type": "application/json",
"Accept": "application/json",
};
let body = {
"otp_id": "6a68fb58-9f58-450e-bf06-d5008977116a"
};
fetch(url, {
method: "POST",
headers,
body: JSON.stringify(body),
}).then(response => response.json());
Example response (200):
[
"ok"
]
Example response (403, Authorization):
{
"status_code": 403,
"message": "Access Denied"
}
Example response (403, Authentication):
{
"status_code": 403,
"message": "Unauthenticated - Missing/Invalid API key"
}
Example response (404, Not Found):
{
"status_code": 404,
"status": "declined",
"message": "OTP_ID does not exist"
}
Example response (422, OTP not Active):
{
"message": "OTP is not active",
"status_code": 422
}
Example response (500, Server Error):
{
"status_code": 500,
"message": "Internal Error"
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Search OTP
requires authentication
Search Otp Information.
Example request:
curl --request GET \
--get "https://api.fullsms.com/otp/search?otp_id=6a68fb58-9f58-450e-bf06-d5008977116a" \
--header "Authorization: Bearer 20|YLuvWkTILYKhq365kCuXQW1aCqJe71BbKgzqsGlq" \
--header "Content-Type: application/json" \
--header "Accept: application/json"
const url = new URL(
"https://api.fullsms.com/otp/search"
);
const params = {
"otp_id": "6a68fb58-9f58-450e-bf06-d5008977116a",
};
Object.keys(params)
.forEach(key => url.searchParams.append(key, params[key]));
const headers = {
"Authorization": "Bearer 20|YLuvWkTILYKhq365kCuXQW1aCqJe71BbKgzqsGlq",
"Content-Type": "application/json",
"Accept": "application/json",
};
fetch(url, {
method: "GET",
headers,
}).then(response => response.json());
Example response (200):
{
"uuid": "23d8ab2e-cd91-47c7-a83f-aa99b8903c38",
"status": "approved",
"destination": "972546461393",
"sender_value": "OTP",
"brand": "",
"created at": "2023-06-05 13:02:56",
"last_check_at": "2023-06-05 13:04:13",
"checks": [
{
"date": "2023-06-05 13:03:24",
"code": 686281,
"status": "invalid"
},
{
"date": "2023-06-05 13:04:13",
"code": 720842,
"status": "valid"
}
]
}
Example response (403, Authorization):
{
"status_code": 403,
"message": "Access Denied"
}
Example response (403, Authentication):
{
"status_code": 403,
"message": "Unauthenticated - Missing/Invalid API key"
}
Example response (404, Not Found):
{
"status_code": 404,
"status": "declined",
"message": "OTP_ID does not exist"
}
Example response (500, Server Error):
{
"status_code": 500,
"message": "Internal Error"
}
Received response:
Request failed with error:
Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.
Errors
General Error Codes
Authentication and Authorization Errors
Code | Body | Description |
---|---|---|
403 | {
"message": "Access Denied" } |
Restriction |
403 | {
"message": "Unauthenticated - Missing/Invalid API key", |
Missing/Invalid API key |
500 | {
"message": "Internal Error", |
Internal Error |
Messages Errors
Code | Body | Description |
---|---|---|
403 | {
"status_code": 403, |
Forbidden - Custom Sender ID must be approved for the account. To check if a custom ID is approved for you see Account - Get my approved Custom Sender IDs |
403 | {
"status_code": 403, |
Forbidden - Number does not belong to the account, is missing, invalid or inactive |
403 | {
"status_code": 403, |
Shortlinks are not allowed in your account. You may use templates without shortlinks. |
404 | {
"status_code": 404, |
Template not found or not valid |
422 | {
"status_code": 422, |
Account Balance Below Minimum |