Please ensure Javascript is enabled for purposes of website accessibility
Powered by Zoomin Software. For more details please contactZoomin

CONNECT data services developer documentation

TABLE OF CONTENTS

Community Invitations

Save PDF
Save selected topicSave selected topic and subtopicsSave all topics
Share
Share to emailCopy topic URL
  • Last UpdatedJan 20, 2023
  • 7 minute read

Defines the public API methods that are used to manage community invitations. Using this API you can, for example, create, retrieve, update and process invitations. You can also resend an invitation email.

List a Community Invitation by issuing Tenant and Community

Get invitations associated with a specific issuing tenant and community.

Request

GET /api/v1-preview/communities/{communityId}/invitations
?query={query}&skip={skip}&count={count}

Parameters

string communityId
The identifier of the community to which the recipient of the invitation is being invited.

[optional] string query
(not supported) Search string identifier

[optional] integer skip
Parameter representing the zero-based offset of the first object to retrieve. If unspecified, a default value of 0 is used.

[optional] integer count
Parameter representing the maximum number of objects to retrieve. If unspecified, a default value of 100 is used.

Response

Status Code Body Type Description
200 CommunityInvitation[] Set of Invitations (type CommunityInvitation) associated with the issuing tenant and community ( communityId)
400 ErrorResponse Bad Request. The server could not understand the request.
401 ErrorResponse Unauthorized. The client has not been authenticated.
403 ErrorResponse Forbidden. The client does not have the required permissions to make the request.
404 ErrorResponse Not Found. The requested item was not found.
408 ErrorResponse Request Timeout. The request has timed out.
500 ErrorResponse Internal Server Error. The server has encountered a situation it does not know how to handle.

Example response body

200 Response (CommunityInvitation[])

[
  {
    "Id": "string",
    "Issued": "2019-08-24T14:15:22Z",
    "Expires": "2019-08-24T14:15:22Z",
    "Accepted": "2019-08-24T14:15:22Z",
    "State": "None",
    "IssuingTenantId": "string",
    "InvitedTenantId": "string",
    "CommunityId": "string",
    "CommunityName": "string",
    "InvitationRecipient": "string",
    "AcceptedUserEmail": "string",
    "AcceptedTenantName": "string"
  }
]

Create a Community Invitation

Creates a community invitation for a specific community.

Request

POST /api/v1-preview/communities/{communityId}/invitations

Parameters

string communityId
Community identifier.

Request Body

Invitation to create.

{
  "InvitationRecipient": "user@example.com"
}

Response

Status Code Body Type Description
201 CommunityInvitation Returns the created invitation of type CommunityInvitation
400 ErrorResponse Bad Request. The server could not understand the request.
401 ErrorResponse Unauthorized. The client has not been authenticated.
403 ErrorResponse Forbidden. The client does not have the required permissions to make the request.
404 ErrorResponse Not Found. The requested item was not found.
408 ErrorResponse Request Timeout. The request has timed out.
500 ErrorResponse Internal Server Error. The server has encountered a situation it does not know how to handle.

Example response body

201 Response (CommunityInvitation)

{
  "Id": "string",
  "Issued": "2019-08-24T14:15:22Z",
  "Expires": "2019-08-24T14:15:22Z",
  "Accepted": "2019-08-24T14:15:22Z",
  "State": "None",
  "IssuingTenantId": "string",
  "InvitedTenantId": "string",
  "CommunityId": "string",
  "CommunityName": "string",
  "InvitationRecipient": "string",
  "AcceptedUserEmail": "string",
  "AcceptedTenantName": "string"
}

Get a Community Invitation by Tenant, Community, and Id

Gets a community invitation by Id.

Request

GET /api/v1-preview/communities/{communityId}/invitations/{invitationId}

Parameters

string communityId
Community identifier.

string invitationId
Invitation identifier.

Response

Status Code Body Type Description
200 CommunityInvitation Returns the invitation of type CommunityInvitation
400 ErrorResponse Bad Request. The server could not understand the request.
401 ErrorResponse Unauthorized. The client has not been authenticated.
403 ErrorResponse Forbidden. The client does not have the required permissions to make the request.
404 ErrorResponse Not Found. The requested item was not found.
408 ErrorResponse Request Timeout. The request has timed out.
500 ErrorResponse Internal Server Error. The server has encountered a situation it does not know how to handle.

Example response body

200 Response (CommunityInvitation)

{
  "Id": "string",
  "Issued": "2019-08-24T14:15:22Z",
  "Expires": "2019-08-24T14:15:22Z",
  "Accepted": "2019-08-24T14:15:22Z",
  "State": "None",
  "IssuingTenantId": "string",
  "InvitedTenantId": "string",
  "CommunityId": "string",
  "CommunityName": "string",
  "InvitationRecipient": "string",
  "AcceptedUserEmail": "string",
  "AcceptedTenantName": "string"
}

Delete a Community Invitation

Deletes a community invitation by invitation identifier.

Request

DELETE /api/v1-preview/communities/{communityId}/invitations/{invitationId}

Parameters

string communityId
Community identifier

string invitationId
Invitation identifier

Response

Status Code Body Type Description
204 None No Content. The invitation has been deleted.
400 ErrorResponse Bad Request. The server could not understand the request.
401 ErrorResponse Unauthorized. The client has not been authenticated.
403 ErrorResponse Forbidden. The client does not have the required permissions to make the request.
404 ErrorResponse Not Found. The requested item was not found.
408 ErrorResponse Request Timeout. The request has timed out.
500 ErrorResponse Internal Server Error. The server has encountered a situation it does not know how to handle.

Get details of an Invitation

Gets details for a community invitation.

Request

GET /api/v1-preview/communityinvitations/{invitationId}/details

Parameters

string invitationId
Invitation identifier

Response

Status Code Body Type Description
200 CommunityInvitationDetails The CommunityInvitationDetails
400 ErrorResponse Bad Request. The server could not understand the request.
401 ErrorResponse Unauthorized. The client has not been authenticated.
403 ErrorResponse Forbidden. The client does not have the required permissions to make the request.
404 ErrorResponse Not Found. The requested item was not found.
408 ErrorResponse Request Timeout. The request has timed out.
500 ErrorResponse Internal Server Error. The server has encountered a situation it does not know how to handle.

Example response body

200 Response (CommunityInvitationDetails)

{
  "CommunityName": "string",
  "CommunityId": "string",
  "InvitationState": "None",
  "ContactEmail": "string"
}

Process a Community Invitation Based on the Requested Action

Processes an action against a particular community invitation. The available actions include accept, decline and resend. For the accept action, tenant's contact email should be provided as a point of contact for the community users.

Request

PUT /api/v1-preview/communityinvitations/{invitationId}

Parameters

string invitationId
Invitation identifier

Request Body

Invitation action

{
  "Action": "Accept",
  "ContactEmail": "user@example.com"
}

Response

Status Code Body Type Description
200 None Created. The invitation was processed.
202 None Accepted. The invitation action was processed and the notification accepted.
400 ErrorResponse Bad Request. The server could not understand the request.
401 ErrorResponse Unauthorized. The client has not been authenticated.
403 ErrorResponse Forbidden. The client does not have the required permissions to make the request.
404 ErrorResponse Not Found. The requested item was not found.
408 ErrorResponse Request Timeout. The request has timed out.
500 ErrorResponse Internal Server Error. The server has encountered a situation it doesn't know how to handle.

List Accepted Community Invitations by Tenant

Gets invitations associated with a specific invited tenant. Only invitations in the accepted state are returned. Using this method, you can identify the communities to which a tenant has been invited by means of the returned CommunityInvitation.CommunityId attribute.

Request

GET /api/v1-preview/tenants/{tenantId}/communityinvitations
?query={query}&skip={skip}&count={count}

Parameters

string tenantId
Tenant identifier

[optional] string query
(not supported) Search string identifier

[optional] integer skip
Parameter representing the zero-based offset of the first object to retrieve. If unspecified, a default value of 0 is used.

[optional] integer count
Parameter representing the maximum number of objects to retrieve. If unspecified, a default value of 100 is used.

Response

Status Code Body Type Description
200 CommunityInvitation[] Set of accepted invitations (type CommunityInvitation) associated with the issuing tenant ( tenantId)
400 ErrorResponse Bad Request. The server could not understand the request.
401 ErrorResponse Unauthorized. The client has not been authenticated.
403 ErrorResponse Forbidden. The client does not have the required permissions to make the request.
404 ErrorResponse Not Found. The requested item was not found.
408 ErrorResponse Request Timeout. The request has timed out.
500 ErrorResponse Internal Server Error. The server has encountered a situation it does not know how to handle.

Example response body

200 Response (CommunityInvitation[])

[
  {
    "Id": "string",
    "Issued": "2019-08-24T14:15:22Z",
    "Expires": "2019-08-24T14:15:22Z",
    "Accepted": "2019-08-24T14:15:22Z",
    "State": "None",
    "IssuingTenantId": "string",
    "InvitedTenantId": "string",
    "CommunityId": "string",
    "CommunityName": "string",
    "InvitationRecipient": "string",
    "AcceptedUserEmail": "string",
    "AcceptedTenantName": "string"
  }
]

Definitions

CommunityInvitation

Representation of the community invitation

Properties

Property Name Data Type Required Nullable Description
Id guid false false Invitation identifier
Issued date-time false false Invitation issued timestamp
Expires date-time false false Invitation expiration timestamp
Accepted date-time false true Invitation accepted timestamp
State CommunityInvitationState false false Invitation state
IssuingTenantId guid false false Identifier of the tenant that issued the invitation
InvitedTenantId guid false true Identifier of the tenant that is invited
CommunityId guid false false Identifier of the community from which the invitation was issued
CommunityName string false true Name of the community from which the invitation was issued
InvitationRecipient string false true Email address of the recipient who will be notified to accept the invitation
AcceptedUserEmail string false true Email address of the recipient who accepts the invitation
AcceptedTenantName string false true Name of the tenant accepting the invitation 
{
  "Id": "string",
  "Issued": "2019-08-24T14:15:22Z",
  "Expires": "2019-08-24T14:15:22Z",
  "Accepted": "2019-08-24T14:15:22Z",
  "State": "None",
  "IssuingTenantId": "string",
  "InvitedTenantId": "string",
  "CommunityId": "string",
  "CommunityName": "string",
  "InvitationRecipient": "string",
  "AcceptedUserEmail": "string",
  "AcceptedTenantName": "string"
}

CommunityInvitationState

Enum for Community invitation state.

Enumerated Values

Property Value Description
None None Enum for Community invitation state.
InvitationCreated InvitationCreated Enum for Community invitation state.
InvitationAccepted InvitationAccepted Enum for Community invitation state.
InvitationDeclined InvitationDeclined Enum for Community invitation state.
InvitationExpired InvitationExpired Enum for Community invitation state.
InvitationCompleted InvitationCompleted Enum for Community invitation state.

ErrorResponse

Object returned whenever there is an error

Properties

Property Name Data Type Required Nullable Description
OperationId string true false Operation identifier of action that caused the error
Error string true false Error description
Reason string true false Reason for the error
Resolution string true false Resolution to resolve the error
DynamicProperties object false true Additional properties 
{
  "OperationId": "string",
  "Error": "string",
  "Reason": "string",
  "Resolution": "string",
  "DynamicProperties": {
    "property1": null,
    "property2": null
  },
  "property1": null,
  "property2": null
}

CreateInvitationInput

The input object to create invitation

Properties

Property Name Data Type Required Nullable Description
InvitationRecipient email false true The email address of the invitation recipient 
{
  "InvitationRecipient": "user@example.com"
}

CommunityInvitationDetails

Summary of a community invitation

Properties

Property Name Data Type Required Nullable Description
CommunityName string false true Community name
CommunityId guid false false Community identifier
InvitationState CommunityInvitationState false false Invitation state
ContactEmail string false true An arbitrary email address provided as the community tenant's point of contact. 
{
  "CommunityName": "string",
  "CommunityId": "string",
  "InvitationState": "None",
  "ContactEmail": "string"
}

ProcessInvitationInput

The input object to process invitation

Properties

Property Name Data Type Required Nullable Description
Action ProcessInvitationAction false false Action to take on invitation
ContactEmail email false true An arbitrary email address provided as the community tenant's point of contact. 
{
  "Action": "Accept",
  "ContactEmail": "user@example.com"
}

ProcessInvitationAction

Enumeration of actions taken on community invitations

Enumerated Values

Property Value Description
Accept Accept Enumeration of actions taken on community invitations
Decline Decline Enumeration of actions taken on community invitations
Confirm Confirm Enumeration of actions taken on community invitations
Resend Resend Enumeration of actions taken on community invitations
In This Topic
Related Links
TitleResults for “How to create a CRG?”Also Available in