Numbers
Add a number
https://api.smsedge.com/v1/numbers/create/Adds one phone number (a contact) to a list, with optional name and custom fields.
- The API removes all characters that are not digits from
number. Send the number in international format, or sendcountryorcountry_idwith a local number. - If the number is already in the list, the API returns the existing contact and does not change it.
- If the number was deleted from the list before, the API restores it.
- When
list_idis not sent, the number goes to your newest list. If you have no lists, the API creates a list namedMy List.
Body params (form)
numberstringrequiredPhone number of the contact. International format is recommended.
list_idintegeroptionalID of the list to add the number to. Default: your newest list.
countrystringoptionalISO 3166-1 alpha-2 country code of the number. Use it when the number is in local format.
country_idintegeroptionalSMSEdge country ID. Used only when country is not sent.
verify_localintegeroptional1 checks that the number is a mobile number. A number that fails gets the status bad. 0 skips the check and marks the number good.
Default:
1Values:0,1namestringoptionalFirst name of the contact.
lnamestringoptionalLast name of the contact.
emailstringoptionalEmail address of the contact.
birthdaystringoptionalDate of birth as YYYY-MM-DD. A date in the future or more than 120 years ago is ignored.
genderstringoptionalGender of the contact. Accepts values such as m, male, mr, f, female, ms or mrs.
custom1stringoptionalCustom field 1. The fields custom2 to custom5 work the same way. HTML tags are removed.
Responses
- 200The number is in the list.
- 400The number is missing or not valid, the country is not known, or the list was not found.
curl -X POST "https://api.smsedge.com/v1/numbers/create/" \
-H "X-API-KEY: YOUR_API_KEY" \
--data-urlencode "number=447700900123"[
{
"success": true,
"data": {
"id": 63264825474,
"number": "447700900123",
"number_normalized": "447700900123",
"list_id": 347617,
"country_id": 225,
"country_name": "United Kingdom",
"created": "2026-11-16 14:20:11",
"name": "Jane",
"lname": "Smith",
"email": "jane@example.com",
"birthday": "1990-05-21",
"gender": "F",
"custom1": "VIP",
"status": "good",
"type": "Free",
"device": null,
"city": null
},
"errors": [],
"response": {
"code": 200,
"description": "OK",
"date": "2026-11-16 14:20:11"
},
"api": {
"version": "v1",
"module": "numbers",
"function": "create"
},
"user": {
"id": 12345
}
}
]All requests need your API key in the X-API-KEY header. See Authentication.