Partner Provisioning

Use partner endpoints to list the tenant hierarchy, create child tenants, and submit and monitor bulk provisioning jobs for partner-managed tenants.

Base URL

https://api.doit.com

Authentication

Send a DCI API JWT (API access token) in the Authorization header using Bearer authentication:

Authorization: Bearer <token>

The calling tenant is taken from the JWT. Each endpoint also enforces authorization and tenant hierarchy rules.

Endpoints

Provisioning flow

1. Create a child tenant with POST /customers/v1/partners/tenants, or submit a bulk job with POST /customers/v1/partners/tenants/bulk.
2. For bulk jobs, poll GET /customers/v1/partners/tenants/bulk/{jobId} until status is terminal: completed, partial, or failed.
3. Read tenantId and customerId from the single-tenant success response or from each succeeded bulk item.
4. Use GET /customers/v1/partners/tenants to list the tenant hierarchy. Each listed tenantId matches the customerId returned by provisioning.

Idempotency

For retry-safe requests, send X-Idempotency-Key with the same value on retries.

Rate limits and polling

Bulk provisioning is limited to 10 bulk jobs per hour per token. When you receive 429, honor the Retry-After response header.

For bulk jobs, poll the statusUrl returned in the 202 response, or call GET /customers/v1/partners/tenants/bulk/{jobId} directly. A fixed polling interval, such as every 30 seconds, is sufficient.

GET /customers/v1/partners/tenants

List the tenant hierarchy below the calling organization. The response includes resellers and end customers at every depth, excluding the calling organization itself. The calling organization is resolved from the bearer token; this endpoint does not accept a parent tenant override.

Use the same API key or service account used for partner provisioning. Scoped API keys and service accounts require Tenant Provisioning (createRootTenant). When geographic or customer-group scoping applies, tenants outside the caller's effective scope are omitted.

Results are sorted by tenantId in ascending order and returned as a flat, paginated list. Use parentTenantId, tenantType, and level, when present, to reconstruct the visible hierarchy across all pages. A parent may be the calling organization or may be absent from the visible results because of scoping.

Headers

No request body or X-Idempotency-Key is required.

Query parameters

Example request

curl --get \
  --url https://api.doit.com/customers/v1/partners/tenants \
  --header 'Authorization: Bearer <token>' \
  --data-urlencode 'maxResults=50'

Success response

Returns 200 OK. This example shows a distributor's visible descendants: two end customers and their reseller.

{
  "items": [
    {
      "tenantId": "cK4nM7pQ1sT0uV2wY5zA",
      "name": "Acme Corp",
      "primaryDomain": "acme.com",
      "tenantType": "customer",
      "level": 2,
      "parentTenantId": "rS2vB8nQ4kL7xM1pW9tD"
    },
    {
      "tenantId": "cP5nK8qM2sT1uV3wY7zB",
      "name": "Beta Inc",
      "primaryDomain": "beta.com",
      "description": "Beta Inc EMEA",
      "tenantType": "customer",
      "level": 2,
      "parentTenantId": "rS2vB8nQ4kL7xM1pW9tD"
    },
    {
      "tenantId": "rS2vB8nQ4kL7xM1pW9tD",
      "name": "Example Reseller",
      "primaryDomain": "reseller.example.com",
      "tenantType": "reseller",
      "level": 1,
      "parentTenantId": "dH6jL3mN9pQ2rT5vX8yB"
    }
  ],
  "rowCount": 3
}

Each items entry has these fields:

When there are no visible descendants, the response is {"items":[],"rowCount":0}.

Pagination

If a response includes pageToken, pass that value unchanged in the next request. URL-encode it, for example with curl's --data-urlencode, and keep the same maxResults value. Continue until pageToken is absent.

curl --get \
  --url https://api.doit.com/customers/v1/partners/tenants \
  --header 'Authorization: Bearer <token>' \
  --data-urlencode 'maxResults=50' \
  --data-urlencode 'pageToken=<pageToken from the previous response>'

Error responses

POST /customers/v1/partners/tenants

Create one child tenant under a parent organization.

Headers

Request body

Example request

curl --request POST \
  --url https://api.doit.com/customers/v1/partners/tenants \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: tenant-create-001' \
  --data '{
    "parentTenantId": "mR3cK9vL2nP8qW5yT7hJ",
    "tenantName": "Acme Corp",
    "primaryDomain": "acme.com",
    "tenantType": "endCustomer",
    "adminEmail": "[email protected]",
    "adminFirstName": "Jane",
    "adminLastName": "Doe",
    "adminJobFunction": "Software / Ops Engineer",
    "externalId": "BCN-12345",
    "countryCode": "US"
  }'

Success response

Returns 201 Created when the child tenant is provisioned.

{
  "tenantId": "tN8kP2mQ5vL9wX3yR6jH",
  "customerId": "cK4nM7pQ1sT0uV2wY5zA",
  "message": "Tenant provisioned successfully",
  "adminEmail": "[email protected]"
}

Error responses

POST /customers/v1/partners/tenants/bulk

Submit an asynchronous job to provision up to 499 child tenants.

Items are processed independently, so a failure on one item does not block the others. Poll the returned statusUrl or call GET /customers/v1/partners/tenants/bulk/{jobId} until the job reaches a terminal status.

If an item omits tier, the job-level defaultTier applies. If both are omitted, the platform resolves the tier from the calling organization's hierarchy. If an item omits parentTenantId, the job-level defaultParentTenantId applies. If both are omitted, the calling organization from the JWT is used as the parent.

An item is considered a duplicate only when parentTenantId, tenantName, and adminEmail match a previously provisioned item. primaryDomain is not part of duplicate detection. Duplicate entries are automatically skipped.

Jobs of up to 499 tenants typically reach a terminal state within about 50 minutes, based on approximately 1 minute per 10 tenants. This is a sizing guideline for polling, not an SLA.

Headers

Request body

Each tenants item supports these fields:

Example request

curl --request POST \
  --url https://api.doit.com/customers/v1/partners/tenants/bulk \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: bulk-job-001' \
  --data '{
    "defaultParentTenantId": "mR3cK9vL2nP8qW5yT7hJ",
    "defaultTier": "reseller",
    "tenants": [
      {
        "tenantName": "Acme Corp",
        "primaryDomain": "acme.com",
        "adminEmail": "[email protected]",
        "adminFirstName": "Jane",
        "adminLastName": "Doe",
        "adminJobFunction": "Software / Ops Engineer"
      },
      {
        "tenantName": "Beta Inc",
        "tier": "end_customer",
        "adminEmail": "[email protected]",
        "adminFirstName": "John",
        "adminLastName": "Smith"
      }
    ]
  }'

Success response

Returns 202 Accepted when the job is queued for asynchronous processing.

{
  "jobId": "job_01HZXXXXXXXXXXXXXXXXXXXXXX",
  "statusUrl": "https://api.doit.com/customers/v1/partners/tenants/bulk/job_01HZXXXXXXXXXXXXXXXXXXXXXX",
  "message": "Bulk provisioning job accepted"
}

Error responses

GET /customers/v1/partners/tenants/bulk/{jobId}

Get the current status and per-item results for a bulk provisioning job.

Poll until status is terminal: completed, partial, or failed. The items array returns one result per input item in original order.

Path parameters

Headers

Example request

curl --request GET \
  --url https://api.doit.com/customers/v1/partners/tenants/bulk/job_01HZXXXXXXXXXXXXXXXXXXXXXX \
  --header 'Authorization: Bearer <token>'

Success response: processing

{
  "jobId": "job_01HZXXXXXXXXXXXXXXXXXXXXXX",
  "status": "processing",
  "total": 3,
  "succeeded": 1,
  "failed": 0,
  "skipped": 0,
  "pending": 2,
  "submittedAt": "2024-06-01T12:00:00Z",
  "statusAt": "2024-06-01T12:00:42Z",
  "items": [
    {
      "index": 0,
      "tenantName": "Acme Corp",
      "status": "succeeded",
      "tenantId": "tN8kP2mQ5vL9wX3yR6jH",
      "customerId": "cK4nM7pQ1sT0uV2wY5zA",
      "adminEmail": "[email protected]"
    },
    {
      "index": 1,
      "tenantName": "Beta Inc",
      "status": "processing"
    },
    {
      "index": 2,
      "tenantName": "Gamma Ltd",
      "status": "pending"
    }
  ]
}

Success response: partial

{
  "jobId": "job_01HZXXXXXXXXXXXXXXXXXXXXXX",
  "status": "partial",
  "total": 3,
  "succeeded": 2,
  "failed": 1,
  "skipped": 0,
  "pending": 0,
  "submittedAt": "2024-06-01T12:00:00Z",
  "statusAt": "2024-06-01T12:02:15Z",
  "items": [
    {
      "index": 0,
      "tenantName": "Acme Corp",
      "status": "succeeded",
      "tenantId": "tN8kP2mQ5vL9wX3yR6jH",
      "customerId": "cK4nM7pQ1sT0uV2wY5zA",
      "adminEmail": "[email protected]"
    },
    {
      "index": 1,
      "tenantName": "Beta Inc",
      "status": "failed",
      "errorCode": "validation_failed",
      "errorMessage": "The item failed pre-provisioning validation"
    },
    {
      "index": 2,
      "tenantName": "Gamma Ltd",
      "status": "skipped",
      "skipReason": "duplicate_tenant",
      "conflictJobId": "job_01HZYYYYYYYYYYYYYYYYYYYYYY"
    }
  ]
}

Job statuses

Item statuses

Error responses

Job function values

Use one of these values for adminJobFunction when you include it:

• Data Engineer / Data Analysts
• Executive Team
• Finance / Accounting
• Founder
• Legal / Purchasing
• Management
• Sales / Marketing
• Software / Ops Engineer