---
title: "Provision a managed customer account"
description: "Create an isolated CloudPrint customer account, App Installation and one-time Agent Enrollment without customer registration."
---
<nav class="docs-breadcrumb" aria-label="Breadcrumb"><a href="/docs/">CloudPrint Documentation</a><span aria-hidden="true">/</span><span>API reference</span></nav>

# Provision a managed customer account

<p class="docs-lead">Create an isolated CloudPrint customer account, App Installation and one-time Agent Enrollment without customer registration.</p>

<div class="api-endpoint-summary"><span class="api-method api-method-post">POST</span><code>/partner-api/v1/accounts</code><span><strong>API version:</strong> v1</span><span><strong>operationId:</strong> <code>createPartnerManagedAccount</code></span><a href="/docs/api/v1/partner/accounts/create/index.md">View as Markdown</a></div>

## What this endpoint does

Create an isolated CloudPrint customer account, App Installation and one-time Agent Enrollment without customer registration.

## Authentication

Send a one-time RS256 Developer Application assertion in `Authorization: Bearer <application_assertion>`. This assertion is not a Public API access token.

## Request

**Production base URL:** `https://public-api.cloudprint.me/partner-api/v1/accounts`

### Parameters

| Name | Location | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | `string` | yes | — | minLength: 1; maxLength: 200 |

### Request body

**Content type:** `application/json`

| Name | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `external_customer_id` | `string` | yes | Stable customer or tenant identifier from the integrator system. | minLength: 1; maxLength: 160; example: `"customer-42"` |
| `name` | `string` | yes | — | minLength: 1; maxLength: 120; example: `"Acme Store 42"` |
| `permissions` | `array` | no | Permissions approved for the installation and included in this token. | — |
| `agent_onboarding` | `object` | yes | — | — |

### Example requests

#### cURL

```bash
curl -sS https://public-api.cloudprint.me/partner-api/v1/accounts \
  -H "Authorization: Bearer $APPLICATION_ASSERTION" \
  -H 'Idempotency-Key: customer-42-provision-v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "external_customer_id": "customer-42",
    "name": "Acme Store 42",
    "permissions": ["printers:read", "documents:write", "print_jobs:write", "print_jobs:read"],
    "agent_onboarding": {
      "return_uri": "https://app.integrator.example/cloudprint/callback",
      "state": "single-use-random-state"
    }
  }'
```

## Response

**HTTP status:** `200` — Idempotent replay of the existing relationship and hosted onboarding URL

### Response fields

| Name | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `relationship_id` | `string (uuid)` | yes | Stable identifier of this resource. | — |
| `developer_account_id` | `string (uuid)` | yes | Stable identifier of this resource. | — |
| `cloudprint_account_id` | `string (uuid)` | yes | Read-only CloudPrint Account identifier. It can be compared with account_id from an Installation Access Token response, but is never supplied when issuing a token. | — |
| `external_customer_id` | `string` | yes | Stable identifier of this resource. | maxLength: 160 |
| `name` | `string` | yes | — | maxLength: 120 |
| `application_id` | `string (uuid)` | yes | Stable identifier of the Developer Application represented by the installation token. | — |
| `installation_id` | `string \| null (uuid)` | yes | Stable UUID of the App Installation that authorized the token. | — |
| `agent_enrollment_id` | `string \| null (uuid)` | yes | Stable identifier of this resource. | — |
| `agent_onboarding_expires_at` | `string \| null (date-time)` | yes | ISO 8601 timestamp recorded by CloudPrint. | — |
| `agent_onboarding_url` | `string \| null (uri)` | yes | CloudPrint-selected hosted onboarding URL. Open the complete value unchanged, including its #token fragment. Do not parse, log, proxy or rebuild it. Network routing and Agent API failover are managed by CloudPrint. | example: `"https://connect.cloudprint.me/setup#token=cpat_example"` |
| `onboarding_status` | `string` | yes | ready means that at least one Agent completed its first authenticated heartbeat. It does not mean that a printer was discovered or is online. | enum: `provisioning`, `waiting_for_agent`, `ready`, `failed` |
| `status` | `string` | yes | Current resource or workflow state; use the endpoint-specific enum values. | enum: `provisioning`, `active`, `suspended`, `closed` |
| `created_at` | `string (date-time)` | yes | ISO 8601 timestamp recorded by CloudPrint. | — |
| `updated_at` | `string (date-time)` | yes | ISO 8601 timestamp recorded by CloudPrint. | — |

### Example response

```json
{
  "relationship_id": "11111111-1111-4111-8111-111111111111",
  "developer_account_id": "11111111-1111-4111-8111-111111111111",
  "cloudprint_account_id": "11111111-1111-4111-8111-111111111111",
  "external_customer_id": "string",
  "name": "string",
  "application_id": "11111111-1111-4111-8111-111111111111",
  "installation_id": null,
  "agent_enrollment_id": null,
  "agent_onboarding_expires_at": null,
  "agent_onboarding_url": "https://connect.cloudprint.me/setup#token=cpat_example",
  "onboarding_status": "provisioning",
  "status": "provisioning",
  "created_at": "2026-08-06T12:00:00Z",
  "updated_at": "2026-08-06T12:00:00Z"
}
```

## Errors

| HTTP status | Description |
| --- | --- |
| `401` | Application assertion is missing, invalid or already used |
| `403` | Partner capability is not granted |
| `404` | Idempotency record references a relationship that no longer exists |
| `409` | Idempotency key or customer relationship conflicts |
| `422` | Request payload, application or permissions are invalid |
| `429` | Rate limit exceeded |
| `500` | Unexpected error |

## Integration guidance

## Related documentation

<div class="docs-card-grid"><a class="docs-card" href="/docs/api/v1/partner/accounts/list/"><strong>List managed customer accounts</strong><span>List customer accounts provisioned by the authenticated partner application, including agent and printer health.</span></a>
<a class="docs-card" href="/docs/api/v1/partner/agent-enrollments/create/"><strong>Create a managed Agent Enrollment</strong><span>Issue an idempotent one-time Enrollment before or after customer onboarding.</span></a>
<a class="docs-card" href="/docs/api/v1/idempotency/"><strong>Idempotent print-job creation</strong><span>Prevent duplicate physical prints when retrying CloudPrint print-job requests after a timeout or network failure.</span></a></div>

<nav class="docs-resource-links" aria-label="Next steps"><a href="/docs/api/v1/explorer/">OpenAPI</a><a href="https://my.cloudprint.me">Open account</a><a href="/docs/legal/privacy/">Privacy Policy</a><a href="/docs/legal/terms/">Terms</a><a href="/docs/legal/payments-and-refunds/">Payment and refunds</a><a href="/docs/legal/data-processing/">DPA</a></nav>