API

API docs

Ang TODAY SMS API ay JSON API sa HTTPS. Ipadala ang iyong API key sa Authorization header sa bawat request. Pareho sa website ang presyo, refund at ang 20 minutong paghihintay. Pumili ng method sa listahan para makita ang sample ng request at response.

Gumawa ng API key sa API key page kapag pumasok na ang una mong top up. Palitan ang YOUR_API_KEY sa mga sample sa ibaba ng sarili mong key.

Mag-sign in Mag-sign up

GET

/balance

Kunin ang balance

Ibinabalik ang kasalukuyang balance ng iyong account sa US dollar. Iisang balance ang gamit sa pagtanggap ng code at pagpapadala ng SMS.

Mga parameter

Walang parameter.

Sample na request

request

$ curl https://today-sms.com/api/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

Sample na response

response

{
  "balance": "42.5000",
  "currency": "USD"
}

Mga posibleng error

unauthorized	Walang API key o mali ito
not_allowed	Magbubukas ang API kapag pumasok na ang una mong top up
rate_limited	Masyadong maraming request sa loob ng 1 minuto

GET

/apps

Listahan ng app

Inililista ang mga app na may number ngayon. Ibinabalik ang app code, pangalan, pinakamababang presyo at bilang ng bansang may number.

Mga parameter

Walang parameter.

Sample na request

request

$ curl https://today-sms.com/api/v1/apps \
  -H "Authorization: Bearer YOUR_API_KEY"

Sample na response

response

[
  { "app": "telegram", "name": "Telegram", "from": "0.4515", "countries": 61 }
]

Mga posibleng error

unauthorized	Walang API key o mali ito
not_allowed	Magbubukas ang API kapag pumasok na ang una mong top up

GET

/prices?app=telegram

Mga bansa at presyo ng isang app

Ibinabalik ang mga bansa ng isang app, mula sa pinakamura. Kasama ang country code, ISO code, presyo at kung ilang number ang available ngayon.

Mga parameter

Pangalan	Uri	Kailangan	Paglalarawan
app	string	Kailangan	App code (ang app value mula sa GET /apps)

Sample na request

request

$ curl https://today-sms.com/api/v1/prices?app=telegram \
  -H "Authorization: Bearer YOUR_API_KEY"

Sample na response

response

[
  { "country": "indonesia", "iso": "id", "price": "0.4515", "stock": 702866 }
]

Mga posibleng error

bad_request	May kulang na kailangang value o mali ang format
unauthorized	Walang API key o mali ito

POST

/numbers

Bumili ng number

Bumibili ng number para sa app at bansang pinili mo. Kinukuha ang presyo sa iyong balance at naghihintay ng SMS ang number sa takdang oras. Kung mas matagal ang pagkumpirma ng number, nagbabalik ito ng 202 na may checking status.

Mga parameter

Pangalan	Uri	Kailangan	Paglalarawan
app	string	Kailangan	App code
country	string	Kailangan	Country code (ang country value mula sa GET /prices)

Sample na request

request

$ curl -X POST https://today-sms.com/api/v1/numbers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"app":"telegram","country":"indonesia"}'

Sample na response

response

{
  "id": "N-7K2M-QX4P-9D3A",
  "app": "telegram",
  "country": "indonesia",
  "phone": "+6281234567890",
  "price": "0.4515",
  "refunded": "0.0000",
  "status": "waiting",
  "expires_at": "2026-10-18T09:20:00.000Z",
  "sms": []
}

Mga posibleng error

bad_request	May kulang na kailangang value o mali ang format
not_enough_balance	Kulang ang balance, mag-top up muna
too_many_open	Masyadong maraming bukas na number, tapusin o i-cancel muna ang ilan
no_numbers	Walang number para sa app at bansang ito ngayon

GET

/numbers/{id}

Status ng number at SMS

Ibinabalik ang status ng number at ang bawat SMS na natanggap hanggang ngayon. Hiwalay ding ibinibigay ang verification code sa code.

Mga parameter

Pangalan	Uri	Kailangan	Paglalarawan
id	string	Kailangan	Ang id na nakuha mo sa pagbili ng number (nagsisimula sa N-)

Sample na request

request

$ curl https://today-sms.com/api/v1/numbers/N-7K2M-QX4P-9D3A \
  -H "Authorization: Bearer YOUR_API_KEY"

Sample na response

response

{
  "id": "N-7K2M-QX4P-9D3A",
  "status": "received",
  "sms": [
    { "code": "482913", "text": "Your code is 482913", "at": "2026-10-18T09:02:11.000Z" }
  ]
}

Mga posibleng error

not_found

Walang ganitong number o mensahe sa iyong account

POST

/numbers/{id}/cancel

I-cancel ang number

Kinakansela ang number na walang natanggap na SMS, mula 120 segundo pagkatapos bumili. Babalik sa iyong balance ang buong halaga.

Mga parameter

Pangalan	Uri	Kailangan	Paglalarawan
id	string	Kailangan	Number id (nagsisimula sa N-)

Sample na request

request

$ curl -X POST https://today-sms.com/api/v1/numbers/N-7K2M-QX4P-9D3A/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

Sample na response

response

{
  "id": "N-7K2M-QX4P-9D3A",
  "status": "canceled",
  "refunded": "0.4515"
}

Mga posibleng error

too_early	Puwedeng mag-cancel mula 120 segundo pagkatapos bumili
has_sms	Hindi na puwedeng i-cancel ang number na nakatanggap na ng SMS
try_again	Hindi pa kumpirmado ang cancellation, pakisubukan ulit pagkalipas ng 1 minuto
not_found	Walang ganitong number o mensahe sa iyong account

POST

/numbers/{id}/finish

Tapusin ang number

Isinasara ang number pagkatanggap mo ng code. Hindi na tumatanggap ng SMS ang saradong number.

Mga parameter

Pangalan	Uri	Kailangan	Paglalarawan
id	string	Kailangan	Number id (nagsisimula sa N-)

Sample na request

request

$ curl -X POST https://today-sms.com/api/v1/numbers/N-7K2M-QX4P-9D3A/finish \
  -H "Authorization: Bearer YOUR_API_KEY"

Sample na response

response

{
  "id": "N-7K2M-QX4P-9D3A",
  "status": "finished"
}

Mga posibleng error

not_found

Walang ganitong number o mensahe sa iyong account

GET

/messages/prices

Presyo ng SMS ayon sa bansa

Ibinabalik ang presyo bawat SMS sa bawat bansa para sa pagpapadala ng SMS. Kasama ang ISO code, country code at presyo bawat SMS (USD).

Mga parameter

Walang parameter.

Sample na request

request

$ curl https://today-sms.com/api/v1/messages/prices \
  -H "Authorization: Bearer YOUR_API_KEY"

Sample na response

response

[
  { "iso": "us", "dial": "1", "price": "0.0042" },
  { "iso": "gb", "dial": "44", "price": "0.0066" }
]

Mga posibleng error

unauthorized	Walang API key o mali ito
not_allowed	Magbubukas ang API kapag pumasok na ang una mong top up

POST

/messages

Magpadala ng SMS

Nagpapadala ng SMS sa listahan ng recipient kasama ang iyong mensahe. Hanggang 1,000 recipient bawat request, at isang mensahe lang ang natatanggap ng mga dobleng number. Idagdag ang at para i-schedule ang pagpapadala sa oras na iyon (UTC). Inilalaan mula sa iyong balance ang kabuuang gastos sa pagpapadala, at nire-refund sa iyong balance ang mga pumalyang bahagi.

Mga parameter

Pangalan	Uri	Kailangan	Paglalarawan
to	string[]	Kailangan	Listahan ng number sa international format (may + at country code), hanggang 1,000
text	string	Kailangan	Text ng mensahe. Isang SMS ang 160 GSM-7 o 70 Unicode character
at	string	Opsyonal	Naka-schedule na oras, ISO 8601 UTC (hal. 2026-10-18T10:00:00Z)
ref	string	Opsyonal	Sarili mong reference, tulad ng order number, hanggang 64 character

Sample na request

request

$ curl -X POST https://today-sms.com/api/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":["+14155550100","+447700900123"],"text":"Your code is 482913"}'

Sample na response

response

{
  "id": "m_7Q2K9X",
  "status": "queued",
  "recipients": 2,
  "parts": 1,
  "encoding": "GSM-7",
  "cost": "0.0136"
}

Mga posibleng error

bad_request	May kulang na kailangang value o mali ang format
too_many_recipients	Hanggang 1,000 recipient bawat request
not_enough_balance	Kulang ang balance, mag-top up muna
not_available	Malapit nang magbukas ang produktong ito. Hindi tinanggap ang request na ito at walang nabawas sa iyong balance

GET

/messages/{id}

Status ng pagpapadala at delivery report

Ibinabalik ang kabuuang status ng ipinadalang mensahe at delivery report para sa bawat recipient. Idinadagdag sa refunded ang halaga ng mga pumalyang bahagi.

Mga parameter

Pangalan	Uri	Kailangan	Paglalarawan
id	string	Kailangan	Ang id na nakuha mo sa pagpapadala

Sample na request

request

$ curl https://today-sms.com/api/v1/messages/m_7Q2K9X \
  -H "Authorization: Bearer YOUR_API_KEY"

Sample na response

response

{
  "id": "m_7Q2K9X",
  "status": "done",
  "cost": "0.0136",
  "refunded": "0.0083",
  "reports": [
    { "to": "+14155550100", "status": "delivered", "at": "2026-10-18T10:00:04Z" },
    { "to": "+447700900123", "status": "failed", "at": "2026-10-18T10:00:09Z" }
  ]
}

Mga posibleng error

not_found

Walang ganitong number o mensahe sa iyong account

POST

/messages/{id}/cancel

I-cancel ang scheduled send

Kinakansela ang scheduled send na hindi pa naipapadala. Babalik sa iyong balance ang buong halagang nakalaan.

Mga parameter

Pangalan	Uri	Kailangan	Paglalarawan
id	string	Kailangan	Message id

Sample na request

request

$ curl -X POST https://today-sms.com/api/v1/messages/m_7Q2K9X/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

Sample na response

response

{
  "id": "m_7Q2K9X",
  "status": "canceled",
  "refunded": "0.0136"
}

Mga posibleng error

too_late	Hindi na puwedeng i-cancel ang mensaheng nagsimula nang ipadala
not_found	Walang ganitong number o mensahe sa iyong account

Base URL

base

https://today-sms.com/api/v1

Authentication

Header Authorization: Bearer YOUR_API_KEY. Gawin ang key sa API key page kapag pumasok na ang una mong top up. Hanggang 300 request bawat minuto ang puwede mong gawin.

auth

$ curl https://today-sms.com/api/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

Format

JSON (UTF-8) ang request body at response. US dollar string na may hanggang 4 na decimal place ang mga halaga, at ISO 8601 UTC ang oras.

Status ng number

waiting	Handa na ang number, wala pang SMS
received	May dumating nang isa o higit pang SMS
finished	Isinara pagkatapos matanggap ang code
canceled	Kinansela, full refund
expired	Walang SMS sa takdang oras, full refund
checking	Sinusuri ang number, ire-refund kung walang number pagdating ng takdang oras

Status ng pagpapadala ng SMS

queued	Naghihintay maipadala
scheduled	Naka-schedule, ipapadala sa itinakdang oras
sending	Ipinapadala
done	May resulta na para sa lahat ng recipient
canceled	Kinansela ang schedule, full refund

Delivery status bawat recipient

pending	Hindi pa naipapasa sa carrier
sent	Naipasa na sa carrier
delivered	Naihatid na sa phone ng recipient
failed	Pumalya, nire-refund sa balance ang halaga ng bahaging iyon

Mga error

Nagbabalik ang error ng status code na hindi 2xx at JSON na may error value.

error

{
  "error": "not_enough_balance"
}

unauthorized	Walang API key o mali ito
not_allowed	Magbubukas ang API kapag pumasok na ang una mong top up
bad_request	May kulang na kailangang value o mali ang format
no_numbers	Walang number para sa app at bansang ito ngayon
not_enough_balance	Kulang ang balance, mag-top up muna
too_many_open	Masyadong maraming bukas na number, tapusin o i-cancel muna ang ilan
too_early	Puwedeng mag-cancel mula 120 segundo pagkatapos bumili
has_sms	Hindi na puwedeng i-cancel ang number na nakatanggap na ng SMS
not_found	Walang ganitong number o mensahe sa iyong account
try_again	Hindi pa kumpirmado ang cancellation, pakisubukan ulit pagkalipas ng 1 minuto
rate_limited	Masyadong maraming request sa loob ng 1 minuto
too_many_recipients	Hanggang 1,000 recipient bawat request
too_late	Hindi na puwedeng i-cancel ang mensaheng nagsimula nang ipadala
not_available	Malapit nang magbukas ang produktong ito. Hindi tinanggap ang request na ito at walang nabawas sa iyong balance