Using Phone.com API Services, Methods and URLs

The Phone.com API extends all of the features available in your Phone.com API Developer account, making them available in the following API services:

  • /calls — Incoming and outgoing phone calls
  • /sms — Incoming and outgoing SMS messages
  • /menus — Menus, which give your callers a list of options for routing their calls
  • /queues — Queues, which let you route callers to a group of phone numbers allocated to a call queue
  • /routes — Call Handling Rules (routes), which do the work of routing calls and SMS messages to a selected endpoint
  • /media — Greetings, hold music and other media objects that can be used on calls and to present menus
  • /batch — Batch functions, which allow you to retrieve and delete a defined group of phone calls or SMS messages
  • /contacts — Contacts in your Phone.com Address books (GET only)
  • /contact_groups — Contact groups in your Phone.com Address books (GET only)
  • /schedules — Schedules, which let you manage when specific phone numbers and extensions are available for routing (GET only)
  • /extensions — Extensions, which let you retrieve extensions assigned to your Phone.com phone numbers (GET only)

Using simple REST-based HTTP requests, you can create, list, update and delete these resources in your Phone.com account, making and receiving calls and SMS messages, or managing the menus, queues and rules needed to route calls.

In This Topic:


Which HTTP Methods Do You Support for Each Service?

Our API supports standard HTTP methods for making requests, including POST, GET, PUT and DELETE, which can be applied to collections and individual objects as shown in the tables below:

Important Notes: When you execute a DELETE on a collection of any kind (for example, DELETE /menus or DELETE /queues) you must supply the delete_all argument. We require this to avoid deleting an entire collection by accident. Also, X in the tables below denotes that the method is not available for that service.

Calls | SMS | Menus | Queues | Routes | Media | Batch | Contacts | Contact Groups | Schedules | Extensions

Calls

  POST GET PUT DELETE
/calls Create new call Retrieve list of calls X Hang up all active calls OR cancel all scheduled calls
/calls/UUID X Retrieve individual call Send additional commands to active call Hang up active call OR cancel scheduled call

SMS

  POST GET PUT DELETE
/sms Create new SMS message Retrieve list of SMS messages X Cancel all scheduled SMS messages
/sms/UUID X Retrieve individual SMS message Update individual SMS message Delete individual SMS message

Menus

  POST GET PUT DELETE
/menus Create new menu Retrieve list of menus X Delete all menus
/menus/UUID X Retrieve individual menu Update individual menu with new data Delete individual menu

Queues

  POST GET PUT DELETE
/queues Create new queue Retrieve list of queues X Delete all queues
/queues/UUID X Retrieve individual queue Update individual queue with new data Delete individual queue

Routes

  POST GET PUT DELETE
/routes Create new route Retrieve list of routes (called Call Handling Rules in your account) X Delete all routes
/routes/UUID X Retrieve individual route Update individual route with new data Delete individual route

Media

  POST GET PUT DELETE
/media Add new media object Retrieve list of media objects X Delete all media objects
/media/UUID X Retrieve individual media object Update individual media object Delete individual media object

Batch

  POST GET PUT DELETE
/batch X Retrieve list of batches X Delete all batches
/batch/UUID X Retrieve individual batch Update individual batch with new data Delete individual batch

Contacts

  POST GET PUT DELETE
/contacts X Retrieve list of contacts X X
/contacts/UUID X Retrieve individual contact X X

Contact Groups

  POST GET PUT DELETE
/contact_groups X Retrieve list of contact_groups X X
/contact_groups/UUID X Retrieve individual contact_groups X X

Schedules

  POST GET PUT DELETE
/schedules X Retrieve list of schedules X X
/schedules/UUID X Retrieve individual schedules X X

Extensions

  POST GET PUT DELETE
/extensions X Retrieve list of extensions X X
/extensions/UUID X Retrieve individual extensions X X

How Do I Make a REST Request?

Our API lets you create, manage and delete resources using simple HTTP requests that act on script-based commands.

For example, to make a phone call, you might create a script.txt file in which you define a set of call actions—say, to call a specific phone number and play a recorded message. Next, you will make an HTTP POST request, identifying that script file, and our API server will execute that POST using the phone number and actions defined in the script.

A sample request, created in cURL, might be structured as follows.

 curl -u <api key>:<api password> -basic -d @call.txt https://v1.api.phone.com/calls

For more information, see Making API Requests Using cURL.

When the actions in the script have been executed, our API server will respond to your request with an HTTP 200 OK code. If the request fails for some reason, our server will respond with an HTTP error response. For detailed information on forming HTTP requests, see Basic Phone.com API Requests and Responses.

Important: If you are not using a programming language that allows you to specify the method and HTTP headers in your call, you will need to use your HTTP request to make the call as follows:

  1. Make a POST request to: https://v1.api.phone.com/calls
  2. Use basic authentication.
  3. Use your API Key as the basic authentication username.
  4. Use your API Password as the basic authentication password.
  5. Send your JSON object in the body of the request.

For more information and a detailed example, see Get Started with Our API.

How Do I Handle Incoming Calls?

Likewise, you can configure your phone number to route incoming calls to your application webserver, on which you host a script file to process incoming calls. The location of the script is defined in the main URL you set when you configured your application.

When our network receives a call for your phone number, the Phone.com API server will send an HTTP request to the URL on your webserver, and the script processes your call.

For more information, and detailed examples, see Get Started with Our API and Basic Phone.com API Requests and Responses.

Learn More: