Restcomm API – Organizations

Organizations

Organization are useful for segmenting accounts and providing restcomm functionalities on custom domain name.

Organization Api

Organization api will provide functionality to perform CRUD (create, read, update and delete) operations for organizations. Api is mainly responsible for communicating with configureable DNS hosting service provider (for example Route-53 or others) for making changes in record sets.

Organization Entity

Property

Description

sid

A string that uniquely identifies this organization.

domain_name

A custom DNS hostname that you create on Restcomm Cloud. It can accept traffic for an account. If anyone makes a SIP/HTTP request using that domain, say the SIP URI sip:alice@cloud.restcomm.com, it will route to Restcomm.

Total Length of domain_name can be upto 255 Characters. It can contain only letters, number and “-” aka hyphen sign.

date_created

The date that this organization was created.

date_updated

The date that this organization was last updated.

Status

Active or Closed.

Create new organization

Rationale

Rational to create a new organization pretty simple and described already, we want to onboard a new customer and provide them with their own domain and account on the platform.

/{Version}/Organizations/{domainName}

HTTP PUT to above Uri will create a new organization and returns the representation of the organization resource, including the properties above.

Uri Parameters

Property

Description

domainName

A custom DNS hostname that you create on Restcomm Cloud. It can accept traffic for an account. If anyone makes a SIP/HTTP request using that domain, say the SIP URI sip:alice@cloud.restcomm.com, it will route to Restcomm.

Total Length of domain_name can be upto 255 Characters. It can contain only letters, number and “-” aka hyphen sign.

Example 1. Add new organization with domain name "test" - Example

curl -X PUT "https://<accountSid>:<authToken>@cloud.restcomm.com/restcomm/2012-04-24/Organizations/test"

<Organization>
  <Sid>OR905d1b4e9d3045acb268f8d0fdf259ac</Sid>
  <DomainName>test.restcomm.com.</DomainName>
  <Status>active</Status>
  <DateCreated>Thu, 28 Sep 2017 16:11:39 +0000</DateCreated>
  <DateUpdated>Thu, 28 Sep 2017 16:11:39 +0000</DateUpdated>
</Organization>
Optional Request Parameters

Property

Description

HostedZoneId

ID of hosted zone on your DNS server, under which you want to create above domainName, if not provided system will use default configured one.

Example 2. Add new organization with domain name "test" under a specific hosted zone - Example

curl -X PUT "https://<accountSid>:<authToken>@cloud.restcomm.com/restcomm/2012-04-24/Organizations/test" -d "HostedZoneId=<myHostedZoneId>"

<Organization>
  <Sid>OR905d1b4e9d3045acb268f8d0fdf259ac</Sid>
  <DomainName>test.restcomm.com.</DomainName>
  <Status>active</Status>
  <DateCreated>Thu, 28 Sep 2017 16:11:39 +0000</DateCreated>
  <DateUpdated>Thu, 28 Sep 2017 16:11:39 +0000</DateUpdated>
</Organization>

Read organization

An account can read organization details if it belongs to that particular organization. Super admins can read all organizations.

Read organization resource will return organization entity provided above.

Single Resource URI

Will return single organization resource

/{Version}/Organizations(.json)/\{OrganizationSid}
Response Headers
Header Description

Link

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

Example 3. Read Organization Example

curl -X GET "https://{accountSid}:{authToken}@cloud.restcomm.com/restcomm/2012-04-24/Organizations/{OrganizationSid}"

<Organization>
  <Sid>OR905d1b4e9d3045acb268f8d0fdf259ac</Sid>
  <DomainName>test.restcomm.com.</DomainName>
  <Status>active</Status>
  <DateCreated>Thu, 28 Sep 2017 16:11:39 +0000</DateCreated>
  <DateUpdated>Thu, 28 Sep 2017 16:11:39 +0000</DateUpdated>
</Organization>
Example 4. Read Organization Json Example

curl -X GET "https://{accountSid}:{authToken}@cloud.restcomm.com/restcomm/2012-04-24/Organizations.json/{OrganizationSid}"

List Resource URI

Will return list of organizations

/{Version}/Organizations(.json)
List Filter

You can filter an organization list resource by providing following parameters.

Request Parameters

Property

Description

Status

Active or Closed.

Example 5. Read Organization List with filter Example

curl -X GET "https://{accountSid}:{authToken}@cloud.restcomm.com/restcomm/2012-04-24/Organizations/{OrganizationSid}.json" -d "Status=active"

Delete Organization

An existing Organization can be deleted using the REST API. Actually the Delete request will set the Organization to state Closed

/{Version}/Organizations/\{organizationSid}

HTTP DELETE to above Uri will delete an existing organization and will return the representation of the organization resource.

Uri Parameters

Property

Description

organizationSid

A string that uniquely identifies this organization.

Migrate Client Passwords

Rationale

This will encrypt all associated Clients passwords to a given encryption algorithm. At this moment, the target algorithm is hardcoded to MD5.

/\{Version}/Organizations/\{OrganizationSid}/Migrate

HTTP PUT to above Uri will encrypt all Client passwords and returns a list of Clients migrated.

Example 6. Migrate Organization Example

curl -X PUT "https://{accountSid}:{authToken}@cloud.restcomm.com/restcomm/2012-04-24/Organizations/{OrganizationSid}.json/Migrate"