MS Entra – Users – Create User Contact

Create a contact for a user in Entra ID.

Action details

Property	Value
Action label	MS Entra – Users – Create User Contact
Category	CloudTools
Apex class and method	CreateEntraUserContact.createUserContact
Input type	CreateEntraUserContact.CreateEntraUserContactInput
Output type	List<CreateEntraUserContact.CreateEntraUserContactOutput>
Authorization	Microsoft 365 connector; supported authorization depends on the endpoint and target.
Microsoft Graph request	POST /users/{userIdOrPrincipalName}/contacts

Prerequisites and permissions

Configure a CloudTools Connector with Connector Type set to Microsoft 365. Complete sign-in for OAuth Delegated (Authorization Code). For supported OAuth Application (Client Credentials) requests, grant application permissions and administrator consent. The identity must have access to the selected resource; directory operations can also require Microsoft Entra roles. Use Creating an Entra ID App and Integration Connectors for setup.

The action permission provider declares these alternatives. They are not cumulative requirements, not all are least privileged, and a scope can have target-specific restrictions. Check the Microsoft operation reference before selecting permissions.

Permission type	Declared alternatives
Delegated	Contacts.ReadWrite
Application	Contacts.ReadWrite

Endpoints: /users/{id | userPrincipalName}/contacts

See the Microsoft operation and permissions reference.

Inputs

Input	Apex field	Type	Required	Description
User Id or Principal Name	userIdOrPrincipalName	String	Yes	User id or principal name to create the contact for.
Display Name	displayName	String	No	Display name for the contact
Given Name	givenName	String	No	Given name for the contact
Surname	surname	String	No	Surname for the contact
Company Name	companyName	String	No	Company name for the contact
Mobile Phone	mobilePhone	String	No	Mobile phone number for the contact
Business Phones CSV	businessPhonesCsv	String	No	Comma-separated business phone numbers
Home Phones CSV	homePhonesCsv	String	No	Comma-separated home phone numbers
Email Addresses JSON	emailAddressesJson	String	No	JSON array of email address objects with name and address properties

Supply a nonempty list with a non-null first request. Graph actions process only that first request. Global inputs do not expose connectorId; subscriber Apex and Flow use CloudTools connector selection. Use Microsoft Graph resource IDs or the specifically documented user identifier, and resolve dynamic values before invocation.

Outputs

Returns one mapped CreateEntraUserContactOutput inside a list. Check the actual result shape and fields before use. This implementation creates a default result object when the response is null; an object alone does not prove that a resource was returned.

Output	Apex field	Type	Description
Id	id	String	Contact identifier
Display Name	displayName	String	Display name for the contact
Given Name	givenName	String	Given name for the contact
Surname	surname	String	Surname for the contact
Company Name	companyName	String	Company name for the contact
Business Phones	businessPhones	List<String>	Business phone numbers for the contact
Home Phones	homePhones	List<String>	Home phone numbers for the contact
Mobile Phone	mobilePhone	String	Mobile phone number for the contact
Email Addresses	emailAddresses	List<EmailAddressInfo>	Email addresses for the contact

Behavior and limits

Creates a mailbox contact for the specified user, not an Entra directory user. Email Addresses JSON must represent the expected email address objects; phone inputs are CSV lists.

Use in Flow

Use MS Entra – Users – Create User Contact where supported. Use a Microsoft 365 application connector configured as Set as default for Flow automations only if the endpoint and target support application access. Supply required values, retain useful outputs, and add fault handling. Delegated connections are not supported for CloudTools Flow automation. The action processes only the first input request.

Use in custom Apex

This subscriber-org example uses the Apptigent namespace. Replace identifiers and example values before use. Configure the connector, complete authorization first, run in a context permitting callouts, and handle exceptions, empty results, and unmapped fields.

Apptigent.CreateEntraUserContact.CreateEntraUserContactInput request =
    new Apptigent.CreateEntraUserContact.CreateEntraUserContactInput();
request.userIdOrPrincipalName = 'alex@contoso.com';
request.displayName = 'Adele Vance';
request.givenName = 'Adele';
request.surname = 'Vance';
request.companyName = 'Contoso';
request.mobilePhone = '+1 425 555 0109';
request.businessPhonesCsv = '+1 425 555 0101';
request.homePhonesCsv = '+1 425 555 0199';
request.emailAddressesJson = '[{"name":"Adele Vance","address":"adelev@contoso.com"}]';



List<Apptigent.CreateEntraUserContact.CreateEntraUserContactOutput> results =
    Apptigent.CreateEntraUserContact.createUserContact(
        new List<Apptigent.CreateEntraUserContact.CreateEntraUserContactInput>{ request }
    );
System.debug(results);

Use in a Lightning Web Component

Use createEntraUserContact from msEntraConnectorLib through MSEntraConnectorController. These c/ imports apply in the same namespace. Set request.connectorId for direct MSEntraAction calls. The controller captures the request selection for MSEntraAction.

Global input	LWC request mapping
userIdOrPrincipalName	request.userIdOrPrincipalName
displayName	request.displayName
givenName	request.givenName
surname	request.surname
companyName	request.companyName
mobilePhone	request.mobilePhone
businessPhonesCsv	request.businessPhones (converted by the controller)
homePhonesCsv	request.homePhones (converted by the controller)
emailAddressesJson	request.emailAddresses (converted by the controller)

entraActionExample.js

import { LightningElement } from 'lwc';
import { createEntraUserContact } from 'c/msEntraConnectorLib';

export default class EntraActionExample extends LightningElement {
    result = null;
    errorMessage = '';
    isRunning = false;
    completed = false;

    async handleRun() {
        if (this.isRunning || this.completed) return;
        this.isRunning = true;
        this.errorMessage = '';
        try {
            const request = { connectorId: 'REPLACE_WITH_CONNECTOR_RECORD_ID' };
            request.userIdOrPrincipalName = 'alex@contoso.com';
            request.displayName = 'Adele Vance';
            request.givenName = 'Adele';
            request.surname = 'Vance';
            request.companyName = 'Contoso';
            request.mobilePhone = '+1 425 555 0109';
            request.businessPhones = ['+1 425 555 0101'];
            request.homePhones = ['+1 425 555 0199'];
            request.emailAddresses = [{ address: 'someone@example.com', name: 'Contact' }];
            this.result = await createEntraUserContact(request);
            this.completed = true;
        } catch (error) {
            this.errorMessage = error.requiresInteractiveAuthorization
                ? 'Sign in to Microsoft for the connector, then try again.'
                : error.message || 'The Entra action failed.';
        } finally {
            this.isRunning = false;
        }
    }
}

entraActionExample.html

<template>
    <lightning-button label="Run action" onclick={handleRun}
        disabled={isRunning}></lightning-button>
    <p role="alert">{errorMessage}</p>
</template>

The library returns one mapped DTO or null. The controller can flatten nested fields, serialize data, or map an action result into an operation DTO. rawJson contains serialized mapped Apex data rather than the untouched Graph response.

Use getMSEntraAuthorizationState, beginMSEntraAuthorization, and createMSEntraOAuthMessageHandler to arrange delegated sign-in. The library normalizes errors but does not automatically sign in or retry. Reset completed for a new deliberate operation, and inspect resource state before retrying a mutation with an uncertain outcome.

Error handling and troubleshooting

Symptom	What to check
Required fields error	Supply a nonempty request list and required or conditionally required inputs. For LWC, use the mapped field names.
Authorization or access denied	Check connector selection, sign-in, endpoint/target permission support, administrator consent, directory roles, and resource access.
Resource not found	Check Microsoft IDs and parent resource relationships. Preserve group/drive/item associations and mailbox/calendar/event IDs.
Missing or unexpected output	Check query support, pagination, wrapper versus item models, public-only properties, and mapped DTO fields.
Operation rejected	Inspect the Microsoft error, supported writable fields, group/calendar restrictions, recipient/license data, and file transfer limits.

See Entra connector introduction.