DTMF

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.

Come back to this page after signing in to manage your API tokens.

List possible number groups

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

[
  {
    "id": "nr-premium",
    "type": "premium",
    "name": "Nauru",
    "country_code": "nr",
    "sms_support": false,
    "voice_support": true,
    "setup_cost": 7000,
    "pristine_additional_cost": 0,
    "rental_cost_per_minute": 73,
    "cost_per_inbound_message": null,
    "cost_per_inbound_call_minute": 0,
    "earnings_per_inbound_call_minute": 5300,
    "premium_payout_terms": 45
  },
  ...
]

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

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", "pristine": false}
HTTP/2.0 200 OK

Setting pristine to true results in renting a number that has never been used before, for an additional cost (see the pricing page for details). This parameter is not relevant for premium numbers, and should be left set to false.

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

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

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