Skip to content
Invitation Service

Create a user invitation

Trimble Invitation Service enables clients to create an invitation for their users. Clients provide the following information:

  • Invitation recipient details

  • Template variable values

  • A webhook to invoke when the invitee accepts

  • A search_tag value to refine queries on existing invitations

Webhook Validation

Webhooks used in an invitation must be within authorized sub-domains. The authorized sub-domains include:

  • trimble.com

  • trimblecloud.com

  • trimble.cloud

  • trimblegeospatial.com

  • trimblepaas.com

  • frame-oesolutions.com

  • trimbletl.com

  • loadhaulmanager.com

  • trimbleag.com

  • trimbleplatform.com

  • connectedclimateexchange.com

  • mepdevelopment.com

  • trimbleag.team

  • viewpointplatform.com

  • tradeservice.com

If you need to add a new domain to the list of authorized subdomains, please contact L4 Support for assistance.

Error and expiration handling

The Invitation service will invoke a webhook if the service encounters an error handling a user’s login or a user’s invitation expires. This webhook, error_webhook invocation, includes the metadata associated with the invitation. To read more, please see Webhook Errors.

Request

POST {base URL}/invitation

  • HEADER:

    • Include TID OAuth Bearer token for your application

    • Add a Content-Type of application/JSON.

  • PARAMETERS:

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

  • BODY: (See example below)

    • invite_email_address: The email aaddress of the person being invited.

    • email_variables: Variables from selected template

    • invitee_name: Name of the person receiving the invitation

    • product_name: Name of the product that the person is invited to

    • inviter_name: Name of the person sending the invitation. This field defaults to the inviter’s email address. This value is optional.

    • 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 the client when invoking the webhook. This value is optional.

    • search_tag: A tag 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 preference of the person receiving the invitation. See list of locales for languages here.

    • custom_templates: Customized templates for sending invitations. This value is optional.

The provided template needs to include a variable invitation_url which will be overridden with the invite_link.

Example request body

{
    "invite_email_address": "jane_example@examplecorp.com",
    "email_variables": {
        "invitee_name": "Jane Example",
        "product_name": "Tekla",
        "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",
    "custom_templates": {
    "new_user": {
    "template_id": "template_id_1",
    "variables": { "variable_1": "value_1", "variable_2": "value_2" }
    },
    "existing_user": {
    "template_id": "template_id_2",
    "variables": { "variable_1": "value_1", "variable_2": "value_2" }
    }
    }
}

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.