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 shortcode
  Shortcode is used by managed users to log in to their account without having to remember the full account ID. Shortcode should be unique and can be added while creating an account by passing shortCode field along with the minimum required fields in the account creation request payload. Shortcode is mandatory if the account contains managed users. Optional otherwise.

• 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.

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.