DTMF.io API

The DTMF.io API supports sending and receiving SMS, as well as managing your phone numbers, buying phone numbers, and managing your account.

If you have any questions about our API or business use of DTMF.io services, please contact us.

There is a Python client library available on PyPI. Other client libraries are coming soon.

API requests must include authentication information in the form of an API token. Sign up to get API access.

Send an SMS

Important: Using the DTMF service to send spam SMS messages or phone calls may result in your account being deactivated.

The from field must be populated with an active phone number in your account that supports SMS – see Purchase a phone number below.

POST https://dtmf.io/api/v1/message
Authorization: Bearer [token]
Content-Type: application/json

{"from": "+1234", "to": "+5678", "content": "Hi!"}
HTTP/2.0 204 No Content

Fetch a specific number (inclding sent and received messages)

To receive asynchronous notification of inbound messages, you can set sms_forwarded_to to a webhook URL – see Forward all incoming SMS to a webhook below.

GET https://dtmf.io/api/v1/number?e164=%2B441234567890
Authorization: Bearer [token]
HTTP/2.0 200 OK
Content-Type: application/json

{
  "id": 1234,
  "e164": "+441234567890",
  "identifier": "",
  "group_id": "gb-mobile",
  "sms": true,
  "voice": true,
  "cost_per_month": "2.50",
  "cost_per_inbound_message": "0.01",
  "assignment_start": "2018-12-22T16:07:25.049383",
  "next_renewal": "2019-02-22T16:07:25.049383",
  "sms_forwarded_to": null,
  "calls": [
    {
      "id": 4567,
      "other_number": "+1234567890",
      "inbound": true,
      "start_timestamp": "2019-01-22T16:07:25.049383",
      "duration": 60,
      "status": "completed"
    }
  ],
  "messages": [
    {
      "id": 8901,
      "other_number": "+1234567890",
      "inbound": false,
      "content": "message content",
      "timestamp": "",
      "status": "delivered"
    }
  ]
}

List your numbers

GET https://dtmf.io/api/v1/numbers
Authorization: Bearer [token]
HTTP/2.0 200 OK
Content-Type: application/json

[
  {
    "id": 1234,
    "e164": "+441234567890",
    "identifier": "",
    "group_id": "gb-mobile",
    "sms": true,
    "voice": true,
    "cost_per_month": "2.50",
    "cost_per_inbound_message": "0.01",
    "assignment_start": "2018-12-22T16:07:25.049383",
    "next_renewal": "2019-02-22T16:07:25.049383",
    "sms_forwarded_to": null,
    "calls": [
      {
        "id": 4567,
        "other_number": "+1234567890",
        "inbound": true,
        "start_timestamp": "2019-01-22T16:07:25.049383",
        "duration": 60,
        "status": "completed"
      }
    ],
    "messages": [
      {
        "id": 8901,
        "other_number": "+1234567890",
        "inbound": false,
        "content": "message content",
        "timestamp": "",
        "status": "delivered"
      }
    ]
  }
]

All timestamps are UTC.

List possible number groups

GET https://dtmf.io/api/v1/groups?type=mobile
Authorization: Bearer [token]
HTTP/2.0 200 OK
Content-Type: application/json

[
  {
    "id": "us-mobile",
    "type": "mobile",
    "name": "United States",
    "country_code": "us",
    "sms_support": true,
    "voice_support": false,
    "rental_cost_per_month": "2.00",
    "cost_per_inbound_message": "0.00",
    "cost_per_inbound_call_minute": null,
    "affordable": true
  },
  ...
]

Possible values for the type parameter are mobile, local, tollfree and sim.

Purchase a phone number

POST https://dtmf.io/api/v1/numbers
Authorization: Bearer [token]
Content-Type: application/json

{"group_id": "gb-mobile"}
HTTP/2.0 200 OK
Content-Type: application/json

{
  "id": 1234,
  "e164": "+441234567890",
  "identifier": "",
  "group_id": "gb-mobile",
  "sms": true,
  "voice": true,
  "cost_per_month": "2.50",
  "cost_per_inbound_message": "0.01",
  "assignment_start": "2018-12-22T16:07:25.049383",
  "next_renewal": "2019-02-22T16:07:25.049383",
  "sms_forwarded_to": null,
  "calls": [],
  "messages": []
}

To find possible values for the group_id field, make a request to the List possible number groups endpoint above and take the id field of the response.

Delete a number

DELETE https://dtmf.io/api/v1/number?e164=%2B441234567890
Authorization: Bearer [token]
HTTP/2.0 204 No Content

Forward all incoming SMS to a webhook

POST https://dtmf.io/api/v1/number?e164=%2B441234567890
Authorization: Bearer [token]
Content-Type: application/json

{"sms_action": "webhook", "sms_forwarded_to": "https://example.com/my-sms-webhook"}
HTTP/2.0 204 No Content

When an SMS arrives to this number, we will do an HTTPS POST to the URL you supply.

The body of the POST request will be a JSON document with two keys: sender and body.

If you return 200 OK with non-empty plain text content, this content will be sent back to the sender of the message as a reply.

At present, replies longer than 160 characters will be truncated, and due to mobile network limitations, non-ASCII responses will be translated to ASCII (preserving as much meaning as possible).

A non-200 HTTP status code or an empty response body will result in no reply being sent.

Forward all incoming SMS to a mobile number

POST https://dtmf.io/api/v1/number?e164=%2B441234567890
Authorization: Bearer [token]
Content-Type: application/json

{"sms_action": "forward", "sms_forwarded_to": "+12345678901"}
HTTP/2.0 204 No Content

Clear forwarding

POST https://dtmf.io/api/v1/number?e164=%2B441234567890
Authorization: Bearer [token]
Content-Type: application/json

{"sms_action": null}
HTTP/2.0 204 No Content

Get account information (balance)

GET https://dtmf.io/api/v1/account
Authorization: Bearer [token]
HTTP/2.0 200 OK
Content-Type: application/json

{"balance": 6788242}