Phone Numbers

Last updated: Mar 4th, 2024

Phone Numbers

Search, Purchase and Configure your DIDs

Methods (calls)

Available Number

Retrieve a list of available phone numbers that can be purchased and used in your RooR account.


Endpoint: https://mapi.gynetix.com/prizm/api/sm/incomingphone/availablenumber.json


Parameters
Field Required Description
areacode Yes Specifies the area code for the returned list of available numbers.
Note: Only available for North American numbers.
Valid values:
Default value:
pagesize Optional The count of objects to return.
Note: Maximum pagesize should not exceed 100.
Valid values:
Default value: 1

Usage Example
curl -X POST 'https://mapi.gynetix.com/prizm/api/sm/incomingphone/availablenumber.json' -u '{AccountSid}:{AuthToken}' --data-urlencode 'areacode=949' --data-urlencode 'pagesize=5'

Sample Inline Response
{
    "RooR": {
        "ResponseStatus": 1,
        "PhoneCount": 5,
        "Page": 0,
        "PageSize": 5,
        "NumPages": 1,
        "Phones": {
            "Phone": [
                {
                    "VoiceEnabled": "true",
                    "SmsEnabled": "true",
                    "FriendlyName": "9496279064",
                    "PhoneNumber": "+19496279064",
                    "RateCenter": "LAGUNA BCH",
                    "MonthlyCost": "$1.5000",
                    "Region": "CA",
                    "Price": {
                        "InboundCallPrice": 0.0085,
                        "OutboundCallPrice": 0.0085,
                        "InboundSMSPrice": 0.004,
                        "OutboundSMSPrice": 0.0035,
                        "InboundMMSPrice": 0.01,
                        "OutboundMMSPrice": 0.01
                    },
                    "PerMinuteCost": "See Price",
                    "Rating": 1
                },
                {
                    "VoiceEnabled": "true",
                    "SmsEnabled": "true",
                    "FriendlyName": "9492814989",
                    "PhoneNumber": "+19492814989",
                    "RateCenter": "LAGUNA BCH",
                    "MonthlyCost": "$1.5000",
                    "Region": "CA",
                    "Price": {
                        "InboundCallPrice": 0.0085,
                        "OutboundCallPrice": 0.0085,
                        "InboundSMSPrice": 0.004,
                        "OutboundSMSPrice": 0.0035,
                        "InboundMMSPrice": 0.01,
                        "OutboundMMSPrice": 0.01
                    },
                    "PerMinuteCost": "See Price",
                    "Rating": 1
                },
                {
                    "VoiceEnabled": "true",
                    "SmsEnabled": "true",
                    "FriendlyName": "9495231302",
                    "PhoneNumber": "+19495231302",
                    "RateCenter": "SADLBK VLY",
                    "MonthlyCost": "$1.5000",
                    "Region": "CA",
                    "Price": {
                        "InboundCallPrice": 0.0085,
                        "OutboundCallPrice": 0.0085,
                        "InboundSMSPrice": 0.004,
                        "OutboundSMSPrice": 0.0035,
                        "InboundMMSPrice": 0.01,
                        "OutboundMMSPrice": 0.01
                    },
                    "PerMinuteCost": "See Price",
                    "Rating": 1
                },
                {
                    "VoiceEnabled": "true",
                    "SmsEnabled": "true",
                    "FriendlyName": "9496278929",
                    "PhoneNumber": "+19496278929",
                    "RateCenter": "LAGUNA BCH",
                    "MonthlyCost": "$1.5000",
                    "Region": "CA",
                    "Price": {
                        "InboundCallPrice": 0.0085,
                        "OutboundCallPrice": 0.0085,
                        "InboundSMSPrice": 0.004,
                        "OutboundSMSPrice": 0.0035,
                        "InboundMMSPrice": 0.01,
                        "OutboundMMSPrice": 0.01
                    },
                    "PerMinuteCost": "See Price",
                    "Rating": 1
                },
                {
                    "VoiceEnabled": "true",
                    "SmsEnabled": "true",
                    "FriendlyName": "9493546298",
                    "PhoneNumber": "+19493546298",
                    "RateCenter": "SADLBK VLY",
                    "MonthlyCost": "$1.5000",
                    "Region": "CA",
                    "Price": {
                        "InboundCallPrice": 0.0085,
                        "OutboundCallPrice": 0.0085,
                        "InboundSMSPrice": 0.004,
                        "OutboundSMSPrice": 0.0035,
                        "InboundMMSPrice": 0.01,
                        "OutboundMMSPrice": 0.01
                    },
                    "PerMinuteCost": "See Price",
                    "Rating": 1
                }
            ]
        }
    }
}

Release Number

Remove a purchased RooR number from your account.


Endpoint: https://mapi.gynetix.com/prizm/api/sm/incomingphone/releasenumber.json


Parameters
Field Required Description
PhoneNumber Yes A valid RooR 10-digit phone number (E.164 format).
Note:
Valid values:
Default value:

Usage Example
curl -X POST 'https://mapi.gynetix.com/prizm/api/sm/incomingphone/releasenumber.json' -u '{AccountSid}:{AuthToken}'

Sample Inline Response
{
    "RooR": {
        "ResponseStatus" => 1,
		"Status" => "success",
		"Message" => "Phone number +1npanxxnxxx has been released"
	}
}

Purchase Number

Purchase a phone number to be used with your RooR account.


Endpoint: https://mapi.gynetix.com/prizm/api/sm/incomingphone/buynumber.json


Parameters
Field Required Description
PhoneNumber Yes A valid RooR 10-digit phone number (E.164 format).
Note:
Valid values:
Default value:

Usage Example
curl -X POST 'https://mapi.gynetix.com/prizm/api/sm/incomingphone/buynumber.json' -u '{AccountSid}:{AuthToken}'

Sample Inline Response
{
    "RooR": {
        "ResponseStatus": 1,
        "BuyNumber": {
            "AccountSid": "{AccountSid}",
            "PhoneSid": "PHxxxxxxxxx",
            "Status": "success",
            "PhoneNumber": "+1npanxxnxxx",
            "AreaCode": "310",
            "Region": "CA",
            "DateCreated": "2024-03-15 14:19:12",
            "MonthlyCost": 1.50,
            "PerMinuteCost": 0.0125,
            "VoiceEnabled": "True",
            "SmsEnabled": "False"
        }
    }
}

Sample Callback Response
None

Update Number

Update properties on a RooR number that has been purchased. Refer to the parameters list for the list of properties that can be updated.


Endpoint: https://mapi.gynetix.com/prizm/api/sm/incomingphone/updatenumber.json


Parameters
Field Required Description
PhoneNumber Yes A valid RooR number (E.164 format).
Note:
Valid values:
Default value:
VoiceUrl Yes URL requested once the call connects
Note:
Valid values:
Default value:
FriendlyName Optional Phone number friendly name description
Note:
Valid values:
Default value:
VoiceMethod Optional Specifies the HTTP method used to request the required VoiceUrl.
Valid values: POST, GET
Default value: POST
VoiceFallbackUrl Optional URL requested if the voice URL is not available
Note:
Valid values:
Default value:
VoiceFallbackMethod Optional The HTTP method RooR will use when calling the VoiceFallbackUrl
Note:
Valid values: POST, GET
Default value: POST
HangupCallback Optional Callback url after a hangup occurs
Note:
Valid values:
Default value:
HangupCallbackMethod Optional The HTTP method RooR will use when calling the HangupCallback
Note:
Valid values: POST, GET
Default value: POST
HeartbeatUrl Optional URL that can be requested every 60 seconds during the call to notify of elapsed time
Note:
Valid values:
Default value:
HeartbeatMethod Optional The HTTP method RooR will use when calling the HeartbeatUrl
Note:
Valid values: POST, GET
Default value: POST
SmsUrl Optional URL requested when an SMS is received
Note: RooR will continue to call this URL on an interval until we get a 200 ok Response
Valid values:
Default value:
SmsMethod Optional The HTTP method RooR will use when calling the SmsUrl
Note:
Valid values: POST, GET
Default value: POST
SmsFallbackUrl Optional URL used if any errors occur during execution of InboundXML from an SMS or at initial request of the SmsUrl.
Note:
Valid values:
Default value:
SmsFallbackMethod Optional The HTTP method RooR will use when URL requested if the SmsUrl is not available.
Note:
Valid values: POST, GET
Default value: POST

Usage Example
curl -X POST 'https://mapi.gynetix.com/prizm/api/sm/incomingphone/updatenumber.json' -u '{AccountSid}:{AuthToken}' --data-urlencode 'FriendlyName=(npa) nxx - nxxx'

Sample Inline Response
{
    "RooR": {
        "ResponseStatus": 1,
        "Phone": {
            "AccountSid": "6a9ba49f-d96d-44c1-845f-46b637b87065",
            "PhoneSid": "PH7caff6b7-f596-436f-ad26-8dd1e2e25956",
            "FriendlyName": "(npa) nxx - nxxx",
            "PhoneNumber": "+1npanxxnxxx",
            "VoiceUrl": "https:\/\/...",
            "VoiceMethod": "POST",
            "VoiceFallbackUrl": null,
            "VoiceFallbackMethod": "POST",
            "DateCreated": "02\/21\/2024 14:17:36",
            "DateofRenewal": "03\/22\/2024 14:17:36",
            "CostofRenewal": "0.3500",
            "State": "",
            "SmsRequestUrl": "https:\/\...",
            "SmsRequestMethod": "POST",
            "SmsFallbackUrl": null,
            "SmsFallbackMethod": "POST",
            "HeartbeatUrl": null,
            "HeartbeatMethod": "POST",
            "HangupCallback": "https:\/\...",
            "HangupCallbackMethod": "POST",
            "VoiceEnable": "true",
            "SmsEnable": "true",
            "ApiVersion": "sm"
        }
    }
}

List Numbers

Retrieve a list of purchased phones numbers associated with your RooR account.


Endpoint: https://mapi.gynetix.com/prizm/api/sm/incomingphone/listnumber.json


Parameters
Field Required Description
Page Optional Which page of the overall response will be returned.
Note: Page indexing starts at 1.
Valid values:
Default value: 1
PageSize Optional Which page of the overall response will be returned.
Note: Page indexing starts at 1.
Valid values:
Default value: 10

Usage Example
curl -X GET 'https://mapi.gynetix.com/prizm/api/sm/incomingphone/listnumber.json' -u '{AccountSid}:{AuthToken}'

Sample Inline Response
{
    "RooR": {
        "ResponseStatus": 1,
        "PhoneCount": 1,
        "Page": 1,
        "Pagesize": 10,
        "Phones": {
            "Phone": [
                {
                    "AccountSid": "{AccountSid}",
                    "PhoneSid": "PH7caf...",
                    "FriendlyName": "npanxxnxxx",
                    "PhoneNumber": "+1npanxxnxxx",
                    "VoiceUrl": "https:\/\/...",
                    "VoiceMethod": "POST",
                    "VoiceFallbackUrl": null,
                    "VoiceFallbackMethod": "POST",
                    "DateCreated": "02\/21\/2024 14:17:36",
                    "DateofRenewal": "03\/22\/2024 14:17:36",
                    "CostofRenewal": "0.3500",
                    "State": "",
                    "SmsRequestUrl": "https:\/\/...",
                    "SmsRequestMethod": "POST",
                    "SmsFallbackUrl": null,
                    "SmsFallbackMethod": "POST",
                    "HeartbeatUrl": null,
                    "HeartbeatMethod": "POST",
                    "HangupCallback": "https:\/\/...",
                    "HangupCallbackMethod": "POST",
                    "VoiceEnable": "true",
                    "SmsEnable": "true",
                    "Disabled": false,
                    "Rating": 2,
                    "CampaignId": null,
                    "AvailableCampaigns": [],
                    "ApiVersion": "sm"
                }
            ]
        }
    }
}

Inbound Calls

In order to connect inbound calls you must configure the VoiceUrl using the updatenumber end point. This Url should return InboundXML telling RooR how to handle the call.