Numbers

Add a number

POSThttps://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 send country or country_id with 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_id is not sent, the number goes to your newest list. If you have no lists, the API creates a list named My List.

Body params (form)

  • numberstringrequired

    Phone number of the contact. International format is recommended.

  • list_idintegeroptional

    ID of the list to add the number to. Default: your newest list.

  • countrystringoptional

    ISO 3166-1 alpha-2 country code of the number. Use it when the number is in local format.

  • country_idintegeroptional

    SMSEdge country ID. Used only when country is not sent.

  • verify_localintegeroptional

    1 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, 1

  • namestringoptional

    First name of the contact.

  • lnamestringoptional

    Last name of the contact.

  • emailstringoptional

    Email address of the contact.

  • birthdaystringoptional

    Date of birth as YYYY-MM-DD. A date in the future or more than 120 years ago is ignored.

  • genderstringoptional

    Gender of the contact. Accepts values such as m, male, mr, f, female, ms or mrs.

  • custom1stringoptional

    Custom 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.