Organizations

An organization in IAM represents a company profile that groups related customer and partner activity across one or more Accounts. While a billable account remains the primary tenant for customer data and administrative management, an organization provides a higher-level view of how a business is structured and how its accounts relate to one another.

Organizations address a common fragmentation problem: the same customer’s data is often spread across multiple accounts in different systems. By linking accounts to an organization, customers and partners can manage assets in a way that reflects their real-world company structure rather than being constrained by individual account boundaries.

For background on how organizations fit into the broader account model, see the Modularity via Organizations and Account Linking section in the Accounts documentation.

How Accounts Relate to Organizations

An account can be associated with organizations in two distinct ways. These are exposed through different API operations and behave differently in list and search results.

Relationship	Created via	What it represents
Customer membership	POST /organizations, POST /organizations/{organizationId}/accounts	A customer account belongs to a company profile. When a customer creates an organization, their account is linked automatically. Additional customer accounts can be added later.
Dealer partnership	POST /organizations (dealer caller), POST /accounts/{accountId}/isPartnerFor	A dealer account is partnered with an organization, allowing the dealer to list, add, and verify customer accounts within that organization.

There is no separate “owner” relationship. The account that creates an organization is linked using the appropriate relationship above based on whether the caller is a customer or dealer account. That account does not receive permanent elevated privileges beyond its IAM permissions.

Relationship model

The diagram below shows how organizations relate to accounts. Customer accounts are linked through account membership, which carries a view property. Dealer accounts are linked through a separate dealer partnership.

erDiagram
    Organization ||--o{ CustomerAccount : "account membership"
    Organization ||--o| DealerAccount : "dealer partnership"

    Organization {
        string id
        string name
    }

    CustomerAccount {
        string id
        string type "customer"
    }

    DealerAccount {
        string id
        string type "dealer"
    }

The account membership link between an organization and a customer account includes:

Property	Values	Description
view	customer	The account was linked in a customer self-service context — the end customer manages their own company profile.
view	dealer	The account was linked in a dealer-managed context — a dealer added the account on behalf of a customer.
verified	true / false	Whether a dealer has verified the account’s membership. Exposed in API responses as relation.organizationVerified.

A single customer account can hold both customer and dealer views on the same organization when it is linked through both contexts. List endpoints filter results by the caller’s view so each integrator sees the memberships relevant to their use case.

Dealer partnership is a separate link between a dealer account and an organization. It is created via POST /accounts/{accountId}/isPartnerFor and enables the dealer to list, add, verify, and manage customer accounts within that organization.

Multiple organizations per account

An account may be linked to more than one organization, with these rules:

• A customer account can belong to at most one organization per view (customer or dealer). Linking the same account to a second organization through the same view returns HTTP 409.
• The same account can be linked to the same organization through both views when both a customer self-service context and a dealer-managed context apply.
• A customer account could appear in one organization through the customer view and in a different organization through the dealer view.

Integrators should always supply the correct account context (accountId query parameter or JWT account) so IAM returns the membership view relevant to the caller.

Organization Visibility

Every organization API requires a valid JWT. What a caller can see depends on their permissions and their relationship to the organization:

• Get by ID — Callers can read an organization only if they have read access and are associated with it through the appropriate customer or dealer context.
• List organizations for an account — Returns organizations linked to the given account, filtered by the caller’s view (customer or dealer).
• Search — Open lookup across all IAM data.

Organization Schema

An organization is comprised of profile information, optional contact details, and an address. The full schema is available in the API Reference for organizations.

Core attributes

Attribute	Description	Constraints
id	Unique identifier (UUID)	Assigned by IAM on create
name	Organization display name	1–100 characters
description	Free-text description	Optional
website	Organization website URL	5–100 characters
industry	Industry classification	1–100 characters
parentOrgId	Parent organization ID	8–36 characters; optional
primaryContactInfo	Contact details (email, firstName, lastName, phoneNumber)	Optional
tradeStyleNames	Alternate business names (often from enrichment)	Up to 10 names, each up to 100 characters
trn	Trimble Resource Name	Returned on responses
type	Organization type	singleTierHierarchical (default) or singleTierNonHierarchical
metadata	Created/updated audit metadata	Returned on responses

Address

An address is required when creating an organization. Address fields follow the standard IAM address schema:

• addressLine1 is required (streetAddress is deprecated).
• country must be a valid ISO 3166 alpha-2 code.

On GET, the address is included only when include=full is supplied.

Dealer and Customer Views

IAM distinguishes two operational contexts for organizations and account memberships:

• Customer view — The organization and its linked accounts are managed by the end customer. This is the self-service context for grouping a customer’s own billable accounts under one company profile.
• Dealer view — The organization and its linked accounts are managed by a dealer on behalf of customers with whom they have an established business relationship.

These views are separate from organizational hierarchy (parent/child orgs). Hierarchy describes how organizations relate to each other; views describe how an account is linked to an organization.

An account can belong to only one organization per view. When a dealer lists organizations for a customer account, the result reflects the dealer view of that account’s membership. To move a customer account to a different organization in the dealer context, remove the existing link first, then create a new one.

List endpoints apply default filters based on the caller’s account type so dealers and customers each see the memberships relevant to their context.

Organization Types

IAM supports two organization types. The type is set at creation time and determines whether users can be added directly to the organization.

Type	Value	Account membership	User membership
Single-tier hierarchical	singleTierHierarchical	Supported (default)	Not supported
Single-tier non-hierarchical	singleTierNonHierarchical	Supported	Supported via invitation flow

Single-tier hierarchical

The default type. Supports linking customer accounts and optional parent–child relationships between organizations (see Organization Hierarchy).

Single-tier non-hierarchical

Supports explicit user membership on an organization in addition to account membership. Users are added through an invitation workflow.

Organization Hierarchy

Organizations can be arranged in a parent–child hierarchy using parentOrgId (for example, a regional office under a parent company).

• A maximum of three levels is supported (parent, child, grandchild).
• Hierarchy is modeled on the organization record itself; there is no separate org-unit resource.

Account Membership

Linking accounts to an organization is the primary way to group billable accounts under a company profile.

Adding a customer account

POST /organizations/{organizationId}/accounts

• Customer callers must already be associated with the organization. Only customer-type accounts can be added.
• Dealer callers must be partnered with the organization and have an established doingBusinessWith relationship with the target customer account.
• Dealer accounts cannot be added through this endpoint.

Removing an account

DELETE /organizations/{organizationId}/accounts/{accountId}

Removal is view-aware: a dealer caller removes the dealer-view link; a customer caller removes the customer-view link. The link is removed entirely when no views remain.

Listing accounts in an organization

GET /organizations/{organizationId}/accounts

Primarily used in dealer partner workflows.

• Results are not paginated and are capped at 50 accounts.
• Each account may include a reference object with external-system identifiers when available.
• The relation.organizationVerified field reflects whether a dealer has verified the account’s membership.

Listing organizations for an account

GET /accounts/{accountId}/organizations

• Supports cursor-based pagination and RSQL filtering. See Pagination.
• The relation.organizationVerified field reflects the dealer’s verification status for that account.

Dealer Partnership

Dealers establish a partnership with an organization using POST /accounts/{accountId}/isPartnerFor.

Once partnered, the dealer can:

• List customer accounts within the organization.
• Add customer accounts to the organization (subject to doingBusinessWith validation).
• Update verification status for linked customer accounts.

Organization Verification

Dealers can mark whether a customer account’s membership in an organization has been verified. The status is exposed as relation.organizationVerified in list responses.

PUT /organizations/{organizationId}/accounts/{accountId}

{ "verified": true }

Requires the caller to be a dealer with appropriate account permissions. The optional accountId query parameter selects the dealer account context when acting on behalf of another account.

User Membership

Available only for single-tier non-hierarchical organizations.

Method	Path	Description
POST	/organizations/{organizationId}/users	Add a user (invitation sent by default)
DELETE	/organizations/{organizationId}/users/{userId}	Remove a user

Removing a user may return HTTP 202 when cleanup of related account access is still in progress.

Search and Enrichment

POST /organizations/search

Provide at least one of name or website, plus an address.

IAM combines two sources:

1. External enrichment (D&B) — Matches from Dun & Bradstreet based on name, website, and address (up to 10 results).
2. Internal IAM search — Matches from organizations already known to IAM within the caller’s scope.

Results are merged and deduplicated by organization ID. Geographic filtering uses a default radius of 1000 km around the supplied address. On create, IAM also attempts D&B enrichment automatically.

Account Context

All organization API calls operate within an account context from the caller’s JWT. The optional accountId query parameter overrides this when the caller is linked to that account.

This is commonly used when a user belongs to multiple accounts or when a dealer acts on behalf of a specific dealer account.

Who Can Modify Organizations and Links

Operations require a valid JWT and appropriate IAM permissions through the caller’s account roles. See Authorization and Roles for general IAM authorization concepts.

Operation	Who typically performs it	Notes
Create organization	Customer or dealer account with create permission	Calling account is linked automatically
Update organization profile	Caller with update permission on organizations	Changes name, website, etc. — not account links
Add/remove account from organization	Customer admin or dealer with account management permission	Dealers also require partnership and doingBusinessWith
Establish dealer partnership	Dealer account	Via isPartnerFor
Update verification	Dealer account	Sets verified on the account–organization link
Add/remove user	Caller with user management permission	Non-hierarchical organizations only

API Overview

Full request and response schemas, status codes, and examples are in the API Reference.

Organization CRUD

Method	Path	Description
POST	/organizations	Create an organization
GET	/organizations/{organizationId}	Get an organization by ID
GET	/organizations	List organizations for the calling subject
PUT	/organizations/{organizationId}	Update an organization

GET query parameters:

Parameter	Description
include=full	Include address and primaryContactInfo
accountId	Override the account context

Account membership

Method	Path	Description
POST	/organizations/{organizationId}/accounts	Add a customer account
GET	/organizations/{organizationId}/accounts	List accounts
PUT	/organizations/{organizationId}/accounts/{accountId}	Update verification status (dealer only)
DELETE	/organizations/{organizationId}/accounts/{accountId}	Remove an account

User membership

Method	Path	Description
POST	/organizations/{organizationId}/users	Add a user
DELETE	/organizations/{organizationId}/users/{userId}	Remove a user

Search and account-scoped operations

Method	Path	Description
POST	/organizations/search	Search organizations
POST	/accounts/{accountId}/isPartnerFor	Establish dealer partnership
GET	/accounts/{accountId}/organizations	List organizations for an account

Common Workflows

Customer creates and manages an organization

1. Call POST /organizations with profile data and a required address.
2. IAM creates the organization, links the customer account, and attempts D&B enrichment.
3. Add additional customer accounts via POST /organizations/{organizationId}/accounts.
4. Update organization details via PUT /organizations/{organizationId}.

Dealer partners with and manages customer accounts

1. Create or find an organization via POST /organizations/search or POST /organizations.
2. Establish partnership via POST /accounts/{accountId}/isPartnerFor.
3. List customer accounts via GET /organizations/{organizationId}/accounts.
4. Add customer accounts via POST /organizations/{organizationId}/accounts (requires doingBusinessWith).
5. Verify membership via PUT /organizations/{organizationId}/accounts/{accountId}.

Non-hierarchical organization with user invitations

1. Create an organization with type set to singleTierNonHierarchical.
2. Link customer accounts to the organization.
3. Add users via POST /organizations/{organizationId}/users.
4. Remove users via DELETE /organizations/{organizationId}/users/{userId} when access should be revoked.

Related Documentation

• Accounts — Billable entities and account types
• Users — User provisioning and invitation flows
• Roles and Permissions — Role and permission concepts
• Authorization — How IAM evaluates access
• Pagination — Cursor-based pagination for list endpoints