Part I: Creating an Enterprise with Restricted Access
1. Retrieve the SBC Gateways
If creating an Enterprise that would use the calling services (either PBX or Trunk), retrieve the sbcGateways. Take note of thesbcGatewayId of the SBC gateways to assign to the enterprise.
Method: GET
Path: /reseller/getAvailableSBCGatewayRegionsByResellerId/{resellerId}
API response
[
{
"sbcGatewayId": 5678,
"sbcGatewayRegion": "US-East"
}
]2. Retrieve the PBX Types
In addition, if creating an enterprise that would use PBX, retrieve the PBX types available. Take note of the id of the PBX Types to assign to this enterprise.
Method: GET
Path: /pbx/getPBXTypesByResellerId?resellerId=<resellerId>
API Response
[
{
"id": 1234,
"pbxName": "Example PBX",
"pbxLabel": "Example PBX Label",
"isDefault": true,
"isDisabled": false,
"hostingType": "Cloud"
}
]3. Create the enterprise
Method: POST
Path: /reseller/newEnterprise
Request Body
Below is the JSON request body for creating a new enterprise. Required fields are highlighted and explained in detail.
{
"allowExternalNumbers": true,
"billingReferences": [
"string"
],
"canAddExtensions": true,
"canResellerManageEnterpriseProvisioning": true,
"countryName": "string",
"entConfigInfos": [
{
"configDetails": {
"contexts": "string",
"defValue": "string",
"ent": true,
"id": 0,
"labelName": "string",
"labelPopover": "string",
"masterReseller": true,
"name": "string",
"partner": true,
"reseller": true,
"system": true,
"type": "string"
},
"entityId": 0,
"id": 0,
"value": "string"
}
],
"enterpriseId": 0,
"enterpriseName": "string",
"federated": true,
"federationDomain": "string",
"pbxId": [0],
"pbxMOH": true,
"registeredBy": "string",
"resellerId": 0,
"restrictAdminAccess": true,
"sbcGateways": [0],
"secureSMSEnabled": true,
"services": ["string"],
"userLimit": 0,
"userProvisioningEnabled": true
}Required Fields
enterpriseName (String) - The name of the enterprise to be created. This field is mandatory as it uniquely identifies the enterprise in the system.
pbxId (Array of Integers) - The PBX Type id.
sbcGateways (Array of Integers) - The Session Border Controller (SBC) gateways.
services (Array of Strings) - Defines the services enabled for the enterprise. Possible values: PBX, Trunk, CALLAPP, CallRecording, SMS, and CHAT.
Response
On a successful request, the API returns a Long integer which represents the database ID of the newly created enterprise. This ID will be used in subsequent API calls to associate users and other configurations with this enterprise.
Example Response:
123456789Part II: Registering the Enterprise
At this point, the service provider should present to the Enterprise Admin the Registration URL to complete the enterprise registration.
1. Retrieve the Registration URL
Method: POST
Path: /enterprise/getActionItemUrl
Request Body
{
"actionType": "REGISTRATION",
"enterpriseName": "string",
"redirectUrl": "string"
}API Response
The API returns a string containing a URL - the Registration URL. This URL leads the user to the appropriate Microsoft consent screen.
Example Response For Enterprise Login Action:
https://login.microsoftonline.com/common/oauth2/v2.0/authorize?response_type=id_token+code&client_id=6a8d4d5b-v334-4db2-9715-90h154ac7043&nonce=6457573502311203778&response_mode=form_post&state=vyTUgEk37BUQK2%2FfDTcvwKoOimF6gl9jC9p2rLlb3Kf0G3utX%2FgBdDa5sD9lZSzGu311s78Z22wamPwcnFZSizl4vMsFyjOCuXA3hnrmYbzBxmo3XLb95XgHh5WSHvXz4DgRqee9qJywqztgI84aQKNCOEAA2tncCoYc%2BtEvNBhBhbXtGd1EIR4V6H1rTOC678nCSCNNKSQWRC2EY0afD7VGstXEKD2QqD%2FrirORkTbkrmxHiQJXd9Y8MzeQxwpcV%2BuVitTxdsdAh0P5F&scope=openid Directory.ReadWrite.All Directory.AccessAsUser.All TeamsAppInstallation.ReadWriteForUser Organization.Read.All User.ReadWrite.All 48ac35b8-9aa8-4d74-927d-1f4a14a0b239/user_impersonation&redirect_uri=https://api.connecttoteams.com/restricted/handleResponse2. Present the Registration URL to the Enterprise Global Admin
Display the Registration URL as either a clickable hyperlink or a redirect button in your own portal.
When this URL is clicked, the Global Admin is prompted to grant the necessary permissions that enable the Enterprise Portal to function properly by accessing data from Microsoft systems.
3. Handle the data posted to your provided redirectURL.
After the Global Admin completes the action on the Microsoft consent screen, the ConnecttoTeams system will post a JSON object to your provided redirectUrl.
Example JSON object posted:
{
"msalAuthenticationResult": {
"authenticationResult": {
"accessToken": "access_token",
"accessTokenType": "login.microsoftonline.com",
"expiresAfter": null,
"expiresOn": 1742985175242681,
"expiresOnDate": null,
"idToken": "id_token",
"multipleResourceRefreshToken": false,
"refreshToken": null,
"userInfo": {
"displayableId": "[email protected]",
"identityProvider": "user",
"tenantId": "tenantid"
}
},
"resellerId": null,
"tenantId": null
},
"organization": "MSFT",
"officeUserType": "GLOBAL_ADMIN",
"companyAdmin": true,
"containsTeamsTenantAdminAPI": true
}The general concept of this workflow is also discussed in this article: Common Workflow .
4. Complete the Enterprise Registration
Method: POST
Path: /provisioning/completeEnterpriseRegistration
Request Body:
Below is the JSON request body for completing the newly created enterprise registration process.
{
"enterpriseId": 0,
"tenantId": "tenantId",
"givenName": "givenName",
"familyName": "familyName"
}Required Fields
enterpriseId - From Part I step 3 when /reseller/newEnterprise method was called
tenantId - From the msalAuthenticationResult entity included in the JSON object posted to the redirectUrl as mentioned in the step above.
Sample cURL Request:
curl --silent --location --request POST 'https://api.connecttoteams.com/provisioning/completeEnterpriseRegistration' \
--header 'Authorization: Bearer eyJraWQiOiJlYj........' \
--header 'Content-Type: application/json' \
--data-raw '{
"enterpriseId": 719,
"tenantId": "tenantid"
}'
API Response
The response is an Enterprise Object that includes credentials under the entAPICredentialInfo field, which you can use to obtain a token to call other methods in the Provisioning API.
{
// other values...
"entAPICredentialInfo": {
"enterpriseId": "enterpriseId",
"entAdminUsername": "entAdminUsername",
"entAdminSecret": "entAdminSecret",
"clientID": "clientID",
"clientSecret": "clientSecret"
}
}Note
Store this enterprise API credentials in a secure storage. This will be used to retrieve Enterprise level access token for ConnecttoTeams Provisioning API method calls.
Part III. Get User Sync Consent
ConnecttoTeams requires permission from the Enterprise Admin to synchronize users, which is necessary to retrieve user data and allow service configurations.
The steps described below follows the Get Action URL, Present to Global Admin, Process the Webhook Payload workflow.
1. Retrieve the User Sync URL
Method: POST
Path: /enterprise/getActionItemUrl
Request Body
{
"actionType": "GET_USER_SYNC_CONSENT",
"enterpriseName": "string",
"redirectUrl": "string"
}API Response
The API returns a string containing a URL. This URL leads the user to the appropriate Microsoft consent screen, where the enterprise admin grants the consent.
2. Present the User Sync Consent URL to the Enterprise Global Admin
Display the URL to as either a clickable hyperlink or a redirect button in your own portal.
When this URL is clicked, the Global Admin is prompted to grant the permissions.
3. Handle the data posted to your provided redirectURL.
After the Global Admin completes the action on the Microsoft consent screen, the ConnecttoTeams system will post a JSON object to your provided redirectUrl.
Example JSON object posted:
200 OKPart IV. Get Consent for “Allow Management by Service Provider”
While this consent is technically optional, restricting customer access to the Enterprise Portal means that the service provider will assume greater responsibility for management tasks. Therefore, obtaining this consent is strongly recommended to ensure easier operation. This feature is discussed in this user guide: Granting Consent to Providers to Perform Enterprise Provisioning.
To get the consent, follow the Get Action URL, Present to Global Admin, Process the Webhook Payload workflow and be sure to use actionType= GET_SERVICE_PROVIDER_MANAGEMENT_CONSENT instead.
Next Steps
Proceed to configure the various objects needed for the services used by the Enterprise. For reference, see the following: