Introduction

Version 1.3.0

The RingPlus API is a new, powerful set of tools for interacting with mobile phones and the cellular network. The API is built around REST and allows you access virtually all aspects of your account - you can lookup call detail records, including inbound or outbound usage data on SMS, Data, MMS, and international minutes. You can change your phone number, or swap your current device with another, check your voicemail, and many more features that have traditionally been locked away behind carrier walls. We're excited to help bust open the silos!

Since the API is based on REST, interacting with it is very easy - you can even do it from your browser. We implement the OAuth2 protocol to help garuantee the security of the your account data, and will soon allow you to set permissions on what parts of your account an application can access.

We are proponents of SemVer and while this API is living and breathing, you can write your applications knowing we won't break existing functionality.

These documents will be updated frequently as we continue to add services to the RingPlus API.

Libraries

The RingPlus API does not yet have any native libraries to use but this is something we are actively working on! If you'd like to help develop an API library for your language of choice, connect with us on Github: github.com/ringplus. We'd love to hear from you and help you in any way possible.

Authentication

All authentication into the RingPlus API must been done using OAuth 2.0 over HTTPS. It allows applications to access user details without needing their password, allows limiting access to only what the application requires, and can be revoked by users at any time.

All application developers need to register their application by visiting the Application tab on their Settings page. A registered application is assigned a Client ID and Client Secret. Your Client Secret should not be shared with anyone.

Using your Client ID and Secret, you will be able to get an Authorization Token for a user, and make requests to the API for their data.

Retreive Authorization Code

The first step to getting an Authorization Token is to redirect the user to request RingPlus access.

Parameters
client_id
required
The Client ID you received from RingPlus when you registered your application.
response_type
required
Type of authorization flow. Use: code
redirect_uri
optional
Callback URL where you want users to be sent after authorization.
Route
GET https://my.ringplus.net/oauth/authorize
Example Redirect URL
https://my.ringplus.net/oauth/authorize?client_id=123412341234&response_type=code&redirect_uri=https://yourapp.com/oauth/callback

If the user has authorized your request, RingPlus redirects back to your site, via the redirect_uri, with a temporary code in the code parameter. This code must now be exchanged for an access token.

Retreive Access Token
Parameters
grant_type
required
Set as authorization_code
client_id
required
The Client ID you received from RingPlus when you registered your application.
client_secret
required
The Client Secret you received from RingPlus when you registered your application.
code
required
The code you received in the response to step 1.
Route
POST https://my.ringplus.net/oauth/token
Example Request
$ curl https://my.ringplus.net/oauth/token \
  -X POST \
  -d grant_type=authorization_code \
  -d client_id=123412341234 \
  -d client_secret=432143214321 \
  -d code=1234567890
Example Response
{
  "access_token": "de6780bc506a0446309bd9362820eedbe1c5c4f9dd350e54",
  "token_type": "bearer",
  "expires_in": 7200,
  "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544"
}
Making Authenticated Requests

The access token you receive allows you to make requests on the API on the user's behalf. Simply include it in each API request as access_token.

https://api.ringplus.net/account/1?access_token=...
Refreshing Access Token

As a security measure, access tokens expire after a given time period but you can easily refresh a token without requiring the user to re-authorize your application.

Parameters
grant_type
required
Set as refresh_token
client_id
required
The Client ID you received from RingPlus when you registered your application.
client_secret
required
The Client Secret you received from RingPlus when you registered your application.
refresh_token
required
The refresh token of the expired access token.
Route
POST https://my.ringplus.net/oauth/token
Example Request
$ curl https://my.ringplus.net/oauth/token \
  -X POST \
  -d grant_type=refresh_token \
  -d client_id=123412341234 \
  -d client_secret=432143214321 \
  -d refresh_token=abcd12348392048020938023
Example Response
{
  "access_token": "de6780bc506a0446309bd9362820eedbe1c5c4f9dd350e54",
  "token_type": "bearer",
  "expires_in": 7200,
  "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544"
}

Versioning

The API uses semantic versioning and you can request a specific major version of the API through the Accept header in each request. All changes within a major version are backwards compatible.

Specify which version of the API you want to request against by sending the value: application/vnd.ringplus.vMAJOR, where MAJOR is the API version number.

For example, the following would query the version 1 API:

application/vnd.ringplus.v1

It is highly recommended you send the version number of the API you intend to work with as no header will default to the latest version of the API.

Example Request
$ curl https://api.ringplus.net/users \
  -H "Accept: application/vnd.ringplus.v1"

Scopes

Scopes are a type of permission for OAuth authentication. They allow you to limit what types of actions your application can do with a user's authorization. This can be helpful as you can request only the permissions your application needs, making users trust your application more, rather than giving you full access.

More information about scopes and how to use them is coming soon.

Errors

The API uses standard HTTP response codes to indicate the succuess or failure of API requests and to give some indication of what went wrong.

In general:

  • codes in the 2xx range indicate success
  • codes in the 4xx range indicate an error based on information received by the API (either a required parameter was missing, or the request failed to complete successfully)
  • codes in the 5xx range indicate an error on the API (which we will then be notified of)

If more information about an error is available, some responses include an error_message field which includes more information about what went wrong.

A full listing of HTTP status codes and their meanings can be found at http://httpstatus.es

Common Response Codes
200 OK
201 Created
202 Accepted
204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
422 Unprocessable Entity

Dates and Times

All dates and times returned by the API are in UTC formatted as ISO 8601. This format should make it easily parseable by most languages.

Any date and times sent to the API that do not contain timezone information will be interpretted as UTC.

Timezone information for each user is stored in their Account.

Example Date Format
Current datetime is: 2014-04-19T01:59:59Z

Errata

PUT and PATCH

Due to backwards compatibliity, this version of the API uses the PUT verb as a replacement for PATCH semantics. PUT requests are interpreted as partial updates to a resource. PUT to a non-existent resource will respond in a 404 response.

The API will support PUT and PATCH properly in a future version.


API Methods


Accounts

Accounts are the object that encapsulate a mobile device on a plan. They belong to a User and are a base model for many other routes on the API.

List a User's Accounts

A list of accounts belonging to a specific User

Scopes
public
Parameters
name
optional
The name of the account to filter by. Currently does not partial or full text search.
email_address
optional
The email_address of the account to filter by. Currently does not partial or full text search.
phone_number
optional
The phone_number of the account to filter by. Currently does not partial or full text search.
device_esn
optional
The active device_esn of the account to filter by. Currently does not partial or full text search.
device_iccid
optional
The active device_iccid of the account to filter by. Currently does not partial or full text search.
page
optional
Default: 1
Which page of the paged results to return.
per_page
optional
Default: 25
How many results to return per page.
Response

The details of the requested account.

Route
GET https://api.ringplus.net/users/{USER ID}/accounts
Example Request
$ curl https://api.ringplus.net/users/1/accounts \
  -d access_token=...
  -d device_esn=1234567890ABCDEF
Example Response
Status: 200 OK
{
  "accounts":[
    {
      "id":1,
      "name":"Name",
      "balance":10.1234,
      "status": "live",
      "registered_on":"2013-05-01T06:23:27Z",
      "user_id":1,
      "phone_number":"15551234567",
      "msid":"1234"
    },
    { ... }
  ],
  "meta":
  {
    "count": 2
  }
}
List all Accounts

List all accounts the user has access to.

Scopes
public
Parameters
name
optional
The name of the account to filter by. Currently does not partial or full text search.
email_address
optional
The email_address of the account to filter by. Currently does not partial or full text search.
phone_number
optional
The phone_number of the account to filter by. Currently does not partial or full text search.
device_esn
optional
The active device_esn of the account to filter by. Currently does not partial or full text search.
device_iccid
optional
The active device_iccid of the account to filter by. Currently does not partial or full text search.
page
optional
Default: 1
Which page of the paged results to return.
per_page
optional
Default: 25
How many results to return per page.
Response

The details of the requested account.

Route
GET https://api.ringplus.net/accounts
Example Request
$ curl https://api.ringplus.net/accounts \
  -d access_token=...
  -d device_esn=1234567890ABCDEF
Example Response
Status: 200 OK
{
  "accounts":[
    {
      "id":1,
      "name":"Name",
      "balance":10.1234,
      "status": "live",
      "registered_on":"2013-05-01T06:23:27Z",
      "user_id":1,
      "phone_number":"15551234567",
      "msid":"1234"
    },
    { ... }
  ],
  "meta":
  {
    "count": 2
  }
}
Get a Specific Account

Get a specific account's information.

Scopes
public
Parameters

None

Response

The details of the requested account.

Route
GET https://api.ringplus.net/accounts/{ACCOUNT ID}
Example Request
$ curl https://api.ringplus.net/accounts/1 \
  -d access_token=...
Example Response
Status: 200 OK
{
  "account":
  {
    "id":1,
    "name":"Name",
    "balance":10.1234,
    "status": "live",
    "registered_on":"2013-05-01T06:23:27Z",
    "user_id":1,
    "active_phone_number":"15551234567",
    "msid":"1234",
    "active_device":
    {
      "id":1,
      "device_esn":"1234567890abcdef",
      "device_iccid":"9292929292929292929",
      "model_name":"Name",
      "master_subsidy_lock": "1234"
    },
    "voicemail_box":
    {
      "id":1,
      "pin":5555,
      "seconds_until_activate":30,
      "send_email":true,
      "send_sms":false,
      "preferred_language":"en-us",
      "voicemail_message_count":2
    },
    "account_services": [
      {
        "id": 1,
        "name": "Block International Dialing"
      },
      {
        "id": 2,
        "name": "LTE Data"
      },
      { ... }
    ],
    "active_billing_subscriptions": [
      {
        "id":1,
        "name":"Plan or Promo Name - Package Name",
        "start_date":"2013-05-01T06:23:27Z",
        "end_date":"2013-05-01T06:23:27Z",
        "text_usage_in_count": 12,
        "sms_usage_in_count": 12,
        "mms_usage_in_count": 7,
        "voice_usage_in_mins": 34,
        "data_usage_in_bytes": 3829502,
        "inbound_domestic_sms_count":6,
        "outbound_domestic_sms_count":0,
        "inbound_international_sms_count":0,
        "outbound_international_sms_count":0,
        "inbound_domestic_mms_count":6,
        "outbound_domestic_mms_count":0,
        "inbound_international_mms_count":0,
        "outbound_international_mms_count":0,
        "inbound_domestic_voice_count":34,
        "outbound_domestic_voice_count":0,
        "inbound_international_voice_count":0,
        "outbound_international_voice_count":0,
        "data_2g_count":0,
        "data_3g_count":3829502,
        "data_wimax_count":0,
        "data_lte_count":0,
        "recurs_until":"2013-05-01T06:23:27Z",
        "next_billed_at":"2013-05-01T06:23:27Z",
      }
    ]
  }
}
Update an Account

Updates an account's information.

Scopes
manage
Parameters
name
optional
Update the name of an account
Response

None

Route
PUT https://api.ringplus.net/accounts/{ACCOUNT ID}
Example Request
$ curl https://api.ringplus.net/accounts/1 \
  -X PUT
  -d access_token=...
  -d "account[name]=John Smith"
Example Response
204 No-Content

Account Registrations

Account Registrations allow you to add new mobile accounts to your User; allowing you to have many different mobile accounts under the same login.

Registering and creating new accounts can take time depending on the device and network conditions. The Account Registration request routes provide a non-blocking way of sending registrations. Requests that pass initial validation will return with with a request ID which can be queried to find out the status of the registration. The status of the registraiton will display whether the request has been completed and whether it was successful.

Submit Account Registration Request

Creates a registration request to associate a user with a mobile device.

Scopes
request
Parameters
name
required
A name for this account.
billing_plan_id
required
The ID of the billing plan to use for this account.
device_esn
required
The mobile device's ESN number, usually an alpha numeric string.
device_iccid
optional
The mobile device's ICCID, or SIM card serial number.
credit_card_id
required
An ID of a credit card already associated with the User.
Response

A request object to monitor the status of the registration process.

Route
POST https://api.ringplus.net/users/{USER ID}/account_registration_requests
Example Request
$ curl https://api.ringplus.net/users/1/account_registration_requests \
  -X POST
  -d access_token=...
  -d "account_registration_request[name]=John Smith"
  -d account_registration_request[billing_plan_id]=1
  -d account_registration_request[device_esn]=600ABCDEF123
  -d account_registration_request[credit_card_id]=1
Example Responses
Status: 202 Accepted
Location: https://api.ringplus.net/account_registration_requests/1
{
  "account_registration_request": {
    "id":1,
    "status":"queued",
    "requested_on":"2013-08-01T06:23:272"
  }
}
Get an Account Registration Request Status

Shows the status of an account registration request.

Scopes
public
Parameters

None

Response

The request object including its status.

Route
GET https://api.ringplus.net/account_registration_requests/{REQUEST ID}
Example Request
$ curl https://api.ringplus.net/account_registration_requests/1 \
  -d access_token=...
Example Responses
Status: 200 OK
{
  "account_registration_request": {
    "id":1,
    "status":"queued",
    "requested_on":"2013-08-01T06:23:272"
  }
}
{
  "account_registration_request": {
    "id":1,
    "status":"in_progress",
    "requested_on":"2013-08-01T06:23:272"
  }
}
{
  "account_registration_request": {
    "id":1,
    "status":"completed"
    "successful":"true"
    "account":{
      "id":1,
      "name":"Name",
      "balance":0,
      "status": "live",
      "active_phone_number":"15551234567",
      "registered_on":"2013-05-01T06:23:27Z",
      "expires_on":"2013-08-01T06:23:272"
     }
  }
}

Change Device Requests

Change device requsts allow you to change the phsyical device associated with an account.

Registering new devices can take time depending on the device and network conditions. The request route provide a non-blocking way of sending the request. Requests that pass initial validation will return with with a request ID which can be queried to find out the status of the request. The status of the request will display whether the request has been completed and whether it was successful.

Submit Change Device Request

Creates a change device request to change the phsical device associated with an Account.

Scopes
request
Parameters
new_model_name
required
Model name of the device.
new_esn
required
The new device's ESN number.
new_iccid
optional
The mobile device's ICCID, or SIM card serial number. This is optional, only if the device does not have an ICCID. If the device has an ICCID and it is not included in the request, the request will likely fail.
Response

A request object to monitor the status of the request process.

Route
POST https://api.ringplus.net/accounts/{ACCOUNT ID}/device_change_requests
Example Request
$ curl https://api.ringplus.net/accounts/1/device_change_requests \
  -X POST
  -d access_token=...
  -d "device_change_request[new_model_name]=Galaxy S3"
  -d device_change_request[device_esn]=600ABCDEF123
Example Responses
Status: 202 Accepted
Location: https://api.ringplus.net/device_change_requests/1
{
  "device_change_request": {
    "id":1,
    "status":"queued",
    "requested_on":"2013-08-01T06:23:272"
  }
}
Get a Device Change Request Status

Shows the status of an device change request.

Scopes
public
Parameters

None

Response

The request object including its status.

Route
GET https://api.ringplus.net/device_change_requests/{REQUEST ID}
Example Request
$ curl https://api.ringplus.net/device_change_requests/1 \
  -d access_token=...
Example Responses
Status: 200 OK
{
  "device_change_request": {
    "id":1,
    "status":"queued",
    "requested_on":"2013-08-01T06:23:272"
  }
}
{
  "device_change_request": {
    "id":1,
    "status":"in_progress",
    "requested_on":"2013-08-01T06:23:272"
  }
}
{
  "device_change_request": {
    "id": 1,
    "status": "completed",
    "successful": true,
    "requested_on": "2013-06-04T01:51:24Z"
  }
}
{
  "device_change_request": {
    "id": 1,
    "status": "completed",
    "successful": false,
    "error_message": "Reason for failure",
    "requested_on": "2013-06-04T01:51:24Z"
  }
}

Change Phone Number Requests

Change phone number requsts allow you to change the phone number on an account. Change Phone Number requests do not allow you choose your new phone number, you will be assigned an available number. To change phone numbers to a specific phone number, see Port Requests.

The request route provide a non-blocking way of sending the request. Requests that pass initial validation will return with with a request ID which can be queried to find out the status of the request. The status of the request will display whether the request has been completed and whether it was successful.

Submit Change Phone Number Request

Creates a request to change the phone number associated with an Account.

Scopes
request
Parameters

None

Response

A request object to monitor the status of the request process.

Route
POST https://api.ringplus.net/accounts/{ACCOUNT ID}/phone_number_change_requests
Example Request
$ curl https://api.ringplus.net/accounts/1/phone_number_change_requests \
  -X POST
  -d access_token=...
Example Responses
Status: 202 Accepted
Location: https://api.ringplus.net/phone_number_change_requests/1
{
  "device_change_request": {
    "id":1,
    "status":"queued",
    "new_phone_number": null,
    "requested_on":"2013-08-01T06:23:272"
  }
}
Get a Phone Number Change Request Status

Shows the status of an phone number change request.

Scopes
public
Parameters

None

Response

The request object including its status.

Route
GET https://api.ringplus.net/phone_number_change_requests/{REQUEST ID}
Example Request
$ curl https://api.ringplus.net/phone_number_change_requests/1 \
  -d access_token=...
Example Responses
Status: 200 OK
{
  "phone_number_change_request": {
    "id":1,
    "status":"queued",
    "requested_on":"2013-08-01T06:23:272"
  }
}
{
  "phone_number_change_request": {
    "id":1,
    "status":"in_progress",
    "requested_on":"2013-08-01T06:23:272"
  }
}
{
  "phone_number_change_request": {
    "id": 1,
    "status": "completed",
    "new_phone_number": "15551234567",
    "successful": true,
    "requested_on": "2013-06-04T01:51:24Z"
  }
}
{
  "phone_number_change_request": {
    "id": 1,
    "status": "completed",
    "new_phone_number": null,
    "successful": false,
    "error_message": "Reason for failure",
    "requested_on": "2013-06-04T01:51:24Z"
  }
}

Enforced Carrier Services

Enforced Carrier Services are services offered at the carrier level that have been enforced on an account. These are not the only services that may be active on a given account, but are sure to override any other policies.

List an Account's Enforced Carrier Services

A list of applied enforced carrier services belonging to a specific Account

Scopes
public
Parameters
page
optional
Default: 1
Which page of the paged results to return.
per_page
optional
Default: 25
How many results to return per page.
Response

The list of carrier services.

Route
GET https://api.ringplus.net/accounts/{ACCOUNT ID}/enforced_carrier_services
Example Request
$ curl https://api.ringplus.net/accounts/1/enforced_carrier_services \
  -d access_token=...
Example Response
Status: 200 OK
{
  "enforced_carrier_services":[
    {
      "id":1,
      "account_id":1,
      "action":"activate",
      "carrier_service": {
        "id":1,
        "name":"Name"
      }
    },
    { ... }
  ],
  "meta":
  {
    "count": 2
  }
}

Phone Calls

Call detail records for all voice calls made on a specific account.

Get a List of Phone Calls

Returns a specific account's paged phone call details.

Scopes
public
Parameters
start_date
optional
Return only records occurring after this date.
end_date
optional
Return only records occurring before this date.
per_page
optional (default: 25)
How many results to return per request.
page
optional (default: 1)
Which page of results to view.
Response

Paged list of phone call objects.

Route
GET https://api.ringplus.net/accounts/{ACCOUNT ID}/phone_calls
Example Request
$ curl https://api.ringplus.net/accounts/1/phone_calls \
  -d access_token=...
Example Response
Status: 200 OK
{
  "phone_calls":[
    {
      "originating_phone_number":"15557654321",
      "destination_phone_number":"15551234567",
      "direction":"inbound",
      "status":"completed",
      "start_time":"2013-05-01T06:23:27Z",
      "cost":0.0121,
      "total_time_in_ms":60000,
      "account_id":1
    },
    { ... }
  ],
  "meta":
  {
    "count": 2
  }
}

Phone Texts

Call detail records for all text messages (both SMS and MMS) made on a specific account.

Get a List of Phone Texts

Returns a specific account's paged phone text details.

Scopes
public
Parameters
start_date
optional
Return only records occurring after this date.
end_date
optional
Return only records occurring before this date.
per_page
optional (default: 25)
How many results to return per request.
page
optional (default: 1)
Which page of results to view.
Response

Paged list of phone text objects.

Route
GET https://api.ringplus.net/accounts/{ACCOUNT ID}/phone_texts
Example Request
$ curl https://api.ringplus.net/accounts/1/phone_texts \
  -d access_token=...
Example Response
Status: 200 OK
{
  "phone_texts":[
    {
      "originating_phone_number":"15557654321",
      "destination_phone_number":"15551234567",
      "direction":"inbound",
      "occurred_at":"2013-05-01T06:23:27Z",
      "cost":0.0130,
      "mode":"mms",
      "account_id":1
    },
    { ... }
  ],
  "meta":
  {
    "count": 2
  }
}

Phone Data

Call detail records for all data used on a specific account.

Get a List of Phone Data Usage

Returns a specific account's paged phone data details.

Scopes
public
Parameters
start_date
optional
Return only records occurring after this date.
end_date
optional
Return only records occurring before this date.
per_page
optional (default: 25)
How many results to return per request.
page
optional (default: 1)
Which page of results to view.
Response

Paged list of phone data objects.

Route
GET https://api.ringplus.net/accounts/{ACCOUNT ID}/phone_data
Example Request
$ curl https://api.ringplus.net/accounts/1/phone_data \
  -d access_token=...
Example Response
Status: 200 OK
{
  "phone_data":[
    {
      "mode":"3g",
      "quantity_in_bytes":3529302,
      "occurred_at":"2013-05-01T06:23:27Z",
      "account_id":1
    },
    { ... }
  ],
  "meta":
  {
    "count": 2
  }
}

Port Requests

Port Requests allow you to move your old number from a previous provider to your RingPlus account. Requests can take anywhere between a couple minutes to a couple weeks to complete, depending on your previous subscriber.

A port request goes through several stages:

  • When a request is created, it will automatically prevalidate the request.
  • If prevalidation is successful, the port request stays prevalidated until a request to submit it is received via the API.
  • Once submitted, the request will come back as accepted, meaning the previous mobile provider will begin the transfer of the phone number.
  • Eventually the request will be set as successful, meaning the phone number transfer has been received and completed.
  • The request can be set as failed if the port request has an error with the other carrier. A failed port request can either be updated and resubmitted, or cancelled via another PUT.

The request route provide a non-blocking way of sending the request. Requests that pass initial validation will return with with a request ID which can be queried to find out the status of the request. The status of the request will display whether the request has been completed and whether it was successful.

Create a Port Request

Creates a request to port your old phone number to your current account.

Scopes
request
Parameters
requested_phone_number
required
The phone number you want to transfer.
account_number
required
Account number from the previous mobile provider.
first_name
required
First name of the account holder from the previous mobile provider.
last_name
required
Last name of the account holder from the previous mobile provider.
address_street
required
Street address on file from the previous mobile provider.
address_locality
required
City on file from the previous mobile provider.
address_region
required
State on file from the previous mobile provider.
address_postal_code
required
Postal code on file from the previous mobile provider.
authorized_by
required
Name of person authorizing this request, usually the account holder's name.
pin_or_password
optional
Some mobile providers require you to include your previous account's PIN or password.
Response

A request object to monitor the status of the request process.

Route
POST https://api.ringplus.net/accounts/{ACCOUNT ID}/port_requests
Example Request
$ curl https://api.ringplus.net/accounts/1/port_requests \
  -X POST
  -d access_token=...
  -d port_request[requested_phone_number]=5551234567
  -d port_request[account_number]=1234abcd
  -d port_request[first_name]=John
  -d port_request[last_name]=Smith
  -d "port_request[address_street]=1234 Street Ave."
  -d port_request[address_locality]=LA
  -d port_request[address_region]=CA
  -d port_request[address_postal_code]=90210
  -d "port_request[authorized_by]=John Smith"
Example Responses
Status: 202 Accepted
Location: https://api.ringplus.net/port_requests/1
{
  "port_request": {
    "id": 1,
    "status": "queued",
    "current_phone_number": "15551112222",
    "requested_phone_number": "5551234567",
    "first_name": "John",
    "last_name": "Smith",
    "address_street": "1234 Street Ave.",
    "address_locality": "LA",
    "address_region": "CA",
    "address_postal_code": "90210",
    "account_number": "123412345678",
    "authorized_by": "John Smith",
    "new_phone_number": null,
    "new_msid": null,
    "port_in_id": null,
    "old_csa": null,
    "old_service_provider": null,
    "requested_on": "2013-07-26T00:27:41Z"
  }
}
Submit a Port Request

Submits a prevalidated port request.

Scopes
request
Parameters

None

Response

A request object to monitor the status of the request process.

Route
PUT https://api.ringplus.net/port_requests/{REQUEST ID}/submit
Example Request
$ curl https://api.ringplus.net/port_requests/1/submit \
  -X PUT
  -d access_token=...
Example Responses
Status: 202 Accepted
Location: https://api.ringplus.net/port_requests/1
{
  "port_request": {
    "id": 1,
    "status": "prevalidated",
    "current_phone_number": "15551112222",
    "requested_phone_number": "5551234567",
    "first_name": "John",
    "last_name": "Smith",
    "address_street": "1234 Street Ave.",
    "address_locality": "LA",
    "address_region": "CA",
    "address_postal_code": "90210",
    "account_number": "123412345678",
    "authorized_by": "John Smith",
    "new_phone_number": null,
    "new_msid": null,
    "port_in_id": null,
    "old_csa": "OLDCSA",
    "old_service_provider": "Sprint",
    "requested_on": "2013-07-26T00:27:41Z"
  }
}
Get a Port Request Status

Shows the status of an port request.

Scopes
public
Parameters

None

Response

The request object including its status.

Route
GET https://api.ringplus.net/port_requests/{REQUEST ID}
Example Request
$ curl https://api.ringplus.net/port_requests/1 \
  -d access_token=...
Example Responses
Status: 200 OK
{
  "port_request": {
    "id": 1,
    "status": "prevalidated",
    "current_phone_number": "15551112222",
    "requested_phone_number": "5551234567",
    "first_name": "John",
    "last_name": "Smith",
    "address_street": "1234 Street Ave.",
    "address_locality": "LA",
    "address_region": "CA",
    "address_postal_code": "90210",
    "account_number": "123412345678",
    "authorized_by": "John Smith",
    "new_phone_number": null,
    "new_msid": null,
    "port_in_id": null,
    "old_csa": "OLDCSA",
    "old_service_provider": "Sprint",
    "requested_on": "2013-07-26T00:27:41Z"
  }
}
{
  "port_request": {
    "id": 1,
    "status": "successful",
    "current_phone_number": "15551112222",
    "requested_phone_number": "5551234567",
    "first_name": "John",
    "last_name": "Smith",
    "address_street": "1234 Street Ave.",
    "address_locality": "LA",
    "address_region": "CA",
    "address_postal_code": "90210",
    "account_number": "123412345678",
    "authorized_by": "John Smith",
    "new_phone_number": "15551234567",
    "new_msid": "12345",
    "port_in_id": "6789",
    "old_csa": "OLDCSA",
    "old_service_provider": "Sprint",
    "requested_on": "2013-07-26T00:27:41Z"
  }
}
{
  "port_request": {
    "id": 1,
    "status": "failed",
    "current_phone_number": "15551112222",
    "requested_phone_number": "5551234567",
    "first_name": "John",
    "last_name": "Smith",
    "address_street": "1234 Street Ave.",
    "address_locality": "LA",
    "address_region": "CA",
    "address_postal_code": "90210",
    "account_number": "123412345678",
    "authorized_by": "John Smith",
    "new_phone_number": null,
    "new_msid": null,
    "port_in_id": null,
    "old_csa": "OLDCSA",
    "old_service_provider": "Sprint",
    "error_message": "Reason for failure",
    "requested_on": "2013-07-26T00:27:41Z"
  }
}
Resubmit a Port Request

Updates and resubmits a port request. Only failed requests can be resubmitted, and you must submit at least one change to the provided information to be able to resubmit.

Scopes
request
Parameters
account_number
optional
Account number from the previous mobile provider.
first_name
optional
First name of the account holder from the previous mobile provider.
last_name
optional
Last name of the account holder from the previous mobile provider.
address_street
optional
Street address on file from the previous mobile provider.
address_locality
optional
City on file from the previous mobile provider.
address_region
optional
State on file from the previous mobile provider.
address_postal_code
optional
Postal code on file from the previous mobile provider.
pin_or_password
optional
Some mobile providers require you to include your previous account's PIN or password.
Response

A request object to monitor the status of the request process.

Route
PUT https://api.ringplus.net/port_requests/{REQUEST ID}
Example Request
$ curl https://api.ringplus.net/port_requests/1 \
  -X PUT
  -d access_token=...
  -d port_request[first_name]="New First Name"
  -d port_request[address_postal_code]=90211
Example Responses
Status: 202 Accepted
Location: https://api.ringplus.net/port_requests/1
{
  "port_request": {
    "id": 1,
    "status": "submitted",
    "current_phone_number": "15551112222",
    "requested_phone_number": "5551234567",
    "first_name": "John",
    "last_name": "Smith",
    "address_street": "1234 Street Ave.",
    "address_locality": "LA",
    "address_region": "CA",
    "address_postal_code": "90210",
    "account_number": "123412345678",
    "authorized_by": "John Smith",
    "new_phone_number": null,
    "new_msid": null,
    "port_in_id": null,
    "old_csa": null,
    "old_service_provider": null,
    "requested_on": "2013-07-26T00:27:41Z"
  }
}
Cancel a Port Request

Cancels a failed port request.

Scopes
request
Parameters
reason_for_cancel
required
Why is this port request being cancelled.
Response

A request object to monitor the status of the request process.

Route
PUT https://api.ringplus.net/port_requests/{REQUEST ID}/cancel
Example Request
$ curl https://api.ringplus.net/port_requests/1/cancel \
  -X PUT
  -d access_token=...
  -d port_request[reason_for_cancel]="Reason"
Example Responses
Status: 202 Accepted
Location: https://api.ringplus.net/port_requests/1
{
  "port_request": {
    "id": 1,
    "status": "cancelled",
    "current_phone_number": "15551112222",
    "requested_phone_number": "5551234567",
    "first_name": "John",
    "last_name": "Smith",
    "address_street": "1234 Street Ave.",
    "address_locality": "LA",
    "address_region": "CA",
    "address_postal_code": "90210",
    "account_number": "123412345678",
    "authorized_by": "John Smith",
    "new_phone_number": null,
    "new_msid": null,
    "port_in_id": null,
    "old_csa": "OLDCSA",
    "old_service_provider": "Sprint",
    "requested_on": "2013-07-26T00:27:41Z"
  }
}

Users

User accounts are the base object representing a user on the system. You can view and update various properties of users, and use User IDs to query many other objects in the system.

Get a Specific User

Returns a specific user's details.

Scopes
public
Parameters

None

Response

User details of the requested account.

Route
GET https://api.ringplus.net/users/{USER ID}
Example Request
$ curl https://api.ringplus.net/users/1 \
  -d access_token=...
Example Response
Status: 200 OK
{
  "user":
  {
    "id":1,
    "email":"email@address.com",
    "role":"user",
    "registered_on":"2013-05-01T06:23:27Z",
    "preferred_language":"en-us",
    "accounts":[
      {
        "id":1,
        "name":"Name",
        "balance":0,
        "status": "live",
        "phone_number":"15551234567",
        "msid":"1234"
      }
    ],
    "shipping_addresses":[
      {
        "id":1,
        "name":"Name",
        "street":"1234 Street Ave",
        "locality":"LA",
        "region":"CA",
        "postal_code":"90210"
      }
    ]
  }
}
List all Users

Lists all Users you have access to.

Scopes
public
Parameters
email_address
optional
Filters users by matching the email address.
per_page
optional (default: 25)
How many results to return per request.
page
optional (default: 1)
Which page of results to view.
Response

Returns a list of the User's you have access to.

Route
GET https://api.ringplus.net/users
Example Request
$ curl https://api.ringplus.net/users \
  -d access_token=...
Example Response
Status: 200 OK
{
  "users":[
    {
      "id":1,
      "email":"email@address.com",
      "role":"user",
      "registered_on":"2013-05-01T06:23:27Z",
      "preferred_language":"en-us",
      "accounts":[
        {
          "id":1,
          "name":"Name",
          "balance":0,
          "status": "live",
          "phone_number":"15551234567",
          "msid":"1234"
        }
      ],
      "shipping_addresses":[
        {
          "id":1,
          "name":"Name",
          "street":"1234 Street Ave",
          "locality":"LA",
          "region":"CA",
          "postal_code":"90210"
        }
      ]
    },
    { ... }
  ],
  "meta":
    {
      "count": 2
    }
}
Update a User

Updates a User's account.

Scopes
manage
Parameters
email
optional
Value to set as new email address
password
optional
Value to set as current password
Response

None

Route
PUT https://api.ringplus.net/users/{USER ID}
Example Request
$ curl https://api.ringplus.net/users/1 \
  -X PUT
  -d access_token=...
  -d user[email]=email@address.com
Example Response
204 No-Content

Voicemail Messages

Everytime a voicemail is left on an account, a voicemail message is created. These include a path to the sound file as well as a transcription of the message left if one could be created.

List all Voicemail Messages

Returns a specific account's paged voicemail messages.

Scopes
voicemail
Parameters
only_new
optional
Return only voicemails that haven't been marked as archived.
per_page
optional (default: 25)
How many results to return per request.
page
optional (default: 1)
Which page of results to view.
Response

Paged list of voicemail message objects.

Route
GET https://api.ringplus.net/voicemail_boxes/{VOICEMAIL BOX ID}/voicemail_messages
Example Request
$ curl https://api.ringplus.net/voicemail_boxes/1/voicemail_messages \
  -d access_token=...
Example Response
Status: 200 OK
{
  "voicemail_messages":[
    {
      "id":1,
      "sent_by":"15551234567",
      "archived": false,
      "transcription":"Transcription Text",
      "recording_url":"https://assets.ringplus.net/path/to/voicemail.wav"
    },
    { ... }
  ],
  "meta":
  {
    "count": 2
  }
}
Delete a Voicemail Message

Deletes a voicemail message.

Scopes
voicemail
Parameters

None

Response

None

Route
DELETE https://api.ringplus.net/voicemail_messages/{VOICEMAIL MESSAGE ID}
Example Request
$ curl https://api.ringplus.net/voicemail_messages/1 \
  -X DELETE
  -d access_token=...
Example Response
Status: 204 No Content

Changelog


1.3.0

Released: February 10th, 2014

  • [Feature] New route for cancelling submitted or failed port requests.
  • [Feature] New route for updating and resubmitting failed port requests.
1.2.1

Released: January 10th, 2014

  • [Fix] Updated documentation to include the action parameter for enforced carrier services, to allow activating and deactivating services.
1.2.0

Released: December 16th, 2013

  • [Feature] A new route to see what carrier services are enforced on an account.
  • [Feature] In the Account show JSON, we previously returned separated arrays of carrier_restrictions and carrier_features . We now return a full list under carrier_services which includes both arrays.
  • [Deprecation] The two arrays carrier_features and carrier_restrictions in the Account JSON are deprecated. It is the application's descision whether certain services are restrictions or features, so the API now provides a single array of all services applied to an account.
1.1.0

Released: November 13th, 2013

  • [Feature] The Accounts response has two new attributes: sms_usage_in_count and mms_usage_in_count
  • [Deprecatation] The attribute text_usage_in_count returned within the Accounts response has been renamed to sms_usage_in_count . text_usage_in_count will continue to be available until the 2.0.0 release, but it is recommeded to use sms_usage_in_count instead.
1.0.0

Released: October 16th, 2013

  • Initial version released to the public.