Skip to content
Invitation Service

Create user invitations in bulk

To create user invitations in bulk, please use the following API call. Invitations submitted using this bulk API call will be created asynchronously in the backend. Upon basic validation of individual invitation requests, the request will be accepted and invitation_id for each valid invitation will be sent in the response for tracking the status. It might take a few seconds to create the invitation and the client should poll the GET invitation API to obtain the final status of an invitation request sent via bulk API.

Request

POST {base URL}/invitation/bulk

  • HEADER:

    • Include TID OAuth Bearer token for your application

    • Add a Content-Type of application/JSON.

  • BODY: (See example below)

    • [<invitation-request-1>,...,<invitation-request-n>]: The invitation request array. limited to maximum of 100.

The parameters for the invitation-request is same as creating a single invitation mentioned in (Create a user invitation)

Example request body

{
  {
    "invite_email_address": "jane@example.com",
    "email_variables": {
      "invitee_name": "Jane",
      "product_name": "Tekla",
      "inviter_name": "invitations@tekla.com",
    },
    "webhook_secret_token": "4316299750",
    "invitation_accepted_webhook": "https://www.example.trimblecloud.com/accept_link",
    "error_webhook": "https://www.example.trimblecloud.com/error_link",
    "metadata_json": {
      "key1": "value1",
      "key2": "value2"
    },
    "search_tag": "example",
    "entitlement_activation_ids": ["activation_TRN_1", "activation_TRN_2"]
    "entitlement_roles": {
      "account_id": "account_id_string",
      "role": "role_to_assign",
    },
    "invitation_expiry_days": 60,
    "locale":"en-US"
  },
  {
    "invite_email_address": "smith@example.com",
    "email_variables": {
      "invitee_name": "Smith",
      "product_name": "Tekla",
      "inviter_name": "invitations@tekla.com",
    },
    "webhook_secret_token": "6432689432",
    "invitation_accepted_webhook": "https://www.example.trimblecloud.com/accept_link",
    "error_webhook": "https://www.example.trimblecloud.com/error_link",
    "metadata_json": {
      "key1": "value1",
      "key2": "value2"
    },
    "search_tag": "example",
    "entitlement_activation_ids": ["activation_TRN_1", "activation_TRN_2"]
    "entitlement_roles": {
      "account_id": "account_id_string",
      "role": "role_to_assign",
    },
    "invitation_expiry_days": 60,
    "locale":"en-US"
  }
}

Example response

The overall status code 200 indicates that the request is successful. However the status of each invitation can be obtained from the items array in the response (in the same order as the request). The individual invitation status code 202 indicates that the request is accepted and invitation_id is sent in the response. Please note that the creation of invitations may take a few seconds. The status code 400 indicates that the specific invitation has a validation error and the corresponding error message is provided in the message attribute.

{
  "items": [
    {
      "status_code": 202,
      "message": "accepted",
      "invitation_id": "ace4f39f2f8240159dca2dea3b117acd",
      "invite_email_address": "jane@example.com"
    },
    {
      "status_code": 400,
      "message": "not a valid email address",
      "invite_email_address": "bruce#example.com"
    }
  ]
}

The final status of an invitation created using the bulk API can be obtained from (Find an invitation using invitation_id).