Usage Examples

Hello World

Let's start by testing our setup. This simple, unprotected route gives you an easy way to test network connectivity to the API. Open up a command prompt and enter the following command (without the $):

$ curl https://www.phoneburner.com/rest/1/tranquility

{
    "http_status": 200,
    "status": "success",
    "tranquility": 
    {
        "tranquility": 
        [
            
            {
                "meaning": "the quality or state of being tranquil; calm."
            }
        ],
        "total_results": 1,
        "page": 1,
        "page_size": 1,
        "total_pages": 1
    }
}

Not very interesting. To do anything interesting with the PhoneBurner API requires authentication.

Access Authenticated Route

First, lets try to access a protected resource without credentials.

$ curl https://www.phoneburner.com/rest/1/members/3288104

{
    "http_status": 401,
    "status": "error",
    "debug_codes": 
    [
        
        {
            "code": 40101,
            "reason": "Login Failure: Authorization Header required"
        }
    ]
}

For protected resources using OAuth, we need to add an Authorization header. For this example, we'll assume our access_token is EibGl9i8WNi0iI3a0He6PYg1Kntpzq8y3foSxQyg. Substitute your access_token.

To add this header with curl use the -H flag.

$ curl https://www.phoneburner.com/rest/1/members/ \
-H "Authorization: Bearer EibGl9i8WNi0iI3a0He6PYg1Kntpzq8y3foSxQyg"

{
        "http_status": 200,
        "status": "success",
        "members":
        {
                "total_results": 1,
                "members":
                [

                        {
                                "user_id": "1234567",
                                "username": "saulgoodman",
                                "first_name": "Saul",
                                "last_name": "Goodman",
                                "email_address": "[email protected]",
                                "date_added": "2013-01-17 17:12:13",
                                "phone": "9492181234",
                                "display_name": "Standard Account",
                                "billing_item_id": "131",
                                "subscription_status": "1",
                                "_link":
                                {
                                        "self":
                                        {
                                                "href": "\/rest\/1\/members\/1234567"
                                        }
                                }
                        }
                ],
                "page": 1,
                "page_size": 1,
                "total_pages": 1
        }

Note: \ is used in these examples to show using curl on multiple lines.

Example PUT

Now let's try to update some data using a PUT request.

With curl, use the -X flag (short for --request) to specify the HTTP verb. Use the -d flag (short for --data) to provide arguments.

$ curl https://www.phoneburner.com/rest/1/members/ \
            -H "Authorization: Bearer EibGl9i8WNi0iI3a0He6PYg1Kntpzq8y3foSxQyg" \
            -X PUT \
            -d "first_name=Jane"

{
    "http_status": 200,
    "status": "success",
    "members":
    {
            "members":
            {
                    "user_id": "1234567",
                    "username": "saulgoodman",
                    "first_name": "Jane",
                    "last_name": "Goodman",
                    "email_address": "[email protected]",
                    "date_added": "2013-01-17 17:12:13",
                    "phone": "9492181234",
                    "display_name": "Standard Account",
                    "billing_item_id": "131",
                    "subscription_status": "1"
            },
            "total_results": 1,
            "page": 1,
            "page_size": 1,
            "total_pages": 1
    }
}