# Plan an import

<div class="api-op" data-api-operation>
<div class="api-op__main">

<p class="api-endpoint"><span class="method method-post">POST</span> <code>/v1/imports</code></p>

<dl class="api-facts"><div><dt>Scope</dt><dd><code>imports:write</code></dd></div><div><dt>Auth</dt><dd>Secret key (<code>sk_…</code>)</dd></div><div><dt>Since</dt><dd>1.0</dd></div></dl>

## Headers

<ul class="api-fields">
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">OhAuthCat-Version</code> <span class="api-field__type">string</span></p>
Minor version; defaults to the environment's pin.
</li>
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">Idempotency-Key</code> <span class="api-field__type">string</span></p>
Honoured for 24 h; a replay returns the original response.

<p class="api-field__chips">min length 1 · max length 255</p>
</li>
</ul>

## Request body

<ul class="api-fields">
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">source</code> <span class="api-field__type">string</span> <span class="api-field__required">Required</span></p>
The source to read. `auth0` and `csv_saml` are read only by their adapter (Auth0 `credentials`, or a `csv_saml` `bundle_upload_id`); an inline `bundle` with either source is refused with `parameter_invalid`. One environment has at most one planned or running `auth0` or `csv_saml` import; another answers `import_state_conflict` (409) until it completes, fails or is cancelled; `GET /v1/imports?state=planned` finds it, and a planned one is cancelled automatically after 24 hours. Creating `auth0` and `csv_saml` imports is also limited to 20 per hour per environment (`rate_limited`, 429, with `Retry-After`). A `csv_saml` archive names at most 100 distinct metadata URLs, each fetched once, and its whole read is bounded to 50 seconds. An `auth0` read, Management API retries included, is bounded to 50 seconds too.

<p class="api-field__chips">one of <code>polis</code>, <code>workos</code>, <code>auth0</code>, <code>csv_saml</code>, <code>bundle</code></p>
</li>
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">credentials</code> <span class="api-field__type">object</span></p>
Read the source's management API once, with these credentials, instead of sending a bundle. Polis/WorkOS authentication credentials and API keys are used only for this request, never stored. Auth0 uses tenant_domain, client_id and client_secret for a canonical Auth0 tenant host, with read:connections only; like Polis/WorkOS credentials they are used only for this request and never stored. Credentials are never logged or returned. Auth0 offset pagination refuses sources exceeding its documented 1000-connection capacity. Custom Auth0 tenant domains are currently refused. Nonsecret migration settings are copied into the normalized bundle and connection configuration and may appear in exports. `polis`: `base_url` (https), `api_key`, `product`, optional `sp_entity_id` (the deployment's SAML audience) and `external_url` (the deployment's `EXTERNAL_URL` when IdPs reach it on another origin than `base_url`; its shared ACS `<external_url>/api/oauth/saml` becomes `legacy_shared_acs_url`). `workos`: `api_key`, optional `base_url` (default `https://api.workos.com`); optional paired `custom_auth_domain` and `custom_auth_connections` configure custom-domain migration. The domain must be a canonical lowercase ASCII hostname, without a port or trailing dot. The connections value is a JSON array of objects with exactly `connection_id`, `acs_url` and `sp_entity_id`, copied from the actual WorkOS Service Provider Details; every imported active SAML connection needs one record and unknown, inactive, non-SAML or duplicate references are refused. Each ACS URL must use that exact domain. No vendor identifier or path is inferred. Each credential value is limited to 4096 bytes; larger setups can send a normalized bundle. WorkOS exports no IdP metadata, so its SAML connections import as drafts with `idp_metadata_required` until the IT admin supplies it through a `migration` portal link. Every request goes through the safe fetcher; a refused key or an unreachable or non-public source answers `import_source_unreachable`.
</li>
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">bundle_upload_id</code> <span class="api-field__type">string</span></p>
A valid, unexpired, unconsumed upload of this environment. csv_saml selects a closed ZIP containing connections.csv and flat named metadata XML files; other sources select import_bundle. The uploaded document must match its declared size and pass the same validation as an inline bundle. Consumption and creation of the planned import are atomic; workers use the frozen import bytes.
</li>
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">users_upload_id</code> <span class="api-field__type">string</span></p>
Optional unconsumed auth0_users JSON lines export of this environment, at most 64 MiB. Allowed only with Auth0 credentials. The exporter must establish the unchanged upstream IdP subject; an unverified provider-specific identity is refused, and the original export is never returned.
</li>
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">mapping_upload_id</code> <span class="api-field__type">string</span></p>
Optional unconsumed auth0_mapping UTF-8 CSV with connection_id,organization_external_id,organization_name columns. Allowed only with Auth0 credentials, at most 5 MiB; explicit mapping takes precedence over source metadata.
</li>
<li class="api-field">
<p class="api-field__head"><code class="api-field__name">bundle</code> <span class="api-field__type">ImportBundle</span></p>
The normalized migration format (version 1). It never carries secrets (OIDC client secrets, SCIM tokens, private keys). At most 16 MiB, 500 organizations and 100000 directory users.
</li>
</ul>

## Responses

<ul class="api-responses">
<li class="api-response"><span class="api-status api-status--ok">201</span> <span>OK <span class="api-field__type">Import</span></span></li>
<li class="api-response"><span class="api-status api-status--bad">400</span> <span>Invalid request. Codes: <a href="/errors/parameter_invalid/">parameter_invalid</a>, <a href="/errors/parameter_missing/">parameter_missing</a>, <a href="/errors/version_unsupported/">version_unsupported</a> and resource-specific codes from the catalogue. <span class="api-field__type">Error</span></span></li>
<li class="api-response"><span class="api-status api-status--bad">401</span> <span>Codes: <a href="/errors/authentication_required/">authentication_required</a>, <a href="/errors/api_key_invalid/">api_key_invalid</a>. <span class="api-field__type">Error</span></span></li>
<li class="api-response"><span class="api-status api-status--bad">403</span> <span>Codes: <a href="/errors/api_key_scope_missing/">api_key_scope_missing</a>, <a href="/errors/ip_not_allowed/">ip_not_allowed</a>, <a href="/errors/plan_limit_reached/">plan_limit_reached</a>. <span class="api-field__type">Error</span></span></li>
<li class="api-response"><span class="api-status api-status--bad">409</span> <span>Codes: <a href="/errors/idempotency_key_reused/">idempotency_key_reused</a> and resource-specific conflicts. <span class="api-field__type">Error</span></span></li>
<li class="api-response"><span class="api-status api-status--bad">429</span> <span>Code: <a href="/errors/rate_limited/">rate_limited</a>. Retry-After is set. <span class="api-field__type">Error</span></span></li>
<li class="api-response"><span class="api-status api-status--bad">503</span> <span>Code: <a href="/errors/service_unavailable/">service_unavailable</a>. Retry-After is set; writes are paused. <span class="api-field__type">Error</span></span></li>
<li class="api-response"><span class="api-status api-status--neutral">default</span> <span>Any other error, including <a href="/errors/internal_error/">internal_error</a>. Every code is in the error catalogue. <span class="api-field__type">Error</span></span></li>
</ul>

Errors share one shape; see the [error code catalogue](/errors/).

</div>
<div class="api-op__code">

**curl**

```sh wrap
curl -X POST \
  "https://api.ohauthcat.com/v1/imports" \
  -H "Authorization: Bearer $OHAUTHCAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "source": "polis"
}'
```

**Node**

```javascript wrap
const response = await fetch("https://api.ohauthcat.com/v1/imports", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OHAUTHCAT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    source: "polis",
  }),
});
const data = await response.json();
```

**Python**

```python wrap
import os
import requests

response = requests.post(
    "https://api.ohauthcat.com/v1/imports",
    headers={"Authorization": f"Bearer {os.environ['OHAUTHCAT_API_KEY']}"},
    json={
        "source": "polis",
    },
)
data = response.json()
```

```json title="Response 201" wrap
{
  "id": "imp_01J9Z3K5V7W8X9Y0Z1A2B3C4D5",
  "object": "import",
  "source": "polis",
  "state": "planning",
  "plan": {
    "organizations": [
      {
        "organization_id": "org_01J9Z3K5V7W8X9Y0Z1A2B3C4D5",
        "lever": "A",
        "routing": "legacy",
        "blockers": ["example_blocker"],
        "legacy_id": "01J9Z3K5V7W8X9Y0Z1A2B3C4D5",
        "name": "Acme Corp",
        "state": "pending",
        "error_code": "saml_signature_invalid",
        "refused": "example_refused",
        "items": [{}],
        "imported_at": "2026-01-15T09:30:00Z",
        "switched_at": "2026-01-15T09:30:00Z",
        "rolled_back_at": "2026-01-15T09:30:00Z"
      }
    ],
    "summary": {
      "create": 1,
      "draft": 1,
      "skip": 1,
      "users": 1,
      "groups": 1
    },
    "source_skipped": [
      {
        "kind": "default",
        "legacy_id": "01J9Z3K5V7W8X9Y0Z1A2B3C4D5",
        "reason": "Primary SSO connection for Acme Corp."
      }
    ],
    "custom_hostnames": [
      {
        "hostname": "acme.com",
        "type": "default"
      }
    ]
  },
  "bundle_source": "polis",
  "created_at": "2026-01-15T09:30:00Z",
  "updated_at": "2026-01-15T09:30:00Z",
  "completed_at": "2026-01-15T09:30:00Z"
}
```

</div>
</div>
