organizationRelationships

Organization Relationships. Cross-org relationships for sharing free/busy and federation. The organizationRelationships entity set lives under /exchange/v1.0/organizationRelationships in the Sharing & federation category.

Fact	Value
Path	/exchange/v1.0/organizationRelationships
Category	Sharing & federation
Tier	Tier 3, Mail flow
Read role	MailFlow.Read.All (Community)
Write role	MailFlow.ReadWrite.All (Pro)
Backing cmdlets	Get-OrganizationRelationship, Set-OrganizationRelationship, New-OrganizationRelationship, Remove-OrganizationRelationship

Routes

Method	Path	Synopsis	Role	Plan
GET	/exchange/v1.0/organizationRelationships	List organizationRelationships entries.	MailFlow.Read	Community
POST	/exchange/v1.0/organizationRelationships	Create a new organizationRelationships entry. Body keys map 1:1 to the cmdlet’s parameter names (camelCased). Returns 201 + Location + the freshly-fetched entity. Use ?dryRun=true to map to -WhatIf without applying.	MailFlow.ReadWrite	Pro
GET	/exchange/v1.0/organizationRelationships/{key}	Get a single organizationRelationships entry by Identity.	MailFlow.Read	Community
PATCH	/exchange/v1.0/organizationRelationships/{key}	Partial update of the organizationRelationships at /organizationRelationships/{key}. Only body fields present are passed to the cmdlet. Returns 200 + the post-Set entity (rename-aware re-fetch when name is in the body).	MailFlow.ReadWrite	Pro
DELETE	/exchange/v1.0/organizationRelationships/{key}	Remove the organizationRelationships at /organizationRelationships/{key}. Returns 204 with no body.	MailFlow.ReadWrite	Pro

GET /exchange/v1.0/organizationRelationships

List organizationRelationships entries.

Backing cmdlet: Get-OrganizationRelationship. Role: MailFlow.Read (Community).

List organizationRelationships

Stub auto-generated example for the organizationRelationships collection. Backing cmdlet: Get-OrganizationRelationship. Live-verify with ?$top=3&$select=Id,Name and replace the synthetic body before promoting to Tier 1.

GET /exchange/v1.0/organizationRelationships?$top=3 HTTP/1.1
Authorization: Bearer {token}

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#organizationRelationships",
  "value": []
}

Notes: Illustrative example derived from the cmdlet documentation, not a live capture: field names are real, values are placeholders.

Related: GET /exchange/v1.0/organizationRelationships/{key}

POST /exchange/v1.0/organizationRelationships

Create a new organizationRelationships entry. Body keys map 1:1 to the cmdlet’s parameter names (camelCased). Returns 201 + Location + the freshly-fetched entity. Use ?dryRun=true to map to -WhatIf without applying.

Backing cmdlet: New-OrganizationRelationship. Role: MailFlow.ReadWrite (Pro).

Parameter	In	Type	Required	Description
domainNames	body		yes
name	body		yes
archiveAccessEnabled	body
deliveryReportEnabled	body
enabled	body
freeBusyAccessEnabled	body
freeBusyAccessLevel	body
freeBusyAccessScope	body
mailboxMoveCapability	body
mailboxMoveEnabled	body
mailboxMovePublishedScopes	body
mailTipsAccessEnabled	body
mailTipsAccessLevel	body
mailTipsAccessScope	body
oAuthApplicationId	body
organizationContact	body
photosEnabled	body
targetApplicationUri	body
targetAutodiscoverEpr	body
targetOwaURL	body
targetSharingEpr	body
dryRun	query	bool (switch)

Create fails when required fields are missing

New-OrganizationRelationship requires both name and domainNames. Omitting domainNames returns a 400 BadRequest envelope before the cmdlet is invoked.

POST /exchange/v1.0/organizationRelationships HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "exonaut-sample-organizationRelationships"
}

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "code": "BadRequest",
    "message": "The required field 'domainNames' is missing from the request body.",
    "target": "domainNames"
  },
  "correlationId": "0HN7K2C3D4E5F-00000001"
}

Notes: Doc-derived from Wiki + write-param allowlist; not live-captured. Body fields are Wiki-valid; values are illustrative.

Related: GET /exchange/v1.0/organizationRelationships

Create an organization relationship

Creates a federated sharing organization relationship via New-OrganizationRelationship. Returns 201 with a Location header and the freshly-fetched entity.

POST /exchange/v1.0/organizationRelationships HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "exonaut-sample-organizationRelationships",
  "domainNames": [
    "contoso.com"
  ],
  "enabled": true,
  "freeBusyAccessEnabled": true,
  "freeBusyAccessLevel": "LimitedDetails",
  "mailTipsAccessEnabled": true,
  "organizationContact": "[email protected]",
  "targetApplicationUri": "outlook.com",
  "targetAutodiscoverEpr": "https://autodiscover.contoso.com/autodiscover/autodiscover.svc/wssecurity"
}

HTTP/1.1 201 Created
Location: /exchange/v1.0/organizationRelationships/exonaut-sample-organizationRelationships

{
  "Id": "exonaut-sample-organizationRelationships",
  "Identity": "exonaut-sample-organizationRelationships",
  "Name": "exonaut-sample-organizationRelationships",
  "DomainNames": [
    "contoso.com"
  ],
  "Enabled": true,
  "FreeBusyAccessEnabled": true,
  "FreeBusyAccessLevel": "LimitedDetails",
  "MailTipsAccessEnabled": true,
  "OrganizationContact": "[email protected]",
  "TargetApplicationUri": "outlook.com"
}

Notes: Doc-derived from Wiki + write-param allowlist; not live-captured. Body fields are Wiki-valid; values are illustrative.

Related: GET /exchange/v1.0/organizationRelationships

GET /exchange/v1.0/organizationRelationships/{key}

Get a single organizationRelationships entry by Identity.

Backing cmdlet: Get-OrganizationRelationship. Role: MailFlow.Read (Community).

Get a single organizationRelationships entry

Stub auto-generated example for GET /organizationRelationships/{key}. Backing cmdlet: Get-OrganizationRelationship with -Identity {key}. Returns the full entity body; 404 if the identity doesn’t resolve.

GET /exchange/v1.0/organizationRelationships/{key} HTTP/1.1
Authorization: Bearer {token}

HTTP/1.1 200 OK

{
  "@odata.context": "http://localhost:5043/exchange/v1.0/$metadata#organizationRelationships/$entity"
}

Notes: Illustrative example derived from the cmdlet documentation, not a live capture: field names are real, values are placeholders.

Related: GET /exchange/v1.0/organizationRelationships

PATCH /exchange/v1.0/organizationRelationships/{key}

Partial update of the organizationRelationships at /organizationRelationships/{key}. Only body fields present are passed to the cmdlet. Returns 200 + the post-Set entity (rename-aware re-fetch when name is in the body).

Backing cmdlet: Set-OrganizationRelationship. Role: MailFlow.ReadWrite (Pro).

Parameter	In	Type	Required	Description
archiveAccessEnabled	body
deliveryReportEnabled	body
domainNames	body
enabled	body
freeBusyAccessEnabled	body
freeBusyAccessLevel	body
freeBusyAccessScope	body
mailboxMoveCapability	body
mailboxMoveEnabled	body
mailboxMovePublishedScopes	body
mailTipsAccessEnabled	body
mailTipsAccessLevel	body
mailTipsAccessScope	body
name	body
oAuthApplicationId	body
organizationContact	body
photosEnabled	body
targetApplicationUri	body
targetAutodiscoverEpr	body
targetOwaURL	body
targetSharingEpr	body
dryRun	query	bool (switch)

Update an organization relationship

Partially updates a federated sharing organization relationship via Set-OrganizationRelationship. Only the supplied body fields are passed to the cmdlet; returns 200 with the post-Set entity.

PATCH /exchange/v1.0/organizationRelationships/{key} HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

{
  "freeBusyAccessLevel": "AvailabilityOnly",
  "mailTipsAccessEnabled": false,
  "enabled": true
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "Id": "exonaut-sample-organizationRelationships",
  "Identity": "exonaut-sample-organizationRelationships",
  "Name": "exonaut-sample-organizationRelationships",
  "DomainNames": [
    "contoso.com"
  ],
  "Enabled": true,
  "FreeBusyAccessEnabled": true,
  "FreeBusyAccessLevel": "AvailabilityOnly",
  "MailTipsAccessEnabled": false
}

Notes: Doc-derived from Wiki + write-param allowlist; not live-captured. Body fields are Wiki-valid; values are illustrative.

Related: GET /exchange/v1.0/organizationRelationships

DELETE /exchange/v1.0/organizationRelationships/{key}

Remove the organizationRelationships at /organizationRelationships/{key}. Returns 204 with no body.

Backing cmdlet: Remove-OrganizationRelationship. Role: MailFlow.ReadWrite (Pro).

Parameter	In	Type	Required	Description
dryRun	query	bool (switch)

Delete an organization relationship

Removes a federated sharing organization relationship via Remove-OrganizationRelationship. Returns 204 with no body.

DELETE /exchange/v1.0/organizationRelationships/{key} HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json

HTTP/1.1 204 No Content

Notes: Doc-derived from Wiki + write-param allowlist; not live-captured. Body fields are Wiki-valid; values are illustrative.

Related: GET /exchange/v1.0/organizationRelationships

?dryRun=true previews of any write stay on Community.