Tenants API Guide

Introduction

The Tenants API allows you to create, retrieve, update, and delete tenants within your organization. Every entity in the iDrive platform—whether a WMS / Channel Partner, 3PL, or 3PL client/brand—is represented as a tenant.

Tenants determine:

• What data a user can access
• Which carrier accounts they can use
• How reporting is segmented
• How API requests are scoped

Important: When making API requests, you must specify which tenant you are acting on behalf of using the x-tenant-id header.

Understanding Tenant Hierarchies

In iDrive, tenants follow a flexible but structured hierarchy. Each tenant is uniquely identified by a tenantId.

3PL Parent
└── 3PL
    └── Brand (or 3PL Client)

Tenant Types

WMS / Channel Partner (thirdPartyLogisticParent) — Intended for organizations that oversee multiple 3PLs and require strict data isolation across all tenants. This allows you to create and manage both 3PL and Brand tenants under your umbrella while maintaining proper separation of data and permissions.

3PL — Represents a single third-party logistics provider. A 3PL can manage multiple warehouse locations in the iDrive platform by creating and configuring individual Shipping Sites.

Brand — Represents either a standalone shipper or a 3PL client.

Note: If a shipper operates independently (not through a 3PL), you can create the Brand tenant at the top level. There is no requirement to place it under a 3PL or 3PL Parent.

Base URLs

Use the correct base URL for your environment:

Sandbox: https://api.beta.idrivelogistics.com

Production: https://api.idrivelogistics.com

Append the specific API route to the base URL (e.g., /api/v1/tenants).

API Endpoints Overview

The Tenants API provides the following endpoints:

List Tenants

Retrieve all tenants accessible to the current authenticated account.

GET /api/v1/tenants

Example Response

[
  {
    "tenantId": "abc123",
    "createdAt": "2025-11-14T17:03:55.480Z",
    "updatedAt": "2025-11-14T17:03:55.480Z",
    "name": "Global Fulfillment",
    "contact": "[email protected]",
    "parentId": null,
    "machineUserId": "string",
    "internalClientId": "string",
    "tenantType": "thirdPartyLogistic"
  }
]

Response Fields

• tenantId — Unique identifier for the tenant
• name — Display name of the tenant
• tenantType — Type of tenant (thirdPartyLogisticParent, thirdPartyLogistic, or brand)
• parentId — ID of the parent tenant (null if top-level)
• contact — Contact email

API Reference: https://idrivelogistics.readme.io/reference/get_api-v1-tenants

Create Tenant

Create a new tenant under a specified parent (if applicable).

POST /api/v1/tenants

Example Request

{
  "name": "New Brand",
  "contact": "[email protected]",
  "tenantType": "brand",
  "parentId": "def456"
}

Request Fields

• name — (Required) Name of the tenant
• contact — Contact email
• tenantType — (Required) Type: "thirdPartyLogisticParent", "thirdPartyLogistic", or "brand"
• parentId — (Optional) ID of the parent tenant. Omit for top-level tenants

Tip: When creating a Brand tenant that operates independently, you can omit the parentId to create it at the top level.

API Reference: https://idrivelogistics.readme.io/reference/post_api-v1-tenants

Get Tenant by ID

Retrieve detailed information about a specific tenant.

GET /api/v1/tenants/{id}

Path Parameters

• id — The tenantId of the tenant to retrieve

Example Request

GET /api/v1/tenants/abc123

The response will include all tenant details including name, type, parent relationships, and metadata.

API Reference: https://idrivelogistics.readme.io/reference/get_api-v1-tenants-id

Update Tenant

Modify an existing tenant's information such as name, tenant type, or contact.

PUT /api/v1/tenants/{id}

Path Parameters

• id — The tenantId of the tenant to update

Example Request

{
  "name": "Updated Brand Name",
  "contact": "[email protected]"
}

API Reference: https://idrivelogistics.readme.io/reference/put_api-v1-tenants-id

Delete Tenant

Remove a tenant from the system.

DELETE /api/v1/tenants/{id}

Path Parameters

• id — The tenantId of the tenant to delete

Important: You may need to remove child tenants first before deleting a parent tenant. Deleting a tenant is permanent and will impact all associated data, carrier accounts, and shipping sites. Historical data may be available in some cases.

API Reference: https://idrivelogistics.readme.io/reference/delete_api-v1-tenants-id

Common Use Cases

Creating a 3PL

Step 1: Create the 3PL

POST /api/v1/tenants

{
  "name": "West Coast Warehouse",
  "tenantType": "thirdPartyLogistic",
  "parentId": "acme_parent_id",
  "contact": "[email protected]"
}

Creating an 3PL Client or Brand

POST /api/v1/tenants

{
  "name": "Direct Shipper Co",
  "tenantType": "brand",
  "contact": "[email protected]"
}

Note: No parentId is specified, creating a top-level brand tenant.

Listing All Child Tenants

Get all tenants and filter by parentId:

GET /api/v1/tenants

Filter the response in your application logic to find tenants where parentId matches your target parent.

Best Practices

• Plan your hierarchy — Design your tenant structure before creating tenants to avoid complex reorganizations later
• Use consistent naming — Establish naming conventions for tenants to make management easier
• Verify parentId — Always verify parent tenant IDs exist before creating child tenants
• Document tenant purposes — Keep internal documentation of what each tenant represents
• Test in sandbox — Test tenant creation and hierarchy changes in the sandbox environment first
• Handle errors gracefully — Implement proper error handling for tenant operations, especially deletes

Need Help?

• API Reference: https://idrivelogistics.readme.io/
• Getting Started Guide: Review authentication and basic concepts
• Support: Contact your iDrive account representative