DTMF API

We have an API covering all functionality except voice. You can get your account balance, Bitcoin deposit addresses, and active numbers (including received SMS), generate Bitcoin deposit addresses, rent new numbers, set up forwarding and send SMS.

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

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": "cz-mobile",
    "type": "mobile",
    "name": "Czech Republic",
    "country_code": "cz",
    "sms_support": true,
    "voice_support": false,
    "setup_cost": 32093,
    "rental_cost_per_minute": 269,
    "cost_per_inbound_message": 601,
    "cost_per_inbound_call_minute": null
  },
  ...
]

Possible values for the type parameter are mobile and local.

List your numbers

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

[
  {
    "e164": "+441234567890",
    "group_id": "gb-mobile",
    "sms": true,
    "cost_per_minute": 13,
    "cost_per_inbound_message": 705,
    "assignment_start": "2017-05-22T16:07:25.049383",
    "sms_forwarded_to": null,
    "messages": [
      {
        "from": "+441234567890",
        "to": "+1234",
        "content": "a message I sent that was delivered successfully",
        "timestamp": "2017-05-22T16:07:25.049383",
        "success": true,
        "cost": 940
      },
      {
        "from": "+441234567890",
        "to": "+1234",
        "content": "a message I sent that has not been delivered yet",
        "timestamp": "2017-05-22T16:07:25.049383",
        "success": null,
        "cost": null
      },
      {
        "from": "+441234567890",
        "to": "+1234",
        "content": "a message I sent that could not be delivered",
        "timestamp": "2017-05-22T16:07:25.049383",
        "success": false,
        "cost": 0
      },
      {
        "from": "+1234",
        "to": "+441234567890",
        "content": "a message I received",
        "timestamp": "2017-05-22T16:07:25.049383",
        "success": true,
        "cost": 705
      }
    ]
  }
]

All costs are in satoshis.

Fetch a specific number

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

{
  "e164": "+441234567890",
  "group": "United Kingdom mobile",
  "sms": true,
  "cost_per_minute": 13,
  "cost_per_inbound_message": 705,
  "assignment_start": "2017-05-22T16:07:25.049383",
  "sms_forwarded_to": null,
  "messages": [
    {
      "from": "+441234567890",
      "to": "+1234",
      "content": "a message I sent that was delivered successfully",
      "timestamp": "2017-05-22T16:07:25.049383",
      "success": true,
      "cost": 940
    }
  ]
}

All costs are in satoshis.

Rent a new number

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

{"group_id": "gb-mobile"}
HTTP/2.0 204 No Content

Possible values for group_id can be found in the id field of the groups endpoint above.

After you receive the 204 successful response, you can poll the /api/v1/numbers endpoint ("List your numbers" above) to find the new number once it's assigned. It can take up to 10 seconds to be assigned.

End a number rental

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}

Get Bitcoin deposit addresses

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

[
  {
    "address": "1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  {
    "address": "1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
]

Generate a new Bitcoin deposit address

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

{"address": "1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}

Send an SMS

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

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