API - Phonify

API Reference

Following the next steps you will be able to connect Phonify API and start sending SMS worldwide. If you already have an account with a billing method you will be able to start sending messages immediately.

The Phonify API is organised around Rest. We unify all behaviour into predictable, consistent results using recommended specifications like HTTP authentication, verbs and resources.

All verbs are performed as GET, POST, PUT (when updating) and DESTROY. All results are returned in jSON.

Authentication

All requests to Phonify API need to be authenticated using the API key provided to you.

You can find your current key visiting your Settings page.

There are two ways to authenticate easily. You can do it with a HTTP Basic Authentication header using your key as the username or you can also send it as api_key parameter in the request.

Arguments

api_key
string

Required

Authenticate easily sending your api key as an argument.

Example request

curl https://www.phonify.io/v1/messages \
-u KW9Aqn84ijagK6zseB5N:

When using cURL, use the -u flag to pass basic auth credentials (adding a colon after your API key prevents cURL from asking for a password).

Non cURL requests can send a HTTP Basic Authentication header like the example below.

Authorization: Basic KW9Aqn84ijagK6zseB5N

Errors

Phonify uses conventional HTTP response codes to indicate status of a request.

When a request is valid but does not complete as expected we return a 402 error and a errors JSON object is attached to the object including a collection of errors including type and title.

Errors Collection

Attributes

type string	The type of error. This is a unique string to help identify precisely the error.
title string	Indicates the error in readable plain english.

HTTP Status Code Summary

200	OK - Everything worked as expected.
400	Bad Request - Often missing a required parameter.
401	Unauthorized - No valid API key.
402	Request Failed - Parameters were valid but request failed.
404	Not Found - The requested item does not exist.
500, 502, 503, 504	Server errors - something went wrong.

Example Response

{
  "errors": [
    {
      "type": "missing_message",
      "title": "Message can be blank"
    }
  ]
}

Messages

All sent and received messaging share the same message object.

Attributes

id string
body string	An arbitrary string that contains the content of the message. Up to 160 characters.
to msisdn	MSISDN as defined in the E.164 international number format including the plus sign.
origin list
colspan: 2 table tr.visible td= link_to t("docs.api.show_child_attributes"), "#", class: 'child-attributes' td tr.hide td= link_to t("docs.api.hide_child_attributes"), "#", class: 'child-attributes' td tr.hide td \| number br/ small string td tr.hide td \| country br/ small string td tr.hide td \| provider br/ small= t("docs.api.optional") td
phone list
colspan: 2 table tr.visible td= link_to t("docs.api.show_child_attributes"), "#", class: 'child-attributes' td tr.hide td= link_to t("docs.api.hide_child_attributes"), "#", class: 'child-attributes' td tr.hide td \| number br/ small string td tr.hide td \| country br/ small string td tr.hide td \| provider br/ small= t("docs.api.optional") td
state string	Alfanumeric string containing the current state of the message, default is unconfirmed. Valid options are unconfirmed, sent and error.
created_at timestamp

Example Response

{
  "message":
  {
    "id": "ch_0UVaSlPypmXHLS",
    "body": "This is a message",
    "to": "+14560000000",
    "phone": {
      "id": "ch_0UVaSlPypmXHLS",
      "number": "4560000000",
      "country": "US",
      "provider": "att",
    },
    "state": "sent",
    "created_at": "2015-07-16T07:56:06.902Z"
  }
}

Sending a message

Arguments

to msisdn Required	MSISDN as defined in the E.164 international number format including the plus sign.
body string Required	An arbitrary string that contains the content of the message. Up to 160 characters.

Returns

Returns a collection of the message objects in JSON format.

Definition

POST https://www.phonify.io/v1/messages

Example request

curl -X POST "https://www.phonify.io/v1/messages" \
-u "KW9Aqn84ijagK6zseB5N:" \
-d to="+12025550186" \
-d body="My first message sent" \

Example Response

{
  "message":
  {
    "id": "ch_0UVaSlPypmXHLS",
    "body": "This is a message",
    "to": "+14560000000",
    "phone": {
      "id": "ch_0UVaSlPypmXHLS",
      "number": "4560000000",
      "country": "US",
      "provider": "att",
    },
    "state": "sent",
    "created_at": "2015-07-16T07:56:06.902Z"
  }
}

Retrieving a message

Arguments

id
string

Required

Identifier of message desired.

Returns

Returns a message object in JSON format.

Definition

GET https://www.phonify.io/v1/messages/{MESSAGE_ID}

Example request

curl "https://www.phonify.io/v1/messages/yiBSz5kCTq4tsRcKLe_t" \
-u KW9Aqn84ijagK6zseB5N:

Example Response

{
  "message":
  {
    "id": "ch_0UVaSlPypmXHLS",
    "body": "This is a message",
    "to": "+14560000000",
    "phone": {
      "id": "ch_0UVaSlPypmXHLS",
      "number": "4560000000",
      "country": "US",
      "provider": "att",
    },
    "state": "sent",
    "created_at": "2015-07-16T07:56:06.902Z"
  }
}

List all messages

Arguments

offset optional	default is 0
limit optional	default is 50 Maximum 1000

Returns

Returns a collection of most recent messages objects matching the given criteria in JSON format.