Restcomm API - Profile

Profiles

Profiles allow to associate behavior configuration to specific Accounts or Organizations. Once a Profile is associated with such Entity, the next session (USSD/Voice/SMS) attempt related to that Entity will use the Profile configuration to tweak the service logic behavior.

During session creation the service logic will try to find the associated Profile based on this criteria, until a Profile is found:

  1. Profile associated to current Account

  2. Profile associated to parent Account

  3. Profile associated to related Organization

  4. Default Profile

The Default Profile is pre-provisioned in the system, and can’t be modified from the REST API. The Default Profile Sid is "PRae6e420f425248d6a26948c17a9e2acf"

Since the Profile configuration is expected to grow as required, the Profile entity is defined by a JSON schema, rather than regular properties, representing a document used as generic container.

The REST API will validate well-known contains of the document that are used by RestcommConnect during session handling logic. The rest of the document will not be validated, with the only constraint of a maximum size limitation of 10MB. This means the REST API consumer may use the Profile document to store/retrieve any kind of arbitrary information as long as the document is a valid JSON document.

The Profiles API allow different types of Profile to be provisioned. The Platform profile contains behavior only configurable by the SuperAdmin. While Subscriber profile maybe managed by the Account administrator. The different kind of profiles are denoted by Content-Type header by setting proper schema parameter. Where "rc-profile-schema.json" is for Platform profile, and "rc-subscriber-schema.json" is for Subscriber profile.

For the Platform profile, the Profiles REST API is only accessible by SuperAdmin credentials. With the exception of reading the associated Profile, where all Roles are allowed if the queried profile is associated with the requesting Account credentials.

For Subscriber profile, The Profiles REST API is only accessible by Account administrator. Where the created Profiles will only be linked to the corresponding account.

Profile Resource URI

/2012-04-24/Profiles/{ProfileSid}

Resource Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "id": "resource:/org/restcomm/connect/http/schemas/rc-profile-schema.json#",
    "additionalProperties": false,
    "type": "object",
    "properties": {
        "featureEnablement": {
            "$ref": "rc-feature-enablement-schema.json#/definitions/featureEnablement"
        }
    }
}

Supported Operations

HTTP GET. Returns the representation of a Profile resource. All roles are allowed.

Response Status

Status Description

200 OK

Body contains Profile JSon document

403 Forbidden

Only Super Admin is allowed to query Profiles

404 Not Found

Target Profile SID is missing

Response Headers

Header Description

Link

a link to the Profile schema with "rel" "describedBy"

Last-Modified

Date of last modification of the profile.

HTTP PUT. Modifies a Profile resource and returns the representation. The body of the request is expected to contain a JSON document compliant to the Profile schema.

Response Status

Status Description

200 OK

Modification performed. Body contains Profile JSon document

403 Forbidden

Only Super Admin is allowed to modify a Profile. DefaultProfile can’t be modified

404 Not Found

Target Profile SID is missing

400 Bad Request

Body contains a Profile not compliant with schema

HTTP DELETE

Removes an existing Profile, removing any existing association with Accounts/Organizations.

Response Status

Status Description

200 OK

Profile removed

403 Forbidden

Only Super Admin is allowed to remove. DefaultProfile can’t be deleted

404 Not Found

Target Profile SID is missing or Link is not found

HTTP LINK/UNLINK

Profile association operation maybe performed against a particular Account or Organization. This operation will use HTTP 1.1 LINK/UNLINK methods, and target resource should be populated in a Link header, using "related" as "rel" attribute. Only one Link header is supported. To associate a single Profile with multiple Accounts/Organizations, multiple requests will be required.

Request Headers

Header Description

Link

Contains an full URL to the Account/Organization that should be associated to the Profile

Response Status

Status Description

200 OK

Association established

403 Forbidden

Only Super Admin is allowed for the association operation

404 Not Found

Target Profile SID is missing or Link is not found

400 Bad Request

None or multiple Link header provided. Link with unsupported "rel".

Get information about the default profile.

curl -X GET  https://<accountSid>:<authToken>@cloud.restcomm.com/restcomm/2012-04-24/Profiles/PRae6e420f425248d6a26948c17a9e2acf

Add a new Platform Profile.

curl -X POST https://<accountSid>:<authToken>@cloud.restcomm.com/restcomm/2012-04-24/Profiles -H "Content-Type: application/instance+json;schema=https://cloud.restcomm.com/restcomm/2012-04-24/Profiles/schemas/rc-profile-schema.json" --data "@/path/to/filename"

Add a new Subscriber Profile.

curl -X POST https://<accountSid>:<authToken>@cloud.restcomm.com/restcomm/2012-04-24/Profiles -H 'Content-Type: application/instance+json;schema=https://cloud.restcomm.com/restcomm/2012-04-24/Profiles/schemas/rc-subscriber-schema.json' --data "@/path/to/filename"

Modify a Profile.

To update a Profile you need to provide the Profile SID

For example, update platform Profile using sid:

curl -X PUT https://<accountSid>:<authToken>@cloud.restcomm.com/restcomm/2012-04-24/Profiles/PRae6e420f425248d6a26948c17a9e2123 -H 'Content-Type: application/instance+json;schema=https://cloud.restcomm.com/restcomm/2012-04-24/Profiles/schemas/rc-profile-schema.json' --data "@/path/to/filename"

Getting information about a Profile.

curl -X GET  https://<accountSid>:<authToken>@cloud.restcomm.com/restcomm/2012-04-24/Profiles/PRae6e420f425248d6a26948c17a9e2123

The above command will print an output similar to the one below:

{
    "featureEnablement": {
        "DIDPurchase": {
            "allowedCountries": ["US", "CA"]
        },
        "subaccountsCreation": {
        },
        "outboundPSTN": {
          "allowedPrefixes": ["+971","971"],
          "blockedPrefixes": ["+1", "1"]},
        },
        "inboundPSTN": {
        },
        "outboundSMS": {
          "allowedPrefixes": ["+971","971"],
          "blockedPrefixes": ["+1", "1"]},
        },
        "inboundSMS": {
        }

    }
}

Link/Unlink a Profile to an Entity

To link a Profile to an Account

curl -X PUT  https://<accountSid>:<authToken>@cloud.restcomm.com/restcomm/2012-04-24/Profiles/PRae6e420f425248d6a26948c17a9e2123 -H "X-HTTP-Method-Override:LINK" -H "Link:<https://<accountSid>:<authToken>@cloud.restcomm.com/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf>;rel=related"

To unlink a Profile from an Account

curl -X PUT  https://<accountSid>:<authToken>@cloud.restcomm.com/restcomm/2012-04-24/Profiles/PRae6e420f425248d6a26948c17a9e2123 -H "X-HTTP-Method-Override:UNLINK" -H "Link:<https://<accountSid>:<authToken>@cloud.restcomm.com/restcomm/2012-04-24/Accounts/ACae6e420f425248d6a26948c17a9e2acf>;rel=related"

To link a Profile to an Organization

curl -X PUT https://<accountSid>:<authToken>@cloud.restcomm.com/restcomm/2012-04-24/Profiles/PRae6e420f425248d6a26948c17a9e2123 -H "X-HTTP-Method-Override:LINK" -H "Link:<https://<accountSid>:<authToken>@cloud.restcomm.com/restcomm/2012-04-24/Organizations/ORafbe225ad37541eba518a74248f0ac4c>;rel=related"

To unlink a Profile from an Organization

curl -X PUT https://<accountSid>:<authToken>@cloud.restcomm.com/restcomm/2012-04-24/Profiles/PRae6e420f425248d6a26948c17a9e2123 -H "X-HTTP-Method-Override:UNLINK" -H  "Link:<https://<accountSid>:<authToken>@cloud.restcomm.com/restcomm/2012-04-24/Organizations/ORafbe225ad37541eba518a74248f0ac4c>;rel=related"

A Subscriber profile may look as

{
    "multiprovider": {
        "outbound-voice": [
            {
                "proxy": [
                    {
                        "uri":"Uri",
                        "username":"String",
                        "password":"String",
                        "match":"Regex String",
                        "headers":[
                            {
                                "headerName":"String",
                                "key":"String",
                                "value":"String"
                            },
                            {...}
                        ]
                    },
                    {...}
                ]
            }
        ],
        "outbound-sms": [
            {"destination_network_id":"Integer"}
        ]

    }
}

Profile List Resource

  • Profile List Resource URI. /2012-04-24/Profiles

Supported Operations

HTTP GET. Returns the list representation of all the Profile resources.

The response will include a JSON document in the response body with this format

[{
	"uri": "https://<accountSid>:<authToken>@cloud.restcomm.com/restcomm/2012-04-24/Profiles/PRae6e420f425248d6a26948c17a9e2acf",
	"sid": "PRae6e420f425248d6a26948c17a9e2acf",
	"dateUpdated": 1516745449949,
	"dateCreated": 1516745449949
}]

HTTP POST. Creates a new Profile.The body of the request is expected to contain a JSON document compliant to the Profile schema.

Response Status

Status Description

201 Created

Profile created. Body contains Profile JSon document

403 Forbidden

Only Super Admin is allowed to modify/create a Profile

400 Bad Request

Body contains a Profile not compliant with schema

Response Headers

Header Description

Location

URL to new Profile created