Restcomm API – Account

Accounts

Accounts and sub-accounts are useful for things like segmenting phone numbers and usage data for your users and controlling access to data.

Account Resource URI

/2012-04-24/Accounts/{AccountSid}

Resource Properties

Property Description

Sid

A string that uniquely identifies this account.

DateCreated

The date that this account was created.

DateUpdated

The date that this account was last updated.

FriendlyName

A description of this account, up to 64 characters long. By default the FriendlyName is your email address.

Role

The role of the account. Can be Administrator, Developer or ProvisioningAgent. Administrator has full access rights on all platform resources. Developer is like Administrator but is not allowed to manage sub-accounts. ProvisioningAgent is like Developer but is not allowed to read the actual text of SMS messages and cannot remove Recordings.

Status

The status of this account. Possible values are active, suspended, and closed.

AuthToken

The authorization token for this account. This should not be shared.

Uri

The URI for this account, relative to https://cloud.restcomm.com/restcomm.

Supported Operations

HTTP GET. Returns the representation of an Account resource, including the properties above.

  • Account Resource URI. /2012-04-24/Accounts/{EmailAddress}

Response Headers

Header Description

Link

a link to the effective Profile document with attribute "rel" set to "related"

HTTP POST. Creates a new Account resource and returns the representation, including the properties above. Below you will find a list of parameters.

Request Parameters

Parameter Description

FriendlyName

A description of this account, up to 64 characters long.

Status

The status of this account. Possible values are active, suspended, and closed.

Password

A password that will be used to generate the AuthToken for the new Account resource.

Role

The role for the new account. It must be one of Administrator, Developer or ProvisioningAgent (for more details please check the Resource Properties)

HTTP PUT. Modifies an Account resource and returns the representation, including the properties above. Below you will find a list of optional parameters.

Request Parameters

Parameter Description

FriendlyName

A description of this account, up to 64 characters long.

Status

The status of this account. Possible values are active, suspended, and closed.

Password

A password that will be used to generate the AuthToken for the new Account resource.

HTTP DELETE. DELETEs an Account resource and returns the representation, including the properties above.

The DELETE operation on an account will go through the following steps:

  • Will set state of the account and all sub-accounts of the accounts to Closed

  • Will remove account and sub-accounts resources

Check also [close-sub-accounts].

Below you will find a list of parameters.

Request Parameters

Parameter Description

Sid

A string that uniquely identifies this account.

Account Status transitions

When the Status of an account is modified by invoking the POST method, different business constraints will be applied:

  • The given Status will be applied to the given Account, and all the subaccount tree.

Uninitialized Account Status

The following conditions will be honored for an Uninitialized account:

  • When a new account is created, this Status is the default.

  • An Uninitialized account will reject its Credentials to be used for any REST API invocation.

  • An Uninitialized account will reject any Voice/SMS/USSD traffic. In addition, any client registration related to the account, will be rejected.

  • To activate an uninitialized account, a password reset is necessary.

Active Account Status

The following conditions will be honored for an Active account:

  • An Active account will allow its Credentials to be used for any REST API invocation.

  • An Active account will allow any Voice/SMS/USSD traffic. In addition, any client registration related to the account, will be allowed.

Suspended Account Status

The following conditions will be honored for a suspended account:

  • A Suspended account will reject its Credentials to be used for any REST API invocation.

  • A Suspended account will reject any Voice/SMS/USSD traffic. In addition, any client registration related to the accoutn, will be rejected.

  • A Suspended accounts may be reactivate by changing the Status to Active again.

Closed Account Status

The following conditions will be honored for a Closed account:

  • A Closed account will reject its Credentials to be used for any REST API invocation.

  • A Closed account will reject any Voice/SMS/USSD traffic. In addition, any client registration related to the accoutn, will be rejected.

  • When an account is closed, all related resources are removed.

  • Any modification over a Closed account will be rejected. This means a closed account can’t be reactivated

Account Migration to new Organization

Account Migration operation can be used to migrate a top level account to a new organization. In the process, all child accounts will also be migrated.

  • Account Migration Resource URI /2012-04-24/Accounts/migrate/{AccountSid}

  • Method HTTP POST

  • The operation is allowed for Super Admin only

  • The account to migrate must be a top level account (child of Super Admin)

Request Parameters

Parameter Description

Organization

The new Organization SID or Domain Name to move the account. Required

Response Status

Status Description

200 OK

Migration operation completed successfully

403 Forbidden

Only Super Admin is allowed for the migrate operation

412 Precondition Failed

Target Organization SID or Domain Name is missing

404 Not Found

Target Account SID is missing

400 Bad Request

Target Account is not a top level account or target account is already in the new organization

Get information about the default account.

curl -X GET https://cloud.restcomm.com/restcomm/2012-04-24/Accounts/#(account_sid).xml \
   -u "YourAccountSid:YourAuthToken"
curl -X GET  https://<primaryAccountSid>:<authToken>@cloud.restcomm.com/restcomm/2012-04-24/Accounts/<secondaryAccountSid>

Change default account password(AuthToken).

To update an account you need to provide the SID of the account or the email address of the account (make sure you url escape the @ sign of the email address)

For example, update password using account sid:

curl -X GET https://cloud.restcomm.com/restcomm/2012-04-24/Accounts/#(account_sid).xml?Password=NewPassword \
   -u "YourAccountSid:YourAuthToken"
curl -X PUT https://<primaryAccountSid>:<authToken>@cloud.restcomm.com/restcomm/2012-04-24/Accounts/<secondaryAccountSid> -d "Password=NewPassword"

And update password using email address of the account:

curl -X GET https://cloud.restcomm.com/restcomm/2012-04-24/Accounts/#(administrator%40company.com).xml?Password=NewPassword \
   -u "YourAccountSid:YourAuthToken"
curl -X PUT https://<primaryAccountSid>:<authToken>@cloud.restcomm.com/restcomm/2012-04-24/Accounts/administrator%40company.com -d "Password=NewPassword"
The above command uses the Account SID of the requester, and the one below uses the Email Account. Note the administrator%40company.com is used instead of administrator@company.com . This is because using curl on the bash terminal doesn’t parse the @ correctlyl. If you were to running on a browser, you can safely use the @ as the web browser will correctly handle it.

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

curl -X GET https://cloud.restcomm.com/restcomm/2012-04-24/Accounts/#(account_sid).xml \
   -u "YourAccountSid:YourAuthToken"
<RestcommResponse>
  <Account>
    <Sid><accountSid></Sid>
    <FriendlyName>Default Administrator Account</FriendlyName>
    <Status>active</Status>
    <Type>Full</Type>
    <DateCreated>2012-04-24T00:00:00.000-06:00</DateCreated>
    <DateUpdated>2012-04-24T00:00:00.000-06:00</DateUpdated>
    <AuthToken>77f8c12cc7b8f8423e5c38b035249166</AuthToken>
    <Uri>/2012-04-24/Accounts/<secondaryAccountSid></Uri>
    <SubresourceUris>
      <AvailablePhoneNumbers>/2012-04-24/Accounts/<secondaryAccountSid>/AvailablePhoneNumbers</AvailablePhoneNumbers>
      <Calls>/2012-04-24/Accounts/<secondaryAccountSid>/Calls</Calls>
      <Conferences>/2012-04-24/Accounts/<secondaryAccountSid>/Conferences</Conferences>
      <IncomingPhoneNumbers>/2012-04-24/Accounts/<secondaryAccountSid>/IncomingPhoneNumbers</IncomingPhoneNumbers>
      <Notifications>/2012-04-24/Accounts/<secondaryAccountSid>/Notifications</Notifications>
      <OutgoingCallerIds>/2012-04-24/Accounts/<secondaryAccountSid>/OutgoingCallerIds</OutgoingCallerIds>
      <Recordings>/2012-04-24/Accounts/<secondaryAccountSid>/Recordings</Recordings>
      <Sandbox>/2012-04-24/Accounts/<secondaryAccountSid>/Sandbox</Sandbox>
      <SMSMessages>/2012-04-24/Accounts/<secondaryAccountSid>/SMS/Messages</SMSMessages>
      <Transcriptions>/2012-04-24/Accounts/<secondaryAccountSid>/Transcriptions</Transcriptions>
    </SubresourceUris>
  </Account>

Account List Resource

  • Account List Resource URI. /2012-04-24/Accounts

Supported Operations

HTTP GET. Returns the list representation of all the Sub-Account resources for this Account, including the properties above.

HTTP POST. Creates a new Sub-Account and returns the representation of the Sub-Account resource, including the properties above. Below you will find a list of required and optional parameters.

=== Request Parameters

Parameter Description

EmailAddress(Required)

The email address to use for this account.

FriendlyName

A description of this account, up to 64 characters long. Default, is your email address.

Status

The status of this account. Default is active, possible values are active, suspended, and closed.

Password(Required)

A password that will be used to generate the AuthToken for the new Account resource.

Role(Required)

The security role that this Account resource will use. If no role is provided then the role of the account resource creating this will be inherited to the new Account resource and may compromise the system.

OrganizationSid

Sid of organization, in case you want to create this account under a different account than its parent account. By default each new account will inherit its parent’s organization. Please note only Super Admins have right to create an account under a different organization.

Sub-Accounts

You can read more about Sub-Accounts and Multi-tenancy HERE

curl -X GET https://<primaryAccountSid>:<AuthToken>@cloud.restcomm.com/restcomm/2012-04-24/Accounts/<secondaryAccountSid>/

Get a list of all current accounts

curl -X GET https://<primaryAccountSid>:<AuthToken>@cloud.restcomm.com/restcomm/2012-04-24/Accounts/

Here is an example of how to create a sub-account. The sub-account will inherit the same permissions has the Administrator’s account.

curl -X POST https://administrator%40company.com:<AuthToken>@cloud.restcomm.com/restcomm/2012-04-24/Accounts/ -d "FriendlyName=MySubAccount" -d "EmailAddress=test@telestax.com" -d "Password=restcomm"

Here is an example of creating an account under a specific organization.

curl -X POST https://<Sid>:<authToken>@<restcommAdress>/restcomm/2012-04-24/Accounts/ -d "FriendlyName=MySubAccount" -d "EmailAddress=test@telestax.com" -d "Password=restcomm" -d "OrganizationSid=<OrganizationSid>"

Supported Operations

the SID, Email and the AuthToken (see output below) of the sub-account can now be used instead of the Administrator’s account
<RestcommResponse>
  <Account>
    <Sid>AC3b8f0dd2e5026abde018446cbb3b185d</Sid>
    <FriendlyName>MySubAccount</FriendlyName>
    <Status>active</Status>
    <Type>Full</Type>
    <DateCreated>2013-10-16T09:22:28.708-06:00</DateCreated>
    <DateUpdated>2013-10-16T09:22:28.712-06:00</DateUpdated>
    <AuthToken>53134d7a9914e2b47c8435ebdb50ded3</AuthToken>
    <Uri>/2012-04-24/Accounts/AC3b8f0dd2e5026abde018446cbb3b185d</Uri>
    <SubresourceUris>
      <AvailablePhoneNumbers>/2012-04-24/Accounts/AC3b8f0dd2e5026abde018446cbb3b185d/AvailablePhoneNumbers</AvailablePhoneNumbers>
      <Calls>/2012-04-24/Accounts/AC3b8f0dd2e5026abde018446cbb3b185d/Calls</Calls>
      <Conferences>/2012-04-24/Accounts/AC3b8f0dd2e5026abde018446cbb3b185d/Conferences</Conferences>
      <IncomingPhoneNumbers>/2012-04-24/Accounts/AC3b8f0dd2e5026abde018446cbb3b185d/IncomingPhoneNumbers</IncomingPhoneNumbers>
      <Notifications>/2012-04-24/Accounts/AC3b8f0dd2e5026abde018446cbb3b185d/Notifications</Notifications>
      <OutgoingCallerIds>/2012-04-24/Accounts/AC3b8f0dd2e5026abde018446cbb3b185d/OutgoingCallerIds</OutgoingCallerIds>
      <Recordings>/2012-04-24/Accounts/AC3b8f0dd2e5026abde018446cbb3b185d/Recordings</Recordings>
      <Sandbox>/2012-04-24/Accounts/AC3b8f0dd2e5026abde018446cbb3b185d/Sandbox</Sandbox>
      <SMSMessages>/2012-04-24/Accounts/AC3b8f0dd2e5026abde018446cbb3b185d/SMS/Messages</SMSMessages>
      <Transcriptions>/2012-04-24/Accounts/AC3b8f0dd2e5026abde018446cbb3b185d/Transcriptions</Transcriptions>
    </SubresourceUris>
  </Account>

Close Sub-Accounts

JSON Account Closing
curl -X PUT https://<secondaryAccountSid>:PWD@cloud.restcomm.com/restcomm/2012-04-24/Accounts.json/<subAccountSid> -d "Status=closed"
XML Account Closing
curl -X PUT https://<secondaryAccountSid>:PWD@cloud.restcomm.com/restcomm/2012-04-24/Accounts/<subAccountSid> -d "Status=closed"

The command above will close an account permanently. When an account is closed access to the system through it is revoked and most of its resources are deleted. The actual account entity will remain present though.

Delete Sub-Accounts (deprecated)

XML Account Deletion
curl -X DELETE https://<secondaryAccountSid>:PWD@cloud.restcomm.com/restcomm/2012-04-24/Accounts/<Sub-Account-SID>
JSON Account Deletion
curl -X DELETE https://<secondaryAccountSid>:PWD@cloud.restcomm.com/restcomm/2012-04-24/Accounts.json/<Sub-Account-SID>.json
Account deletion has been deprecated from the REST API. Both of these methods will return HTTP 405. You will need to close the account instead.