Microsoft Teams Phone

App · 20 actions

See who is available or on a call, set your Teams status, manage phone numbers, read call history, and start workflows on new calls and presence changes.

Actions

ActionWhat it does
Assign phone numberGive a phone number to a person.
Find peopleFind people in your organization whose name or email address starts with what you type, with their phone numbers.
Get a person's Teams Phone settingsGet one person's phone numbers, whether calling is on, and their calling policies.
Get call recordGet one Teams call or meeting: when it was, who took part and, if asked, each leg of the call.
Get phone numberGet one phone number's details: its type, who has it, and its emergency location.
Get phone number request statusCheck whether an assignment or unassignment has finished, and why it failed if it did.
Get presenceGet someone's presence in Teams: whether they are available, busy or in a call, and their status message.
Get presence of several peopleGet the presence of up to 650 people at once, such as everyone who answers a phone line.
List call recordsList Teams calls and meetings that ended in the last 30 days, with who organized them.
List direct routing callsList calls through your own phone carrier's connection (Direct Routing), with whether each connected and why it failed.
List phone network callsList calls people made and received over the phone network with Calling Plans or Operator Connect, with numbers, length and cost.
List phone numbersList your organization's phone numbers in Teams and who each is assigned to.
List Teams Phone usersList people's Teams Phone settings: their phone numbers, whether calling is on, and their calling policies.
Reset my statusStop showing the status you set, so Teams works your presence out again from your calls, meetings and calendar.
Set my statusSet the status you show in Teams, as choosing it in Teams does: available, busy, do not disturb, be right back, away or offline.
Set my status messageSet the message people see on your Teams profile and when they message or call you.
Show me as in a callTell Teams you are busy somewhere else for a while, such as on a call in another phone system.
Stop showing me as in a callEnd the presence Show me as in a call set, before it runs out.
Unassign phone numberTake a phone number back from whoever has it, so it can be given to someone else.
Update phone numberChange a phone number's emergency location, or route internal calls to it over the phone network.

Assign phone number

Give a phone number to a person. Teams finishes it within a few minutes; Get phone number request status says when. Needs a Teams admin.

Inputs

Phone numbertelephone_numbertextRequired
The phone number, with its country code. Pick one of your organization's numbers, or type one such as +12065550100.
PersonusertextRequired
Who gets the number.
Useassignment_categorytext
How they use it. Leave empty for Primary.One of: primary, private (Private (incoming calls only)), alternate.
Emergency location idlocation_idtext
The id of the emergency location for this number, from the Teams admin center. Leave empty for none.

Outputs

acceptedtrue/false
Always true once Teams has taken the request
operation_idtext
The request's id, for Get phone number request status
telephone_numbertext
The phone number
user_idtext
The id of the person getting it
Example output
{
  "accepted": true,
  "operation_id": "QXNzaWdubWVudHw2Y2E4Yjc0Ni00YzgxLTRhY2EtOTUyNi1jZmNjNGRiYWYyMmI",
  "telephone_number": "+12065550100",
  "user_id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3"
}

Find people

Find people in your organization whose name or email address starts with what you type, with their phone numbers.

Inputs

Name or emailsearchtextRequired
The start of a name or email address.
Maximum resultsmax_resultsnumber
The most to return, from 1 to 100. Leave empty for 25.From 1 to 100.

Outputs

countnumber
How many are returned
userslist
The people found
Example output
{
  "count": 1,
  "users": [
    {
      "businessPhones": [
        "+12065550100"
      ],
      "displayName": "Adele Vance",
      "id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
      "jobTitle": "Deputy Clerk",
      "mail": "adelev@contoso.com",
      "mobilePhone": "",
      "userPrincipalName": "adelev@contoso.com"
    }
  ]
}

Get a person's Teams Phone settings

Get one person's phone numbers, whether calling is on, and their calling policies. Needs a Teams admin.

Inputs

PersonusertextRequired
Whose settings to get.

Outputs

userobject
A person's Teams Phone settings
Example output
{
  "user": {
    "accountType": "user",
    "createdDateTime": "2025-01-07T09:08:50.9115993Z",
    "featureTypes": [
      "Teams",
      "PhoneSystem",
      "CallingPlan"
    ],
    "id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
    "isEnterpriseVoiceEnabled": true,
    "modifiedDateTime": "2025-01-07T09:08:50.9115993Z",
    "policies": [
      {
        "assignmentType": "group",
        "displayName": "AllOn",
        "policyType": "TeamsCallingPolicy"
      }
    ],
    "primary_phone_number": "+12065550100",
    "telephoneNumbers": [
      {
        "assignmentCategory": "primary",
        "telephoneNumber": "+12065550100"
      }
    ],
    "userPrincipalName": "adelev@contoso.com"
  }
}

Get call record

Get one Teams call or meeting: when it was, who took part and, if asked, each leg of the call. Needs the CallRecords.Read.All application permission (see the connect steps).

Inputs

Call record idcall_record_idtextRequired
The call record's id, from List call records or the New call record trigger.
Include each leginclude_sessionstrue/false
Also return each leg of the call, with who called whom.Default: false.

Outputs

call_recordobject
A Teams call or meeting that ended, with who was on it
Example output
{
  "call_record": {
    "endDateTime": "2026-11-03T18:52:46.7640013Z",
    "id": "e523d2ed-2966-4b6b-925b-754a88034cc5",
    "joinWebUrl": "",
    "lastModifiedDateTime": "2026-11-03T19:00:24.582757Z",
    "modalities": [
      "audio"
    ],
    "organizer_id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
    "organizer_name": "Adele Vance",
    "participants": [
      {
        "displayName": "Adele Vance",
        "id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
        "kind": "user"
      },
      {
        "displayName": "Owen Franklin",
        "id": "66825e03-7ef5-42da-9069-724602c31f6b",
        "kind": "user"
      }
    ],
    "sessions": [
      {
        "callee_name": "Owen Franklin",
        "caller_name": "Adele Vance",
        "endDateTime": "2026-11-03T18:52:46.7640013Z",
        "id": "e523d2ed-2966-4b6b-925b-754a88034cc5",
        "modalities": [
          "audio"
        ],
        "startDateTime": "2026-11-03T18:52:21.2169889Z"
      }
    ],
    "startDateTime": "2026-11-03T18:52:21.2169889Z",
    "type": "peerToPeer",
    "version": 1
  }
}

Get phone number

Get one phone number's details: its type, who has it, and its emergency location. Needs a Teams admin.

Inputs

Phone numbertelephone_numbertextRequired
The phone number, with its country code. Pick one of your organization's numbers, or type one such as +12065550100.

Outputs

numberobject
A phone number your organization has
Example output
{
  "number": {
    "activationState": "activated",
    "assignmentCategory": "primary",
    "assignmentStatus": "userAssigned",
    "assignmentTargetId": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
    "capabilities": [
      "userAssignment"
    ],
    "city": "Seattle",
    "civicAddressId": "",
    "id": "YmMyNjMyZTMtNzUwYy00N2Q3LWFlYWUtOWZlZTAzNWJjMGM3fCsxMjAyMzQ1Njc4OQ",
    "isoCountryCode": "US",
    "locationId": "",
    "numberSource": "online",
    "numberType": "callingPlan",
    "operatorId": "7a205197-8e59-487d-b9fa-3fc1b108f1e5",
    "portInStatus": "",
    "reverseNumberLookupOptions": [],
    "supportedCustomerActions": [
      "locationUpdate"
    ],
    "telephoneNumber": "+12065550100"
  }
}

Get phone number request status

Check whether an assignment or unassignment has finished, and why it failed if it did.

Inputs

Request idoperation_idtextRequired
The request id Assign phone number or Unassign phone number returned.

Outputs

operationobject
A phone number assignment request
Example output
{
  "operation": {
    "createdDateTime": "2026-11-03T22:03:26Z",
    "id": "QXNzaWdubWVudHw2Y2E4Yjc0Ni00YzgxLTRhY2EtOTUyNi1jZmNjNGRiYWYyMmI",
    "numbers": [
      {
        "resourceLocation": "https://graph.microsoft.com/v1.0/admin/teams/telephoneNumberManagement/numberAssignments/N2EyMDUxOTctOGU1OS00ODdkLWI5ZmEtM2ZjMWIxMDhmMWU1fCsxMjA2MTIzNDU2Nw",
        "status": "succeeded",
        "statusDetail": ""
      }
    ],
    "status": "succeeded"
  }
}

Get presence

Get someone's presence in Teams: whether they are available, busy or in a call, and their status message.

Inputs

Personusertext
Whose presence to get. Leave empty for your own.

Outputs

presenceobject
A person's presence in Teams
Example output
{
  "presence": {
    "activity": "InACall",
    "availability": "Busy",
    "id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
    "is_out_of_office": false,
    "out_of_office_message": "",
    "sequenceNumber": "A0129311063",
    "status_message": "On the clerk's office line until noon"
  }
}

Get presence of several people

Get the presence of up to 650 people at once, such as everyone who answers a phone line.

Inputs

PeopleuserslistRequired
The people whose presence to get.

Outputs

countnumber
How many are returned
presenceslist
Each person's presence
Example output
{
  "count": 1,
  "presences": [
    {
      "activity": "InACall",
      "availability": "Busy",
      "id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
      "is_out_of_office": false,
      "out_of_office_message": "",
      "sequenceNumber": "A0129311063",
      "status_message": "On the clerk's office line until noon"
    }
  ]
}

List call records

List Teams calls and meetings that ended in the last 30 days, with who organized them. Needs the CallRecords.Read.All application permission (see the connect steps).

Inputs

Fromstart_timedate and time
The start of the time range, by when calls started. Leave empty for a day before the end.
Untilend_timedate and time
The end of the time range. Leave empty for now.
Personparticipanttext
Only calls this person took part in. Leave empty for everyone.
Maximum resultsmax_resultsnumber
The most to return, from 1 to 1000. Leave empty for 200.From 1 to 1000.

Outputs

call_recordslist
The call records
countnumber
How many are returned
Example output
{
  "call_records": [
    {
      "endDateTime": "2026-11-03T18:52:46.7640013Z",
      "id": "e523d2ed-2966-4b6b-925b-754a88034cc5",
      "joinWebUrl": "",
      "lastModifiedDateTime": "2026-11-03T19:00:24.582757Z",
      "modalities": [
        "audio"
      ],
      "organizer_id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
      "organizer_name": "Adele Vance",
      "startDateTime": "2026-11-03T18:52:21.2169889Z",
      "type": "peerToPeer",
      "version": 1
    }
  ],
  "count": 1
}

List direct routing calls

List calls through your own phone carrier's connection (Direct Routing), with whether each connected and why it failed. Needs the CallRecords.Read.All application permission (see the connect steps).

Inputs

Fromstart_timedate and time
The start of the time range, by when calls started. Leave empty for a day before the end.
Untilend_timedate and time
The end of the time range. Leave empty for now.
Personusertext
Only this person's calls. Leave empty for everyone.
Only failed callsfailed_onlytrue/false
Leave out calls that connected.Default: false.
Maximum resultsmax_resultsnumber
The most to return, from 1 to 1000. Leave empty for 200.From 1 to 1000.

Outputs

callslist
The calls, oldest first
countnumber
How many are returned
Example output
{
  "calls": [
    {
      "callEndSubReason": 540000,
      "callType": "ByotIn",
      "calleeNumber": "+12065550100",
      "callerNumber": "+12065550199",
      "correlationId": "c98e1515-a937-4b81-b8a8-3992afde64e0",
      "duration": 5,
      "endDateTime": "2026-11-03T15:00:30.105Z",
      "failureDateTime": "0001-01-01T00:00:00Z",
      "finalSipCode": 0,
      "finalSipCodePhrase": "BYE",
      "id": "9e8bba57-dc14-533a-a7dd-f0da6575eed1",
      "inviteDateTime": "2026-11-03T15:00:21.949Z",
      "mediaBypassEnabled": false,
      "mediaPathLocation": "USWE",
      "signalingLocation": "USWE",
      "startDateTime": "2026-11-03T15:00:25.105Z",
      "successfulCall": true,
      "trunkFullyQualifiedDomainName": "sbc1.contoso.com",
      "userDisplayName": "Adele Vance",
      "userId": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
      "userPrincipalName": "adelev@contoso.com"
    }
  ],
  "count": 1
}

List phone network calls

List calls people made and received over the phone network with Calling Plans or Operator Connect, with numbers, length and cost. Needs the CallRecords.Read.All application permission (see the connect steps).

Inputs

Fromstart_timedate and time
The start of the time range, by when calls started. Leave empty for a day before the end.
Untilend_timedate and time
The end of the time range. Leave empty for now.
Personusertext
Only this person's calls. Leave empty for everyone.
Maximum resultsmax_resultsnumber
The most to return, from 1 to 1000. Leave empty for 200.From 1 to 1000.

Outputs

callslist
The calls, oldest first
countnumber
How many are returned
Example output
{
  "calls": [
    {
      "callDurationSource": "microsoft",
      "callId": "1835317186_112562680@61.221.3.176",
      "callType": "user_in",
      "calleeNumber": "+12065550100",
      "callerNumber": "+12065550199",
      "charge": 0,
      "conferenceId": "",
      "connectionCharge": 0,
      "currency": "USD",
      "destinationContext": "",
      "destinationName": "United States",
      "duration": 219,
      "endDateTime": "2026-11-03T15:03:47.2589935Z",
      "id": "9c4984c7-6c3c-427d-a30c-bd0b2eacee90",
      "inventoryType": "Subscriber",
      "licenseCapability": "MCOPSTNU",
      "operator": "Microsoft",
      "startDateTime": "2026-11-03T15:00:08.2589935Z",
      "tenantCountryCode": "US",
      "usageCountryCode": "US",
      "userDisplayName": "Adele Vance",
      "userId": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
      "userPrincipalName": "adelev@contoso.com"
    }
  ],
  "count": 1
}

List phone numbers

List your organization's phone numbers in Teams and who each is assigned to. Needs a Teams admin.

Inputs

Number typenumber_typetext
Only numbers of this type. Leave empty for all.One of: callingPlan (Calling Plan), directRouting (Direct Routing), operatorConnect (Operator Connect).
Assigned toassignment_statustext
Only numbers in this state, such as Not assigned to find a free one. Leave empty for all.One of: unassigned (Not assigned), userAssigned (Assigned to a person), conferenceAssigned (Assigned to audio conferencing), voiceApplicationAssigned (Assigned to a call queue or auto attendant), thirdPartyAppAssigned (Assigned to a third-party app), policyAssigned (Assigned to a shared calling policy).
Phone numbertelephone_numbertext
Only this number, with its country code. Leave empty for all.
Maximum resultsmax_resultsnumber
The most to return, from 1 to 1000. Leave empty for 200.From 1 to 1000.

Outputs

countnumber
How many are returned
numberslist
The phone numbers
Example output
{
  "count": 1,
  "numbers": [
    {
      "activationState": "activated",
      "assignmentCategory": "primary",
      "assignmentStatus": "userAssigned",
      "assignmentTargetId": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
      "capabilities": [
        "userAssignment"
      ],
      "city": "Seattle",
      "civicAddressId": "",
      "id": "YmMyNjMyZTMtNzUwYy00N2Q3LWFlYWUtOWZlZTAzNWJjMGM3fCsxMjAyMzQ1Njc4OQ",
      "isoCountryCode": "US",
      "locationId": "",
      "numberSource": "online",
      "numberType": "callingPlan",
      "operatorId": "7a205197-8e59-487d-b9fa-3fc1b108f1e5",
      "portInStatus": "",
      "reverseNumberLookupOptions": [],
      "supportedCustomerActions": [
        "locationUpdate"
      ],
      "telephoneNumber": "+12065550100"
    }
  ]
}

List Teams Phone users

List people's Teams Phone settings: their phone numbers, whether calling is on, and their calling policies. Needs a Teams admin.

Inputs

Only people with calling onvoice_enabled_onlytrue/false
Leave out people who can't make or take phone calls in Teams.Default: false.
Maximum resultsmax_resultsnumber
The most to return, from 1 to 1000. Leave empty for 200.From 1 to 1000.

Outputs

countnumber
How many are returned
userslist
Each person's Teams Phone settings
Example output
{
  "count": 1,
  "users": [
    {
      "accountType": "user",
      "createdDateTime": "2025-01-07T09:08:50.9115993Z",
      "featureTypes": [
        "Teams",
        "PhoneSystem",
        "CallingPlan"
      ],
      "id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
      "isEnterpriseVoiceEnabled": true,
      "modifiedDateTime": "2025-01-07T09:08:50.9115993Z",
      "policies": [
        {
          "assignmentType": "group",
          "displayName": "AllOn",
          "policyType": "TeamsCallingPolicy"
        }
      ],
      "primary_phone_number": "+12065550100",
      "telephoneNumbers": [
        {
          "assignmentCategory": "primary",
          "telephoneNumber": "+12065550100"
        }
      ],
      "userPrincipalName": "adelev@contoso.com"
    }
  ]
}

Reset my status

Stop showing the status you set, so Teams works your presence out again from your calls, meetings and calendar.

Inputs

None.

Outputs

clearedtrue/false
Always true once cleared
user_idtext
Your Microsoft Entra user id
Example output
{
  "cleared": true,
  "user_id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3"
}

Set my status

Set the status you show in Teams, as choosing it in Teams does: available, busy, do not disturb, be right back, away or offline.

Inputs

StatuspresencetextRequired
The status to show.One of: Available/Available (Available), Busy/Busy (Busy), DoNotDisturb/DoNotDisturb (Do not disturb), BeRightBack/BeRightBack (Be right back), Away/Away (Appear away), Offline/OffWork (Appear offline).
Forexpires_aftertext
How long to keep it. Leave empty for Teams' default: a day for busy or do not disturb, a week for the others.One of: PT1H (1 hour), PT2H (2 hours), PT4H (4 hours), PT8H (8 hours), PT24H (1 day), PT168H (1 week).

Outputs

activitytext
The activity now set
availabilitytext
The availability now set
updatedtrue/false
Always true once set
user_idtext
Your Microsoft Entra user id
Example output
{
  "activity": "DoNotDisturb",
  "availability": "DoNotDisturb",
  "updated": true,
  "user_id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3"
}

Set my status message

Set the message people see on your Teams profile and when they message or call you.

Inputs

MessagemessagetextRequired
The status message.
Clear it atexpires_atdate and time
When to clear it. Leave empty to keep it until you change it.

Outputs

expires_attext
When it clears (ISO 8601, UTC), or empty
messagetext
The message now set
updatedtrue/false
Always true once set
user_idtext
Your Microsoft Entra user id
Example output
{
  "expires_at": "2026-11-06T17:00:00Z",
  "message": "On the clerk's office line until noon",
  "updated": true,
  "user_id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3"
}

Show me as in a call

Tell Teams you are busy somewhere else for a while, such as on a call in another phone system. Teams combines it with your other activity.

Inputs

PresencepresencetextRequired
What to show.One of: Available/Available (Available), Busy/InACall (Busy, in a call), Busy/InAConferenceCall (Busy, in a conference call), Away/Away (Away), DoNotDisturb/Presenting (Do not disturb, presenting).
For (minutes)minutesnumber
How long it lasts unless it is set again, from 5 to 240 minutes. Leave empty for 5.From 5 to 240.

Outputs

activitytext
The activity now set
availabilitytext
The availability now set
minutesnumber
How many minutes it lasts
updatedtrue/false
Always true once set
user_idtext
Your Microsoft Entra user id
Example output
{
  "activity": "InACall",
  "availability": "Busy",
  "minutes": 30,
  "updated": true,
  "user_id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3"
}

Stop showing me as in a call

End the presence Show me as in a call set, before it runs out.

Inputs

None.

Outputs

clearedtrue/false
Always true once cleared
user_idtext
Your Microsoft Entra user id
was_settrue/false
Whether a workflow presence was in place
Example output
{
  "cleared": true,
  "user_id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
  "was_set": true
}

Unassign phone number

Take a phone number back from whoever has it, so it can be given to someone else. Needs a Teams admin.

Inputs

Phone numbertelephone_numbertextRequired
The phone number, with its country code. Pick one of your organization's numbers, or type one such as +12065550100.

Outputs

acceptedtrue/false
Always true once Teams has taken the request
operation_idtext
The request's id, for Get phone number request status
previous_user_idtext
The id of who had it, or empty
telephone_numbertext
The phone number
Example output
{
  "accepted": true,
  "operation_id": "QXNzaWdubWVudHw2Y2E4Yjc0Ni00YzgxLTRhY2EtOTUyNi1jZmNjNGRiYWYyMmI",
  "previous_user_id": "fa8bf3dc-eca7-46b7-bad1-db199b62afc3",
  "telephone_number": "+12065550100"
}

Update phone number

Change a phone number's emergency location, or route internal calls to it over the phone network. Needs a Teams admin.

Inputs

Phone numbertelephone_numbertextRequired
The phone number, with its country code. Pick one of your organization's numbers, or type one such as +12065550100.
Emergency location idlocation_idtext
The id of the new emergency location, from the Teams admin center. Leave empty to keep the current one.
Clear emergency locationclear_locationtrue/false
Remove the number's emergency location.Default: false.
Skip internal VoIPskip_internal_voiptrue/false
Send calls from inside your organization to this number over the phone network instead of Teams. Turn it off again in the Teams admin center.Default: false.

Outputs

telephone_numbertext
The phone number
updatedtrue/false
Always true once updated
updated_fieldslist
What changed
Example output
{
  "telephone_number": "+12065550100",
  "updated": true,
  "updated_fields": [
    "locationId"
  ]
}

On this page