Help Center/ Organizations/ API Reference/ APIs/ Managing Invitations/ Getting Invitation Information

Updated on 2025-10-16 GMT+08:00

View PDF

Getting Invitation Information

Function

This API is used to get the information about existing invitations in an organization.

It can be called by all accounts in an organization.

URI

GET /v1/organizations/handshakes/{handshake_id}

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
handshake_id	Yes	String	Unique ID of an invitation. The originating account creates the ID when initiating the invitation.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Security-Token	No	String	Security token (session token) of your temporary security credentials. If a temporary security credential is used, this header is required.

Response Parameters

Status code: 200

**Table 3** Response body parameters
Parameter	Type	Description
handshake	HandshakeDto object	Information to be exchanged between two accounts (sender and receiver) for establishing a secure relationship. For example, when a management account (the sender) invites another account (the receiver) to join its organization, the two accounts exchange information as a series of invitation (handshake) requests and responses, which are contained in this structure.

**Table 4** HandshakeDto
Parameter	Type	Description
id	String	Unique ID of an invitation (handshake). The originating account creates the ID when initiating the invitation (handshake).
urn	String	Uniform resource name of the invitation (handshake).
updated_at	String	Date and time when an invitation (handshake) request was accepted, canceled, declined, or expired.
created_at	String	Date and time when an invitation (handshake) request was made.
expired_at	String	The date and time the invitation (handshake) expires.
management_account_id	String	Unique ID of the organization's management account.
management_account_name	String	Name of the organization's management account.
organization_id	String	Unique ID of an organization.
notes	String	Additional information that you want to include in the email to the recipient account owner.
target	TargetDto object	ID of the account that you want to invite to join your organization.
status	String	Current state of the invitation (handshake). It can be pending, accepted, cancelled, declined, or expired.

**Table 5** TargetDto
Parameter	Type	Description
type	String	Target type. It can be account ID or name.
entity	String	If you choose type:account, you must provide the account ID. If you choose type:name, you must specify the account name.

Example Requests

Getting invitation information

GET /v1/organizations/handshakes/{handshake_id}

Example Responses

Status code: 200

Successful.

{
  "handshake" : {
    "id" : "h-awjp43m7bz3b8jgy5v61jrfwakt3og8w",
    "urn" : "organizations::0a6d25d23900d45c0faac010e0fb4de0:handshake:o-fhkmi6mek7wlqdp6nideqhb47qwtjdsv/h-awjp43m7bz3b8jgy5v61jrfwakt3og8w",
    "updated_at" : "2022-08-25T08:11:53Z",
    "created_at" : "2022-08-25T08:11:20Z",
    "expired_at" : "2022-09-08T08:11:20Z",
    "management_account_id" : "0a6d25d23900d45c0faac010e0fb4de0",
    "management_account_name" : "paas_iam_573331",
    "organization_id" : "o-fhkmi6mek7wlqdp6nideqhb47qwtjdsv",
    "notes" : "test-notes",
    "target" : {
      "type" : "account",
      "entity" : "05c734152f00d4200f2bc0179ac6c5e0"
    },
    "status" : "pending"
  }
}