# v1 Quickstart (https://docs2.smao.ai/docs/distributor-v1/quickstart)



This is the partner-based workflow for Synaxon and Distributor API v1
integrations. Base URL: `https://api2.smao.ai/api/distributor/v1`.

## 1. Configure the v1 key [#1-configure-the-v1-key]

Distributor keys are issued by SMAO and shown only once. Store the raw key in a
secret manager. A v1 key is authorized for v1 only.

```bash
export SMAO_DISTRIBUTOR_KEY="your-v1-distributor-key"
export BASE="https://api2.smao.ai/api/distributor/v1"
```

`GET /health` is public. All other endpoints require the Bearer token:

```bash
curl "$BASE/health"
curl "$BASE/plans" \
  -H "Authorization: Bearer $SMAO_DISTRIBUTOR_KEY"
```

Choose a plan `slug` and `commitment` from `/plans` for the customer request
below.

## 2. Create the partner (MSP) [#2-create-the-partner-msp]

```bash
curl -X POST "$BASE/partners" \
  -H "Authorization: Bearer $SMAO_DISTRIBUTOR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MSP Hamburg GmbH",
    "externalPartnerId": "SYN-MSP-001",
    "contactEmail": "admin@msp.example",
    "contactName": "Ada Admin",
    "timezone": "Europe/Berlin"
  }'
```

Save both IDs from the response:

* `partner.id` is the `partnerId` used for customer organizations.
* `partner.organizationId` is the MSP's own internal SMAO organization.

The internal organization is part of successful partner provisioning. Trial
setup, invitation creation, and invitation email delivery are best-effort; do
not use email receipt as the provisioning acknowledgement.

The trial is capped by call minutes, not by time. To keep the MSP's own
workspace in use beyond it, assign a paid plan to the partner — the MSP
organization is not reachable through the `/organizations` endpoints:

```bash
curl -X PATCH "$BASE/partners/665abc123def456789012345/plan" \
  -H "Authorization: Bearer $SMAO_DISTRIBUTOR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "plan": { "slug": "advanced", "commitment": "monthly" } }'
```

## 3. Create a customer organization [#3-create-a-customer-organization]

```bash
curl -X POST "$BASE/organizations" \
  -H "Authorization: Bearer $SMAO_DISTRIBUTOR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization": {
      "name": "Customer Hamburg GmbH",
      "industry": "Manufacturing",
      "timezone": "Europe/Berlin"
    },
    "owner": {
      "email": "owner@customer.example",
      "firstName": "Chris",
      "lastName": "Customer"
    },
    "externalCustomerId": "SYN-CUSTOMER-4711",
    "externalContractId": "SYN-CONTRACT-4711",
    "partnerId": "665abc123def456789012345",
    "plan": {
      "slug": "business",
      "commitment": "monthly"
    }
  }'
```

Replace `partnerId` and the plan values with those returned by your calls. A
successful response includes the customer organization and its owner
invitation record. Email transport is best-effort.

`externalPartnerId` and `externalCustomerId` are reconciliation keys. If a
retry returns a duplicate-ID conflict, fetch the existing record instead of
creating a different identifier.

## 4. Read usage and billing [#4-read-usage-and-billing]

Usage query windows use inclusive `YYYY-MM-DD` dates and may cover up to 365
days. For compatibility, the single-organization response serializes its
`period` boundaries as ISO UTC date-times; aggregate responses echo the query
dates.

```bash
curl "$BASE/organizations/69c175970f3e28310926a1aa/usage?from=2026-07-01&to=2026-07-31" \
  -H "Authorization: Bearer $SMAO_DISTRIBUTOR_KEY"

curl "$BASE/partners/665abc123def456789012345/usage?from=2026-07-01&to=2026-07-31" \
  -H "Authorization: Bearer $SMAO_DISTRIBUTOR_KEY"
```

Billing summaries are limited to 31 days and price usage against the current
assigned plan:

```bash
curl "$BASE/organizations/69c175970f3e28310926a1aa/billing-summary?from=2026-07-01&to=2026-07-31" \
  -H "Authorization: Bearer $SMAO_DISTRIBUTOR_KEY"
```

Monetary values are in the smallest unit of the returned currency (for example,
cents for EUR). The API is polling-only; there are no Distributor webhooks.

<Callout type="warn">
  Do not run create, update, plan-assignment, or delete examples against
  live customer data as connectivity tests. Use `/health`, `/plans`, and read endpoints
  for deployment verification.
</Callout>