---
title: "Create Space"
method: POST
path: "/v2/spaces"
tags: ["spaces"]
---

# Create Space

`POST /v2/spaces`

## Request

- Base URL: `https://api.getauctor.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.getauctor.com/v2/spaces`
- Auth: none declared

## Request body

- union
  - CreateAccountRequest
    - `type` 'account', required
    - `name` string, nullable
    - `external_ids` object, nullable: Identifiers for this space in integrated third-party systems, keyed by system. Only these keys are accepted: `azure_devops`, `hubspot`, `jira`, `linear`, `salesforce`, `snow_acct`, `snow_opp`. Any other key is rejected with `400`. To store an identifier from another system (for example a NetSuite customer ID), add a custom field to the template and set it through `custom_fields` instead. Creation is idempotent on these identifiers: if a space of the same `type` in the organization already carries any of them, nothing is created and that existing space is returned unchanged, so a timed-out create can be safely retried.
    - `description` string, nullable
    - `website` string, nullable
    - `headquarters` string, nullable
    - `image_url` string, nullable
    - `users` InitialUser[], nullable: A list of users to add to the space at creation time. Each user can be specified by user_id or email. Users must already exist and be members of the organization.
      - `user_id` string, nullable: The ID of an existing user in the organization. At least one of user_id or email must be provided.
      - `email` string, nullable: The email of an existing user in the organization. At least one of user_id or email must be provided.
    - `template_id` string, uuid, nullable: Account template to create the space from. Required when `custom_fields` is supplied.
    - `custom_fields` object, nullable: Custom field values to set at creation, keyed by custom field ID (UUID). IDs come from the template's custom fields endpoint. Fields you omit keep their template default value. Requires `template_id`; supplying `custom_fields` without it is rejected with `422`.
  - CreateProjectRequest
    - `type` 'project', required
    - `name` string, nullable
    - `template_id` string, uuid, required
    - `status_id` string, required
    - `parent_id` string, nullable
    - `external_ids` object, nullable: Identifiers for this space in integrated third-party systems, keyed by system. Only these keys are accepted: `azure_devops`, `hubspot`, `jira`, `linear`, `salesforce`, `snow_acct`, `snow_opp`. Any other key is rejected with `400`. To store an identifier from another system (for example a NetSuite customer ID), add a custom field to the template and set it through `custom_fields` instead. Creation is idempotent on these identifiers: if a space of the same `type` in the organization already carries any of them, nothing is created and that existing space is returned unchanged, so a timed-out create can be safely retried.
    - `description` string, nullable
    - `start_date` string, date-time, nullable
    - `end_date` string, date-time, nullable
    - `pinned` boolean, nullable
    - `plan_pattern` string, nullable
    - `crm_link` CrmLinkRequest
      - `provider` 'hubspot' | 'salesforce', required
      - `deal_id` string, nullable
      - `deal_url` string, nullable
    - `users` InitialUser[], nullable: A list of users to add to the space at creation time. Each user can be specified by user_id or email. Users must already exist and be members of the organization.
      - `user_id` string, nullable: The ID of an existing user in the organization. At least one of user_id or email must be provided.
      - `email` string, nullable: The email of an existing user in the organization. At least one of user_id or email must be provided.
    - `custom_fields` object, nullable: Custom field values to set at creation, keyed by custom field ID (UUID). IDs come from the template's custom fields endpoint. Fields you omit keep their template default value.

## Response `200`

Successful Response

- SpaceResponse
  - `id` string, required
  - `external_ids` object, nullable, required
  - `parent_id` string, nullable, required
  - `type` 'organization' | 'account' | 'project', required: Scope of the space. The v2 spaces API is organization-scoped, so only `organization`, `account`, and `project` spaces are ever returned; personal spaces (`organization_id IS NULL`) are never returned by these endpoints.
  - `name` string, required
  - `created_at` string, required
  - `crm_integration` CrmIntegration
    - `deal` CrmDeal
      - `id` string, required
      - `name` string, required
      - `amount` number, nullable
      - `stage` string, nullable
      - `close_date` string, nullable
      - `currency` string, nullable
      - `external_url` string, nullable
      - `provider` 'hubspot' | 'salesforce', required

## Other responses

- `422`: Validation Error

## Changes

- **2026-09-01** `aeb6faa3b8f0`: 1 breaking, 4 info
  - the `anyOf[subschema #2: CreateProjectRequest]/template_id` request property format changed from no format to `uuid`
  - added the new optional request property `anyOf[subschema #1: CreateAccountRequest]/custom_fields`
  - added the new optional request property `anyOf[subschema #1: CreateAccountRequest]/template_id`
  - added the new optional request property `anyOf[subschema #2: CreateProjectRequest]/custom_fields`
  - …1 more

[Operation history](https://skmtc.dev/getauctor/apis/getauctor-api/changes/v2/spaces/post.md)

---

[API](https://skmtc.dev/getauctor/apis/getauctor-api.md) - [All operations](https://skmtc.dev/getauctor/apis/getauctor-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getauctor/apis/getauctor-api/revisions/be39c59c13f6?raw)