Provision Customer M365 User

This request updates the details of the M365 customer tenant user including assigning numbers and configuring Calling policies. Once a number is assigned, its updated to both Live Platform and Teams admin center.

This request can be executed for both Essentials Plus and Pro services (both Direct Routing and Operator Connect) customers.

URI

Copy 
{{baseUrl}}/api/v2/customer/b2c6bc2f-f42a-4cd2-b253-143764d7c2ec/user/sip:Christiec@M365x43868129.onmicrosoft.com/script

HTTP Method

POST, PUT

Both POST and PUT methods are interchangeable for backward compatibility.

Request Headers

Parameter

Type

Description

X-Ovoc-Channel-Id

integer

The Live Platform channel "id". When specified, data retrieval is scoped to only customers belonging to the specified channel. See Get List of Channels to extract this value.

You can alternatively use "X-IAM-Account-Id" which as result generates an identical response.

X-IAM-Account-Id

string

The Live Platform "iamAccountId" of the channel. When specified, data retrieval is scoped to only customers belonging to the specified channel. See Get List of Channels to extract this value.

Request Parameters (Mandatory)

Parameter

Type

Description

customerGuid

string($uuid) path

Customer subscriber Azure Tenant Guid.

subscriberEmail

string($uuid) path

Customer subscriber Email address.

Request Body

Parameter

Type

Description

FirstName

string

User's given name (first name) as stored in Microsoft Entra ID (Azure AD).

Last Name

string

User's surname or family name.

City

string

The city associated with the user's business address.

Department

string

Organizational department to which the user belongs (e.g., Sales, IT, Finance).

Office

string

Office location or office name assigned to the user. Often maps to the physical office site.

PostalCode

string

ZIP/postal code of the user's business address.

StateOrProvince

string

State, province, or region associated with the user's business address.

StreetAddress

string

Street portion of the user's business address.

UsageLocation

integer

A valid Two-letter ISO 3166-1 alpha-2 country/region code that determines service availability and licensing eligibility for the user (e.g., US, GB, IL).

ClientPolicy

string

Teams client policy assigned to the user, controlling features and behavior within the Teams client application.

ConferencingPolicy

string

Teams meeting/conferencing policy that controls meeting capabilities such as dial-in, recording, anonymous join, and meeting options.

HostedVoiceMail

Boolean

Indicates whether voicemail services are hosted in Microsoft 365/Teams Phone for the user.

PinPolicy

string

Policy governing PIN requirements for features such as Audio Conferencing and other voice-enabled services.

ExternalAccessPolicy

string

Policy controlling federation and communication with external organizations and Skype users.

HostedVoicemailPolicy

string

Voicemail policy assigned to the user, defining voicemail-related settings and behavior.

MobilityPolicy

string

Legacy Skype/Teams mobility policy controlling mobile client capabilities and mobile access features.

EnterpriseVoiceEnabled

boolean

Indicates whether the user is enabled for Teams Phone / Enterprise Voice functionality, allowing PSTN calling capabilities when properly licensed and configured.

TeamsCallingPolicy

string

Teams calling policy assigned to the user, controlling calling features such as call forwarding, delegation, call groups, and voicemail options. For full list of values, LifeCycle Management Templates.

OnlineVoiceRoutingPolicy

string

Voice routing policy assigned to the user that determines how outbound PSTN calls are routed through Direct Routing infrastructure. Default 'unrestricted'

For Direct Routing services only.

TenantDialPlan

string

Tenant-level dial plan assigned to the user, defining number normalization and dialing rules.

LineURI

string

The primary telephone number assigned to the user, typically stored in E.164 format (e.g., tel:+15551234567).

PrivateLine

string

Secondary/private telephone number assigned to the user for direct calling that bypasses delegates or assistants.

CallPickupGroup

string

Call pickup group assignment that allows members of a group to answer calls intended for other group members.

GroupingId GUID

string

Unique globally unique identifier (GUID) used to associate related voice or call pickup group memberships and configurations.

The 'Usage location' of the user must match the phone number country code. The Usage Location must be manually set in the customer Teams admin center. See Set Usage Location.

Example Request

Copy 
{
"TeamsCallingPolicy": "AllowCalling",
"EnterpriseVoiceEnabled": true,
"LineURI": "tel:+61396504002"
}

Example Response

Copy 
{
    "Identity": "bf62cea8-685d-4d78-bd2e-5d03cb878fd1",
    "Status": "----",
    "CallForward": "",
    "Department": "Marketing",
    "WebName": "Alex Wilber",
    "LineURI": "tel:+61396504002",
    "UserType": "TeamsOnly",
    "MsInterpretedUserType": "PureOnlineTeamsOnlyUser",
    "SipAddress": "sip:alexw@1xwzg5.onmicrosoft.com",
    "UserPrincipalName": "AlexW@1xwzg5.onmicrosoft.com",
    "UsageLocation": "AU",
    "HybridPstnSiteName": null,
    "RegistrarPool": null,
    "ObjectId": "BF62CEA8-685D-4D78-BD2E-5D03CB878FD1",
    "PsCount": 3,
    "IsManaged": true,
    "HostingProvider": "sipfed.online.lync.com",
    "EnterpriseVoiceEnabled": true,
    "OnlineVoiceRoutingPolicy": "",
    "Template": null
}

The assigned number is displayed in the customer Teams admin center.

Response

■ 200 OK

Parameter

Type

Description

Identity

string($uuid) (path)

Unique identifier for the user object within Microsoft Teams or Microsoft 365. Typically a GUID used by PowerShell and backend services.

Status

string

Current operational or provisioning status of the user.

CallForward

boolean

Indicates the user's call forwarding configuration. A blank value typically means no call forwarding is configured.

Department

string

Organizational department assigned to the user (e.g., Marketing, Finance, IT).

WebName

string

Display name shown in Teams, Microsoft 365, and address books.

LineURI

string

Primary phone number assigned to the user, usually stored in E.164 format prefixed with tel:. Example: tel:+61396504002.

UserType

string

Indicates the user's Teams coexistence mode. TeamsOnly means all chat, calling, and meeting workloads are handled in Microsoft Teams. Default: TeamsOnly

MsInterpretedUserType

string

Microsoft's internal classification of the user's deployment model. PureOnlineTeamsOnlyUser indicates a cloud-only Teams user with no on-premises Skype for Business dependencies. Default: PureOnlineTeamsOnlyUser

SipAddress

string

Session Initiation Protocol (SIP) address used for voice, messaging, and presence services in Teams. For example, sip:christiec@m365x43868129.onmicrosoft.com

UserPrincipalName

string

The user's sign-in account (UPN), usually matching their email address.

UsageLocation

string

Usage Location as defined in the customer tenant Microsoft Entra admin center (see Set Usage Location).

HybridPstnSiteName

string

Name of the PSTN site assigned in a hybrid voice deployment. null indicates the user is not associated with a hybrid PSTN site.

RegistrarPool

string

Teams/Skype registrar service hosting the user account. A null value is common for cloud-only users where the infrastructure is managed by Microsoft.

ObjectId

string

Azure AD (Microsoft Entra ID) object GUID representing the user. Often matches the Identity value.

PsCount

integer

Internal PowerShell property count or object metadata value. Usually not relevant for administrative reporting.

IsManaged

boolean

Indicates whether the account is managed by the organization. true means the account is actively managed in Microsoft Entra ID.

HostingProvider

string

The Microsoft service hosting the user's real-time communications services. sipfed.online.lync.com indicates Microsoft-hosted Teams/Skype Online infrastructure.

EnterpriseVoiceEnabled

boolean

Indicates whether the user is enabled for Teams Phone (Enterprise Voice) capabilities. true means the user can be configured for PSTN calling.

OnlineVoiceRoutingPolicy

string

Voice routing policy assigned to the user for Direct Routing. A blank value indicates no custom policy is assigned. Default: unrestricted or SiteLocationTag-Unrestricted

Template

string

User template or provisioning template applied to the account. null indicates no template assignment exists.
■ 400 Bad Request

Parameter

Type

Description/Examples

errors

string

 Text description of the error.

type

string

"https://tools.ietf.org/html/rfc7231#section-6.5.1"

title

string

Email title. For example "One or more validation errors occurred."

status

error code

HTML error code i.e. 400

detail

string

Additional error details.

traceId

string

Error trace Id

instance

string

Error instance

errorTicket

string

This field may not appear for all return codes.

errorCode

string

This field may not appear for all return codes.

additionalProp1

string

Custom Script variable argument. For example "CacProfile": "5 sessions"

additionalProp2

string

Custom Script argument. For example, ProxySet": "SIPTrunk",

additionalProp3

string

Custom Script argument. For example, "OnlinePstnGateway": "sandbox1.audiocodes.be"
■ 403 Forbidden: this error is raised when the M365 user specified in the URL that does not belong to a customer that is attached to the channel as specified by the Request header X-Ovoc-Channel-Id or X-IAM-Account-Id values.

Parameter

Type

Description/Examples

errors

string

 Text description of the error.

type

string

"https://tools.ietf.org/html/rfc7231#section-6.5.1"

title

string

Email title. For example "One or more validation errors occurred."

status

error code

HTML error code i.e. 400

detail

string

Additional error details.

traceId

string

Error trace Id

instance

string

Error instance

errorTicket

string

This field may not appear for all return codes.

errorCode

string

This field may not appear for all return codes.

additionalProp1

string

Custom Script variable argument. For example "CacProfile": "5 sessions"

additionalProp2

string

Custom Script argument. For example, ProxySet": "SIPTrunk",

additionalProp3

string

Custom Script argument. For example, "OnlinePstnGateway": "sandbox1.audiocodes.be"
■ 409 Conflict

Parameter

Type

Description/Examples

errors

string

 Text description of the error.

type

string

"https://tools.ietf.org/html/rfc7231#section-6.5.1"

title

string

Email title. For example "One or more validation errors occurred."

status

error code

HTML error code i.e. 400

detail

string

Additional error details.

traceId

string

Error trace Id

instance

string

Error instance

errorTicket

string

This field may not appear for all return codes.

errorCode

string

This field may not appear for all return codes.

additionalProp1

string

Custom Script variable argument. For example "CacProfile": "5 sessions"

additionalProp2

string

Custom Script argument. For example, ProxySet": "SIPTrunk",

additionalProp3

string

Custom Script argument. For example, "OnlinePstnGateway": "sandbox1.audiocodes.be"
■ 500 Internal Server Error