Create a platform invitation

Creating a platform invitation exists to serve legacy applications. This call creates an invitation for the Trimble ecosystem invitation. This applies to portals that manage multiple entitlements simultaneously.

Request

POST {base URL}/platform-invitation/

• HEADER:

  • Include TID OAuth Bearer token for your application

  • Add a Content-Type of application/JSON.

• PARAMETERS:

  • send_email: {Query parameter accepts boolean value to raise or suppress email notification. This value is optional and default value is true.}

• BODY: (See example below)

  • invite_email_address: {The email address of person being invited}

  • email_variables: {Variables from selected template}

  • invitee_name: {Name of the person receiving the invitation}

  • product_name: {Name of the product person is invited to}

  • webhook_secret_token: {Random string used to verify the client webhook is invoked}

  • invitation_accepted_webhook: {URL of a callback webhook. Address must be HTTPS endpoint of an authorized subdomain.}

  • error_webhook: {URL of a callback webhook}

  • metadata_json: {JSON metadata to return to client when invoking the webhook. This value is optional.}

  • search_tag: {A tag that can be used to query invitations on the GET endpoint. This value is optional.}

  • entitlement_activation_ids: {This value is an array of up to 10 TRNs that correspond to Entitlements v3 activations. This value is optional.}

  • entitlement_roles: {Represents the Account Master (CDH) roles associated with this invitation. This value is optional.}

  • account_id: {Account ID for the customer for role assignment.}

  • role: {Role the person receiving the invitation will have in Account Master (CDH).}

  • invitation_expiry_days: {Days until invitation expires. Supported values are between 1 and 60. The default value is 30 days.}

  • locale: {Local language for person receiving the invitation. See list of locales for languages here.}

Example request body

{
    "invite_email_address": "jane_example@examplecorp.com",
    "email_variables": {
        "invitee_name": "Jane Example",
        "inviter_name": "invitations@tekla.com",
    },
    "webhook_secret_token": "4316299750",
    "invitation_accepted_webhook": "https://www.example.trimblecloud.com/landing_page",
    "error_webhook": "https://www.example.trimblecloud.com/error_link/",
    "metadata_json": {
        "optional_object"
        },
    "search_tag": "example",
    "entitlement_activation_ids": "optional_TRN_array, optional_TRN_array",
    "entitlement_roles": {
        "account_id": "account_id_string",
        "role": "role_to_assign",
    },
    "invitation_expiry_days": "60",
    "locale":"en-US",
}

Example response

The status code 201 indicates that the request is successful and the invitation_id is returned in the response.

{
    "invitation_id": "ad8c2590-1888-4ae6-b1ee-4ca26b6c470b"
}

Error handling

If there is any error while updating the entitlement_activation_ids or entitlement_roles in Entitlements, the status code 207 is returned along with the error details and invitation_id in the response body. Refer to the following example for details.

{

    "invitation_id": "ad8c2590-1888-4ae6-b1ee-4ca26b6c470b",
    "orchestration_error": [
        {
            "system": "EMS",
            "element": "TRN_activation_id",
            "message": "Error received from entitlements API. Invalid activation id.",
            "operation": "Assign Activation",
            "error_code": "400"
        }

    ]
}

The operation attribute value displayed under orchestration_error message can display either Assign Activation or Assign Role.

If a user already exists you will receive a response of 204 No Content. This triggers the invitation_accepted_webhook with the user ID.