Create companies/accounts

A company is a core resource in the AppDirect platform, containing one or more company memberships. An account represents a company or another organization that does business in the marketplace. Each account must include at least one user associated with the account through an account membership.

Use the APIs described in this topic to perform various company/account management tasks. Note that the REST API endpoints in this section refer to the term ‘company’ whereas GraphQL APIs use ‘account.’ Conceptually, they are one and the same.

Create a company (REST)

Before you can create a company, you must create a company membership. The firstUser object in the request body represents the first membership. When a company is created, an activation email is sent to the first user. The user and company remain in a pending activation state until this user clicks the activation link in the email.

Use the following POST request to create a new company and the associated first user of that company.

POST https://{marketplaceUrl}/api/account/v2/companies

The example in this topic only includes the body parameters required to create a company through the API. You can have additional parameters in your request. Refer to the Create new company API reference for details on authorization rules and the complete list of supported body and query parameters.

A unique identifier (uuid) for your company is returned in the response. This identifier is required in requests to create users, payment instruments, and subscriptions, and is often referred to as the companyUuid. This ID is also required for subscription management API calls.

Request

{
  "name": "Example Inc",
  "countryCode": "US",
  "firstUser": {
       "firstName": "John",
       "lastName": "Smith",
       "email": "john.smith@example.com",
       "roles": [
         "ROLE_SYS_ADMIN"
       ]
  }
}

Create an account (GraphQL)

To create a new account, you use the createAccount mutation to specify a company name, the email address for the account's first associated user, and other account characteristics. This mutation is the equivalent of the REST API Create company.

If the user does not exist, it is created along with the account. The mutation also creates a new account membership to link the account and the user.

The response to the mutation includes the unique identifier (uuid) for the new account. This identifier is required in requests to create users, payment instruments, and subscriptions and is often referred to as the accountID. This ID is also required for subscription management queries and mutations.