/distributors - Create distributor

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://api.my.nethesis.it/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json 
{
  "my.nethesis.it MCP server": {
    "url": "https://api.my.nethesis.it/mcp"
  }
}
Close
POST /distributors
Bearer auth

Create a new distributor organization (Owner only)

application/json

Body Required

  • name string Required

    Organization name (cannot be empty)

    Minimum length is 1.

  • description string

    Organization description

  • created_by_organization_id string

    Optional. Attributes the new organization to an ancestor org (its custom_data.createdBy) instead of the caller's own org — used to preserve hierarchical ownership when an upper tier creates an entity on behalf of a lower one. Honored only for reseller creation (owner only; target must be a distributor) and customer creation (owner or distributor; target must be a reseller or distributor) within the caller's hierarchy. Empty = owned by the caller's organization. When set, the created_by snapshot in responses shows the attributed org and carries on_behalf_of: true.

  • custom_data object Required

    Custom organization data (vat field is required)

    Additional properties are allowed.

    Hide custom_data attribute Show custom_data attribute object
    • vat string Required

      VAT number (required, cannot be empty)

      Minimum length is 1.

Responses

  • 201 application/json

    Distributor created successfully

    Hide response attributes Show response attributes object
    • code integer
    • message string
    • data object
      Hide data attributes Show data attributes object
      • id string

        Database UUID of the organization

      • logto_id string

        Logto organization ID (use this value for assignment operations)

      • name string

        Organization name

      • description string

        Organization description

      • custom_data object

        Custom organization data

        Additional properties are allowed.

      • suspended_at string(date-time) | null

        Timestamp when the organization was suspended. NULL means enabled, non-NULL means blocked/suspended.

      • suspended_by_org_id string | null

        Organization ID that caused cascade suspension (for resellers and customers only). NULL means directly suspended or not suspended. When set, the entity can only be reactivated by the parent organization that initiated the cascade.

      • rebranding_enabled boolean

        Whether rebranding is active for this organization (directly or inherited from parent)

      • rebranding_org_id string | null

        The organization ID that provides the rebranding (the org where rebranding is configured). Only present when rebranding_enabled is true.

      • created_by object

        Snapshot of the user who created an organization (distributor, reseller or customer). The user identity fields are point-in-time; organization_name is kept in sync when the referenced organization is renamed.

        Hide created_by attributes Show created_by attributes object
        • user_id string

          Logto ID of the user who created the organization

        • username string

          Username of the creator

        • name string

          Full name of the creator

        • email string

          Email of the creator

        • organization_id string

          Organization ID the creator belongs to

        • organization_name string

          Organization name the creator belongs to

        • on_behalf_of boolean

          True when the organization was attributed to a different organization via created_by_organization_id (the user acted on behalf of organization_name rather than belonging to it). Omitted when false.

      • promoted_from object

        Trace of the promotion that gave the organization its level. Distributors only, and only those promoted from reseller level (PATCH /resellers/{id}/promote) - omitted for an organization created at its level.

        Hide promoted_from attributes Show promoted_from attributes object
        • level string

          The organization level the promotion moved up from

        • at string(date-time)

          When the promotion ran

        • detached_from_organization_id string

          Logto ID of the organization that manages the promoted organization at its old level and drops it from its scope. Omitted when the organization carried no createdBy.

        • by object

          Snapshot of the user who ran the promotion

          Hide by attributes Show by attributes object
          • user_id string

            Logto ID of the user who created the organization

          • username string

            Username of the creator

          • name string

            Full name of the creator

          • email string

            Email of the creator

          • organization_id string

            Organization ID the creator belongs to

          • organization_name string

            Organization name the creator belongs to

          • on_behalf_of boolean

            True when the organization was attributed to a different organization via created_by_organization_id (the user acted on behalf of organization_name rather than belonging to it). Omitted when false.
  • 400 application/json

    Bad request - validation error

    Hide response attributes Show response attributes object
    • code integer

      HTTP error code

    • message string

      Error message

    • data object
      Hide data attributes Show data attributes object
      • type string

        Type of error

        Values are validation_error or external_api_error.

      • errors array[object]
        Hide errors attributes Show errors attributes object
        • key string

          Field name that failed validation

        • message string

          Error code or message

        • value string

          Value that failed validation

      • details

        Additional error details
  • 401 application/json

    Unauthorized - invalid or missing token

    Hide response attributes Show response attributes object
    • code integer
    • message string
    • data object | null
  • 403 application/json

    Forbidden - insufficient permissions

    Hide response attributes Show response attributes object
    • code integer
    • message string
    • data object | null
  • 422 application/json

    Unprocessable entity - business logic error

    Hide response attributes Show response attributes object
    • code integer

      HTTP error code

    • message string

      Error message

    • data object
      Hide data attributes Show data attributes object
      • type string

        Type of error

        Values are validation_error or external_api_error.

      • errors array[object]
        Hide errors attributes Show errors attributes object
        • key string

          Field name that failed validation

        • message string

          Error code or message

        • value string

          Value that failed validation

      • details

        Additional error details
POST /distributors 
curl \
 --request POST 'https://collect.your-domain.com/api/distributors' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"name":"ACME Distribution SpA","description":"Main distributor for Italian and Swiss markets","created_by_organization_id":"eeex9cffzsd7","custom_data":{"vat":"IT12345678901","email":"contact@acme-distribution.com","contactPerson":"John Smith","region":"Italy"}}'
Request examples 
{
  "name": "ACME Distribution SpA",
  "description": "Main distributor for Italian and Swiss markets",
  "created_by_organization_id": "eeex9cffzsd7",
  "custom_data": {
    "vat": "IT12345678901",
    "email": "contact@acme-distribution.com",
    "contactPerson": "John Smith",
    "region": "Italy"
  }
}
Response examples (201) 
{
  "code": 201,
  "message": "distributor created successfully",
  "data": {
    "id": "4405ffd0-0aca-44ef-bae2-c8545bce94f4",
    "logto_id": "akkbs6x2wo82",
    "name": "ACME Distribution SpA",
    "description": "Main distributor for Italian and Swiss markets",
    "custom_data": {
      "email": "contact@acme-distribution.com",
      "contactPerson": "John Smith",
      "region": "Italy"
    },
    "suspended_at": "2026-05-04T09:42:00Z",
    "suspended_by_org_id": "string",
    "rebranding_enabled": false,
    "rebranding_org_id": "string",
    "created_by": {
      "user_id": "aa15fcvgzw1y",
      "username": "owner",
      "name": "Nethesis Owner",
      "email": "owner@nethesis.it",
      "organization_id": "2wl3iixbc8ua",
      "organization_name": "Owner",
      "on_behalf_of": true
    },
    "promoted_from": {
      "level": "reseller",
      "at": "2026-07-30T10:00:00Z",
      "detached_from_organization_id": "akkbs6x2wo82",
      "by": {
        "user_id": "aa15fcvgzw1y",
        "username": "owner",
        "name": "Nethesis Owner",
        "email": "owner@nethesis.it",
        "organization_id": "2wl3iixbc8ua",
        "organization_name": "Owner",
        "on_behalf_of": true
      }
    }
  }
}
Response examples (400) 
{
  "code": 400,
  "message": "validation failed",
  "data": {
    "type": "validation_error",
    "errors": [
      {
        "key": "username",
        "message": "required",
        "value": "string"
      }
    ]
  }
}
Response examples (401) 
{
  "code": 401,
  "message": "invalid token",
  "data": {}
}
Response examples (403) 
{
  "code": 403,
  "message": "insufficient permissions",
  "data": {}
}
Response examples (422) 
{
  "code": 400,
  "message": "validation failed",
  "data": {
    "type": "validation_error",
    "errors": [
      {
        "key": "username",
        "message": "required",
        "value": "string"
      }
    ]
  }
}