Create an Account

How to Create an Account

1. Subscribe to IAM

• You must have the account-provisioner role, see Becoming a Trusted Account Data Source

• Using the client credentials auth flow, you can create an account using the POST /accounts API. The request body below shows the minimum required fields for creating an account:
  

  {
      "name": "my-name",
      "type": "customer" | "dealer" | "distributor" | "reseller",
      "customerType": "enterprise" | "individual" | "organization",
      "externalSystems": {
          "sourceSystem": {
              "refId": "account-id-in-system-of-reference",
              "id": "iam-id-of-system-of-reference"
          },
      }
  }

• How to add source system/external reference identifier.

  • Since external systems are static in IAM, to add a new reference, call the following endpoint:
    PUT /accounts/{accountId}/externalSystems/references/{externalSystemId} and give it a payload of the refId.
  • Adding a new external system that does not exist in IAM would require a manual review for approval and can be added quickly to support your integration needs.

• How to add a short code

  • A short code is a globally unique, immutable account identifier that managed users use to sign in without remembering the full account ID. It is mandatory if the account will contain managed users.
  • Set it on POST /accounts or add it later with PATCH /accounts/{accountId}. See Short Code Management for the schema, examples, error responses, and the support process for a manual correction.

• Testing in lower environments

  • The Stage environment is available for testing and is intended to behave extremely similarly to production environments. However, it requires a separate application.

• How to add/create an address

  • Once you’ve created an account, you can create an address. This is done through the POST /accounts/accountId/addresses endpoint
  • The required fields for an address are
    • country which is an ISO 3166-1 Alpha-2 country code. For example, US Region, in the us these are states.
    • Locality, often a city name included in the street address like Westminster
    • Street Address, represents the address where mail is delivered. It can be a physical street address (e.g., a home or business location) or a PO Box (a mailbox rented at a post office for receiving mail). This property allows for both types of address formats.
    • One or more references, these are the same type of reference objects as in accounts and indicate other locations this address is defined
  • There are optional fields as well, such as postalCode, shipping, and billing.
    • It should be noted that if shipping and/or billing are provided, the respective fields isShipTo, isBillTo, isDefaultShipTo, and isDefaultBillTo should be set to true or false accordingly.

• Add an identity to an account

  • Add an existing TID User
    • To add an existing user to an account you can send a POST /accounts/accountId/users with a JSON body that contains
      • id: the string with the user’s TID user id
      • roleIds: An array of roleIds to grant the user
      • default: a boolean value for if this account is the user’s default account
  • Add a new TID user
    • To invite a new user to an account by their email or username a POST request can be made to users
    • At a minimum, the body must include either the email field or both the userName and tempPassword fields.
    • Optionally query parameters can be defined to add the user to a specific groupId, accountId, and or roleIds(comma separate)
    • The body of the request also accepts optional values for firstName, lastName, country, language, timezone, and a picture uri.

Dealer-Customer Opt-In

A dealer account can establish a doingBusinessWith relationship with a customer account to manage the customer’s account and, once opted in, access the customer’s users, devices, and shipping addresses. See Dealer-Customer Opt-In Workflow for the full step-by-step guide.

Becoming a Trusted Account Data Source

• Trusted data sources are special privilege applications that subscribe to IAM, utilize client_credentials auth flows, and will be able to create and view all accounts
• To gain this status for your application subscription, you must go through a manual review process and have your client id granted the account-provisioner role.
• Reach out to support to become a trusted account data source with a valid use case.