# Onboard a new customer in one shot (/docs/api-reference/admin-onboarding/AdminOnboardingController_onboard)

`POST /admin/onboard`

Base URL: https://api.xentr.ai

Authentication: bearer token (`Authorization: Bearer <token>`).

Creates a trial organization, first factory and manager assignment atomically, then attempts invitation delivery. Reuse requestId after failures. Hardware provisioning is separate.

## Request body

Required.

Content type: `application/json`

```json
{
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string",
      "description": "Stable UUID for this onboarding attempt; reuse when retrying"
    },
    "customerEmail": {
      "type": "string",
      "description": "Customer contact email — receives the invitation",
      "example": "plant.manager@acme-precision.com"
    },
    "companyName": {
      "type": "string",
      "description": "Customer company name — becomes the organization name",
      "example": "Acme Precision Mfg"
    },
    "factoryName": {
      "type": "string",
      "description": "First factory name (will inherit company name if omitted)",
      "example": "Detroit Plant"
    },
    "machines": {
      "description": "Deprecated: hardware configuration is separate from customer onboarding",
      "example": [
        {
          "archetype": "cnc",
          "count": 4
        },
        {
          "archetype": "mill",
          "count": 2
        },
        {
          "archetype": "andon",
          "count": 1
        }
      ],
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "archetype": {
            "type": "string",
            "enum": [
              "cnc",
              "mill",
              "edm",
              "grind",
              "inspection",
              "injection-mold",
              "extruder",
              "press",
              "andon",
              "other"
            ],
            "example": "cnc"
          },
          "count": {
            "type": "number",
            "example": 4,
            "description": "How many machines of this type"
          }
        },
        "required": [
          "archetype",
          "count"
        ]
      }
    },
    "onBehalfOfAccountManagerId": {
      "type": "string",
      "description": "On-behalf-of: account_manager userId to assign as the customer owner. Only honored when the caller is xentr_platform_owner — account_managers self-assign automatically."
    },
    "partnerTag": {
      "type": "string",
      "description": "Optional partner / reseller tag — recorded on the org for revenue attribution. Free-text today; later promoted to a partners table.",
      "example": "siemens-southeast-asia"
    }
  },
  "required": [
    "requestId",
    "customerEmail",
    "companyName",
    "factoryName",
    "machines"
  ]
}
```

## Responses

### 201

Content type: `application/json`

```json
{
  "type": "object",
  "properties": {
    "organizationId": {
      "type": "string"
    },
    "organizationSlug": {
      "type": "string"
    },
    "factoryId": {
      "type": "string"
    },
    "factorySlug": {
      "type": "string"
    },
    "inviteLink": {
      "type": "string",
      "description": "Deprecated: always empty; use onboarding status and retry-invite"
    },
    "trialEndsAt": {
      "type": "string",
      "example": "2026-05-26T14:30:00.000Z"
    },
    "pendingShipmentId": {
      "type": "object",
      "description": "Always null: hardware provisioning is a separate operation"
    },
    "status": {
      "type": "string",
      "enum": [
        "invitation_pending",
        "sending",
        "awaiting_acceptance",
        "accepted",
        "expired"
      ]
    }
  },
  "required": [
    "organizationId",
    "organizationSlug",
    "factoryId",
    "factorySlug",
    "inviteLink",
    "trialEndsAt",
    "pendingShipmentId",
    "status"
  ]
}
```