Common Workflow

  • Updated on Jun 27, 2025
  • Published on Jun 24, 2025
  • 3 minute(s) read
Prev Next

Get Action URL, Present to Global Admin, Process the Webhook

Action Type Values

This table shows the possible values in the actionType for the enterprise/getActionItemUrl method.

actionType

Use

REGISTRATION

To get the URL with which the Global Admin (GA) can start the enterprise registration process.

When registration is completed, an msalAuthentication token is given to the webhook. This token can be used to access other Graph API calls, such as for deploying apps to MS Teams.

LOGIN_ENTERPRISE_ADMIN

To get the URL with which the Global Admin (GA) can login to the system thereby getting their msalAuthentication token.  This token can be used to access other Graph API calls, such as for deploying apps to MS Teams.


Retrieving the URL for this actionType may be frequently done during deployment of app and, if GA is not consenting to “Allow Management by Service Provider“, during actions like Sync Teams Users.

GET_USER_SYNC_CONSENT

REQUIRED

To get the URL to which the GA can consent to accessing and updating the MS Teams users data. This is needed for configuring services to Teams Users such as PBX and SMS.

GET_PRESENCE_CONSENT

REQUIRED for calling services

To get the URL with which the GA can consent to access Presence status of Teams users. The presence status is used in the following services:
PBX Connector

CallApp Add-on
Call Recording Add-on

GET_CALL_APP_CONSENT

REQUIRED for CallApp Add-on

To get the URL with which the GA can consent to access MS Teams in order for CallApp Add-on to function.

GET_CONTACTS_CONSENT

OPTIONAL

To get the URL with which the GA can consent to allow sync’ing with Outlook and Microsoft Organization contacts. Useful for contacts management feature of the following apps:
PBX Connector
CallApp Add-on

SMS Connector

GET_CDR_CONSENT

OPTIONAL

To get the URL with which the GA can consent to allow access to call records in Teams. Useful to allow Service Provider to get more call details to debug call issues.

GET_CALL_RECORDING_CONSENT

REQUIRED for Call Recording Add-on

To get the URL with which the GA can consent to access MS Teams in order for Call Recording to function. This includes creating the Compliance Recording Policy in the Microsoft Teams tenant.

GET_SERVICE_PROVIDER_MANAGEMENT_CONSENT

OPTIONAL

To get the URL with which the GA consent to allow Service Provider to do most management tasks on GA’s behalf. This includes provisioning users, syncing users, and create direct routes among others.

  1. Retrieve the action URL

    API Endpoint

    Method: POST

    Path: /enterprise/getActionItemUrl

    Request Body (JSON)

    {
  "actionType": "string",
  "enterpriseName": "string",
  "redirectUrl": "string"
}

    Required Fields

    actionType - see Action Type Values table below.  

    enterpriseName

    redirectUrl - Your webhook URL that will receive the response payload

    API Response

    The API returns a string containing a URL. This URL leads the user to the appropriate Microsoft consent screen.

    Sample cURL Request

    curl --silent --location --request POST 'https://api.connecttoteams.com/enterprise/getActionItemUrl' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>' \
--data-raw '{
  "actionType": "REGISTRATION",
  "redirectUrl": "https://yourapp.com/callback",
  "enterpriseName": "AcmeCorp"
}'

    Sample Response

    https://login.microsoftonline.com/common/oauth2/v2.0/authorize?response_type=id_token+code&client_id=<client_id>&nonce=6457573502311203778&response_mode=form_post&state=<state>&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/handleResponse

  2. Present the URL to the Enterprise Global Admin

    Display the retrieved URL in step 1 as either a clickable hyperlink or a redirect button in your own portal.

    When this URL is clicked, the  Global Admin is prompted to follow the actions presented — such as consenting to some permissions.

  3. Handle the data posted to your provided redirectURL.

    a. For Registration & Login, a JSON object is posted to the provided redirectUrl after the process is completed.

    Sample JSON Object Response on Registration or Login Actions:

    {
  "msalAuthenticationResult": {
    "authenticationResult": {
      "accessToken": "eyJ0eXAiOiJKV1QiLCJub25j...",
      "accessTokenType": "login.microsoftonline.com",
      "expiresAfter": null,
      "expiresOn": 1742985175242681,
      "expiresOnDate": null,
      "idToken": "rZ7VeEm5tG2nlBZ6MAfW-...",
      "multipleResourceRefreshToken": false,
      "refreshToken": null,
      "userInfo": {
        "displayableId": "[email protected]",
        "identityProvider": "user",
        "tenantId": "5c0068f3-dfbb-..."
      }
    },
    "resellerId": null,
    "tenantId": null
  },
  "organization": "MSFT",
  "officeUserType": "GLOBAL_ADMIN",
  "companyAdmin": true,
  "containsTeamsTenantAdminAPI": true
}

    b. For other consent actions, a message is sent as a query parameter, and the user is redirected to the provided redirect URL.

    Sample Redirect on Success:

    https://yourapp.com/callback?success=User Sync Consent Completed Successfully

    Sample Redirect on Error:

    https://yourapp.com/callback?error=Unable to Complete the process. User is not a Global Admin

    Query parameter values are displayed without URL encoding for better readability.