contacts

Creates, updates, deletes, gets or lists a contacts resource.

Overview

Name	contacts
Type	Resource
Id	entra_id.org_contacts.contacts

Fields

The following fields are returned by SELECT queries:

get

Retrieved entity

Name	Datatype	Description
id	string	The unique identifier for an entity. Read-only.
addresses	array	Postal addresses for this organizational contact. For now a contact can only have one physical address.
companyName	string	Name of the company that this organizational contact belongs to. Supports $filter (eq, ne, not, ge, le, in, startsWith, and eq for null values).
deletedDateTime	string (date-time)	Date and time when this object was deleted. Always null when the object hasn't been deleted. (pattern: ^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$)
department	string	The name for the department in which the contact works. Supports $filter (eq, ne, not, ge, le, in, startsWith, and eq for null values).
directReports	array	The contact's direct reports. (The users and contacts that have their manager property set to this contact.) Read-only. Nullable. Supports $expand.
displayName	string	Display name for this organizational contact. Maximum length is 256 characters. Supports $filter (eq, ne, not, ge, le, in, startsWith, and eq for null values), $search, and $orderby.
givenName	string	First name for this organizational contact. Supports $filter (eq, ne, not, ge, le, in, startsWith, and eq for null values).
jobTitle	string	Job title for this organizational contact. Supports $filter (eq, ne, not, ge, le, in, startsWith, and eq for null values).
mail	string	The SMTP address for the contact, for example, 'jeff@contoso.com'. Supports $filter (eq, ne, not, ge, le, in, startsWith, and eq for null values).
mailNickname	string	Email alias (portion of email address pre-pending the @ symbol) for this organizational contact. Supports $filter (eq, ne, not, ge, le, in, startsWith, and eq for null values).
manager		The user or contact that is this contact's manager. Read-only. Supports $expand and $filter (eq) by id.
memberOf	array	Groups that this contact is a member of. Read-only. Nullable. Supports $expand.
onPremisesLastSyncDateTime	string (date-time)	Date and time when this organizational contact was last synchronized from on-premises AD. This date and time information uses ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z. Supports $filter (eq, ne, not, ge, le, in). (pattern: ^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$)
onPremisesProvisioningErrors	array	List of any synchronization provisioning errors for this organizational contact. Supports $filter (eq, not for category and propertyCausingError), /$count eq 0, /$count ne 0.
onPremisesSyncBehavior
onPremisesSyncEnabled	boolean	true if this object is synced from an on-premises directory; false if this object was originally synced from an on-premises directory but is no longer synced and now mastered in Exchange; null if this object has never been synced from an on-premises directory (default). Supports $filter (eq, ne, not, in, and eq for null values).
phones	array	List of phones for this organizational contact. Phone types can be mobile, business, and businessFax. Only one of each type can ever be present in the collection.
proxyAddresses	array	For example: 'SMTP: bob@contoso.com', 'smtp: bob@sales.contoso.com'. The any operator is required for filter expressions on multi-valued properties. Supports $filter (eq, not, ge, le, startsWith, /$count eq 0, /$count ne 0).
serviceProvisioningErrors	array	Errors published by a federated service describing a non-transient, service-specific error regarding the properties or link from an organizational contact object . Supports $filter (eq, not, for isResolved and serviceInstance).
surname	string	Last name for this organizational contact. Supports $filter (eq, ne, not, ge, le, in, startsWith, and eq for null values).
transitiveMemberOf	array	Groups that this contact is a member of, including groups that the contact is nested under. Read-only. Nullable.

list

Retrieved collection

Name	Datatype	Description
id	string	The unique identifier for an entity. Read-only.
addresses	array	Postal addresses for this organizational contact. For now a contact can only have one physical address.
companyName	string	Name of the company that this organizational contact belongs to. Supports $filter (eq, ne, not, ge, le, in, startsWith, and eq for null values).
deletedDateTime	string (date-time)	Date and time when this object was deleted. Always null when the object hasn't been deleted. (pattern: ^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$)
department	string	The name for the department in which the contact works. Supports $filter (eq, ne, not, ge, le, in, startsWith, and eq for null values).
directReports	array	The contact's direct reports. (The users and contacts that have their manager property set to this contact.) Read-only. Nullable. Supports $expand.
displayName	string	Display name for this organizational contact. Maximum length is 256 characters. Supports $filter (eq, ne, not, ge, le, in, startsWith, and eq for null values), $search, and $orderby.
givenName	string	First name for this organizational contact. Supports $filter (eq, ne, not, ge, le, in, startsWith, and eq for null values).
jobTitle	string	Job title for this organizational contact. Supports $filter (eq, ne, not, ge, le, in, startsWith, and eq for null values).
mail	string	The SMTP address for the contact, for example, 'jeff@contoso.com'. Supports $filter (eq, ne, not, ge, le, in, startsWith, and eq for null values).
mailNickname	string	Email alias (portion of email address pre-pending the @ symbol) for this organizational contact. Supports $filter (eq, ne, not, ge, le, in, startsWith, and eq for null values).
manager		The user or contact that is this contact's manager. Read-only. Supports $expand and $filter (eq) by id.
memberOf	array	Groups that this contact is a member of. Read-only. Nullable. Supports $expand.
onPremisesLastSyncDateTime	string (date-time)	Date and time when this organizational contact was last synchronized from on-premises AD. This date and time information uses ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z. Supports $filter (eq, ne, not, ge, le, in). (pattern: ^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$)
onPremisesProvisioningErrors	array	List of any synchronization provisioning errors for this organizational contact. Supports $filter (eq, not for category and propertyCausingError), /$count eq 0, /$count ne 0.
onPremisesSyncBehavior
onPremisesSyncEnabled	boolean	true if this object is synced from an on-premises directory; false if this object was originally synced from an on-premises directory but is no longer synced and now mastered in Exchange; null if this object has never been synced from an on-premises directory (default). Supports $filter (eq, ne, not, in, and eq for null values).
phones	array	List of phones for this organizational contact. Phone types can be mobile, business, and businessFax. Only one of each type can ever be present in the collection.
proxyAddresses	array	For example: 'SMTP: bob@contoso.com', 'smtp: bob@sales.contoso.com'. The any operator is required for filter expressions on multi-valued properties. Supports $filter (eq, not, ge, le, startsWith, /$count eq 0, /$count ne 0).
serviceProvisioningErrors	array	Errors published by a federated service describing a non-transient, service-specific error regarding the properties or link from an organizational contact object . Supports $filter (eq, not, for isResolved and serviceInstance).
surname	string	Last name for this organizational contact. Supports $filter (eq, ne, not, ge, le, in, startsWith, and eq for null values).
transitiveMemberOf	array	Groups that this contact is a member of, including groups that the contact is nested under. Read-only. Nullable.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	org_contact_id		Get the properties and relationships of an organizational contact.
list	select		ConsistencyLevel	Get the list of organizational contacts for this organization.
update	update	org_contact_id
delete	delete	org_contact_id	If-Match
get_available_extension_properties	exec			Return all directory extension definitions that are registered in a directory, including through multitenant apps. The following entities support extension properties:
get_by_ids	exec			Return the directory objects specified in a list of IDs. Only a subset of user properties are returned by default in v1.0. Some common uses for this function are to:
validate_properties	exec			Validate that a Microsoft 365 group's display name or mail nickname complies with naming policies. Clients can use this API to determine whether a display name or mail nickname is valid before trying to create a Microsoft 365 group. To validate the properties of an existing group, use the group: validateProperties function. The following policy validations are performed for the display name and mail nickname properties: 1. Validate the prefix and suffix naming policy 2. Validate the custom banned words policy 3. Validate that the mail nickname is unique This API only returns the first validation failure that is encountered. If the properties fail multiple validations, only the first validation failure is returned. However, you can validate both the mail nickname and the display name and receive a collection of validation errors if you're only validating the prefix and suffix naming policy. To learn more about configuring naming policies, see Configure naming policy.
check_member_groups	exec	org_contact_id		Check for membership in a specified list of group IDs, and return from that list the IDs of groups where a specified object is a member. The specified object can be of one of the following types: - user - group - service principal - organizational contact - device - directory object This function is transitive. You can check up to a maximum of 20 groups per request. This function supports all groups provisioned in Microsoft Entra ID. Because Microsoft 365 groups cannot contain other groups, membership in a Microsoft 365 group is always direct.
check_member_objects	exec	org_contact_id
get_member_groups	exec	org_contact_id		Return all the group IDs for the groups that the specified user, group, service principal, organizational contact, device, or directory object is a member of. This function is transitive. This API returns up to 11,000 group IDs. If more than 11,000 results are available, it returns a 400 Bad Request error with the DirectoryResultSizeLimitExceeded error code. If you get the DirectoryResultSizeLimitExceeded error code, use the List group transitive memberOf API instead.
get_member_objects	exec	org_contact_id		Return all IDs for the groups, administrative units, and directory roles that an object of one of the following types is a member of: - user - group - service principal - organizational contact - device - directory object This function is transitive. Only users and role-enabled groups can be members of directory roles.
restore	exec	org_contact_id		Restore a recently deleted directory object from deleted items. The following types are supported: - administrativeUnit - application - agentIdentityBlueprint - agentIdentity - agentIdentityBlueprintPrincipal - agentUser - certificateBasedAuthPki - certificateAuthorityDetail - group - servicePrincipal - user If an item is accidentally deleted, you can fully restore the item. Additionally, restoring an application doesn't automatically restore the associated service principal automatically. You must call this API to explicitly restore the deleted service principal. A recently deleted item remains available for up to 30 days. After 30 days, the item is permanently deleted.
retry_service_provisioning	exec	org_contact_id		Retry the orgContact service provisioning.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
org_contact_id	string	The unique identifier of orgContact
ConsistencyLevel	string	Indicates the requested consistency level. Documentation URL: https://docs.microsoft.com/graph/aad-advanced-queries
If-Match	string	ETag

SELECT examples

get

Get the properties and relationships of an organizational contact.

SELECT
id,
addresses,
companyName,
deletedDateTime,
department,
directReports,
displayName,
givenName,
jobTitle,
mail,
mailNickname,
manager,
memberOf,
onPremisesLastSyncDateTime,
onPremisesProvisioningErrors,
onPremisesSyncBehavior,
onPremisesSyncEnabled,
phones,
proxyAddresses,
serviceProvisioningErrors,
surname,
transitiveMemberOf
FROM entra_id.org_contacts.contacts
WHERE org_contact_id = '{{ org_contact_id }}' -- required
;

list

Get the list of organizational contacts for this organization.

SELECT
id,
addresses,
companyName,
deletedDateTime,
department,
directReports,
displayName,
givenName,
jobTitle,
mail,
mailNickname,
manager,
memberOf,
onPremisesLastSyncDateTime,
onPremisesProvisioningErrors,
onPremisesSyncBehavior,
onPremisesSyncEnabled,
phones,
proxyAddresses,
serviceProvisioningErrors,
surname,
transitiveMemberOf
FROM entra_id.org_contacts.contacts
WHERE ConsistencyLevel = '{{ ConsistencyLevel }}'
;

UPDATE examples

update

No description available.

UPDATE entra_id.org_contacts.contacts
SET 
id = '{{ id }}',
deletedDateTime = '{{ deletedDateTime }}',
addresses = '{{ addresses }}',
companyName = '{{ companyName }}',
department = '{{ department }}',
displayName = '{{ displayName }}',
givenName = '{{ givenName }}',
jobTitle = '{{ jobTitle }}',
mail = '{{ mail }}',
mailNickname = '{{ mailNickname }}',
onPremisesLastSyncDateTime = '{{ onPremisesLastSyncDateTime }}',
onPremisesProvisioningErrors = '{{ onPremisesProvisioningErrors }}',
onPremisesSyncEnabled = {{ onPremisesSyncEnabled }},
phones = '{{ phones }}',
proxyAddresses = '{{ proxyAddresses }}',
serviceProvisioningErrors = '{{ serviceProvisioningErrors }}',
surname = '{{ surname }}',
directReports = '{{ directReports }}',
manager = '{{ manager }}',
memberOf = '{{ memberOf }}',
onPremisesSyncBehavior = '{{ onPremisesSyncBehavior }}',
transitiveMemberOf = '{{ transitiveMemberOf }}'
WHERE 
org_contact_id = '{{ org_contact_id }}' --required
RETURNING
id,
addresses,
companyName,
deletedDateTime,
department,
directReports,
displayName,
givenName,
jobTitle,
mail,
mailNickname,
manager,
memberOf,
onPremisesLastSyncDateTime,
onPremisesProvisioningErrors,
onPremisesSyncBehavior,
onPremisesSyncEnabled,
phones,
proxyAddresses,
serviceProvisioningErrors,
surname,
transitiveMemberOf;

DELETE examples

delete

No description available.

DELETE FROM entra_id.org_contacts.contacts
WHERE org_contact_id = '{{ org_contact_id }}' --required
AND If-Match = '{{ If-Match }}'
;

Lifecycle Methods

get_available_extension_properties

Return all directory extension definitions that are registered in a directory, including through multitenant apps. The following entities support extension properties:

EXEC entra_id.org_contacts.contacts.get_available_extension_properties 
@@json=
'{
"isSyncedFromOnPremises": {{ isSyncedFromOnPremises }}
}'
;

get_by_ids

Return the directory objects specified in a list of IDs. Only a subset of user properties are returned by default in v1.0. Some common uses for this function are to:

EXEC entra_id.org_contacts.contacts.get_by_ids 
@@json=
'{
"ids": "{{ ids }}", 
"types": "{{ types }}"
}'
;

validate_properties

Validate that a Microsoft 365 group's display name or mail nickname complies with naming policies. Clients can use this API to determine whether a display name or mail nickname is valid before trying to create a Microsoft 365 group. To validate the properties of an existing group, use the group: validateProperties function. The following policy validations are performed for the display name and mail nickname properties:
1. Validate the prefix and suffix naming policy
2. Validate the custom banned words policy
3. Validate that the mail nickname is unique This API only returns the first validation failure that is encountered. If the properties fail multiple validations, only the first validation failure is returned. However, you can validate both the mail nickname and the display name and receive a collection of validation errors if you're only validating the prefix and suffix naming policy. To learn more about configuring naming policies, see Configure naming policy.

EXEC entra_id.org_contacts.contacts.validate_properties 
@@json=
'{
"entityType": "{{ entityType }}", 
"displayName": "{{ displayName }}", 
"mailNickname": "{{ mailNickname }}", 
"onBehalfOfUserId": "{{ onBehalfOfUserId }}"
}'
;

check_member_groups

Check for membership in a specified list of group IDs, and return from that list the IDs of groups where a specified object is a member. The specified object can be of one of the following types:
- user
- group
- service principal
- organizational contact
- device
- directory object This function is transitive. You can check up to a maximum of 20 groups per request. This function supports all groups provisioned in Microsoft Entra ID. Because Microsoft 365 groups cannot contain other groups, membership in a Microsoft 365 group is always direct.

EXEC entra_id.org_contacts.contacts.check_member_groups 
@org_contact_id='{{ org_contact_id }}' --required 
@@json=
'{
"groupIds": "{{ groupIds }}"
}'
;

check_member_objects

Success

EXEC entra_id.org_contacts.contacts.check_member_objects 
@org_contact_id='{{ org_contact_id }}' --required 
@@json=
'{
"ids": "{{ ids }}"
}'
;

get_member_groups

Return all the group IDs for the groups that the specified user, group, service principal, organizational contact, device, or directory object is a member of. This function is transitive. This API returns up to 11,000 group IDs. If more than 11,000 results are available, it returns a 400 Bad Request error with the DirectoryResultSizeLimitExceeded error code. If you get the DirectoryResultSizeLimitExceeded error code, use the List group transitive memberOf API instead.

EXEC entra_id.org_contacts.contacts.get_member_groups 
@org_contact_id='{{ org_contact_id }}' --required 
@@json=
'{
"securityEnabledOnly": {{ securityEnabledOnly }}
}'
;

get_member_objects

Return all IDs for the groups, administrative units, and directory roles that an object of one of the following types is a member of:
- user
- group
- service principal
- organizational contact
- device
- directory object This function is transitive. Only users and role-enabled groups can be members of directory roles.

EXEC entra_id.org_contacts.contacts.get_member_objects 
@org_contact_id='{{ org_contact_id }}' --required 
@@json=
'{
"securityEnabledOnly": {{ securityEnabledOnly }}
}'
;

restore

Restore a recently deleted directory object from deleted items. The following types are supported:
- administrativeUnit
- application
- agentIdentityBlueprint
- agentIdentity
- agentIdentityBlueprintPrincipal
- agentUser
- certificateBasedAuthPki
- certificateAuthorityDetail
- group
- servicePrincipal
- user If an item is accidentally deleted, you can fully restore the item. Additionally, restoring an application doesn't automatically restore the associated service principal automatically. You must call this API to explicitly restore the deleted service principal. A recently deleted item remains available for up to 30 days. After 30 days, the item is permanently deleted.

EXEC entra_id.org_contacts.contacts.restore 
@org_contact_id='{{ org_contact_id }}' --required
;

retry_service_provisioning

Retry the orgContact service provisioning.

EXEC entra_id.org_contacts.contacts.retry_service_provisioning 
@org_contact_id='{{ org_contact_id }}' --required
;