The Valuecase API lets you create Spaces automatically from external systems such as your CRM, signup flow, website forms, or internal onboarding tools.
This is useful when you want to create a customer Space without creating it manually in Valuecase; for example when a new deal is closed, a customer signs up, or an onboarding project starts.
This article explains how to create Spaces via API and when to use synchronous or asynchronous Space creation.
Before You Start
To create Spaces via API, you need API credentials.
In Valuecase, go to Administration → Developer to find your API credentials.
Valuecase uses token-based authentication. Include the token in every API request:
Authorization: Bearer <token>
API docs:
Authentication: https://app.valuecase.com/dashboard/api/docs
Spaces API: https://app.valuecase.com/spaces/api/docs#/
Choosing the Right Creation Method
There are two ways to create Spaces via API:
Method | Best for | How it works |
Synchronous creation | Simple workflows where your system can wait for the result | The API returns the created Space directly |
Asynchronous creation | More reliable workflows, larger templates, or higher-volume automations | The API returns a request ID, which you use to check when the Space is ready |
If you are unsure, use synchronous creation for simple automations and asynchronous creation for production workflows where reliability is more important than getting the result in a single request.
Option 1: Create a Space Synchronously
Synchronous creation creates the Space and returns the finished Space in the same request.
Use this when:
You create Spaces one at a time
Your system can wait for the Space to be created
You need the Space URL immediately in the next step
Step 1: Send the Space Creation Request
POST /spaces
Authorization: Bearer <token>
Example body:
{
"templateId": "ze3ljqvzwaw8ufyitv6jdq08",
"ownerId": null,
"ownerEmail": "[email protected]",
"integrationIds": [
{
"thirdParty": "Custom",
"thirdPartyEntityType": "Lead",
"thirdPartyId": "1954687215",
"thirdPartyOrganizationId": "1954687215"
}
],
"customProperties": [
{
"name": "country_code",
"value": "DE"
},
{
"name": "departments",
"values": ["Sales", "Marketing"]
}
],
"teamIds": ["team1", "team2"],
"data": {
"companyName": "Example Inc.",
"companyWebsite": "https://example.com",
"contactEmail": "[email protected]",
"contactFirstName": "First",
"contactLastName": "Last",
"companyLogoUrl": "https://example.com/logo.png",
"blockNavigationEnabled": true,
"commentsOpenByDefault": true
}
}Step 2: Use the Created Space
When the Space is created successfully, the API returns the created Space.
Example response:
{
"id": "yp8gw6jc85sg3fyefg1yept7",
"slug": "tesla",
"createdAt": "2026-05-21T17:09:42.266Z",
"ownerId": "valuecase|99ad6b1a-c49d-4b51-8d39-e9590687b50b",
"url": "https://share.valuecase.com/spaces/demo?token=123",
"authToken": "6e52a46c8f1"
}You can use the returned Space data to:
Store the Space ID in another system
Add the Space URL to your CRM
Send the Space link to a customer
Trigger the next step in your onboarding workflow
Option 2: Create a Space Asynchronously
Asynchronous creation starts the Space creation process and returns a request ID. You can use this ID to check when the Space is ready.
Use this when:
You create many Spaces
Your template is complex
Your automation should not depend on one long-running request
You want a more reliable setup for production workflows
Step 1: Start Space Creation
POST /spaces/async
Authorization: Bearer <token>
Use the same request body as synchronous Space creation.
Example body:
{
"templateId": "ze3ljqvzwaw8ufyitv6jdq08",
"ownerEmail": "[email protected]",
"customProperties": [
{
"name": "country_code",
"value": "DE"
}
],
"data": {
"companyName": "Example Inc.",
"contactEmail": "[email protected]"
}
}Example response:
{
"requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}The response means that the creation request was accepted. The Space is not finished yet.
Step 2: Check the Creation Status
Use the request ID to check the creation status.
GET /spaces/async/{id}/status
Authorization: Bearer <token>Example response:
{
"requestId": "3fa85f64-...",
"status": "QUEUED",
"spaceId": null,
"error": null,
"createdAt": "2026-05-21T10:00:00.000Z",
"completedAt": null
}
Possible statuses:
Status | Meaning |
| The request is waiting to be processed |
| The Space is being created |
| The Space was created successfully |
| The Space could not be created |
Poll every 1–2 seconds until the status is either COMPLETED or FAILED.
Once the status is COMPLETED, the response includes the spaceId.
Step 3: Fetch the Created Space
Use the spaceId to retrieve the created Space.
GET /spaces/{spaceSlug}
Authorization: Bearer <token>The response includes the Space details, including the Space URL and authentication token.
Understanding the Request Body
When creating a Space, you can pass the following information.
Template
Use templateId to define which Valuecase template should be used.
{
"templateId": "ze3ljqvzwaw8ufyitv6jdq08"
}Owner
Use either ownerId or ownerEmail to assign the Space to a specific owner.
{
"ownerEmail": "[email protected]"
}Integration IDs
Use integrationIds to connect the Space to an external system, such as a CRM record.
{
"integrationIds": [
{
"thirdParty": "Custom",
"thirdPartyEntityType": "Lead",
"thirdPartyId": "1954687215",
"thirdPartyOrganizationId": "1954687215"
}
]
}This is useful when you want to keep Valuecase Spaces linked to deals, opportunities, leads, or onboarding projects in another system.
Custom Properties
Use customProperties to pass values into Space Properties.
For single-value properties, use value:
{
"name": "country_code",
"value": "DE"
}For multi-value properties, use values:
{
"name": "departments",
"values": ["Sales", "Marketing"]
}Custom properties can be used for personalization, content visibility, reporting, and workflow automation.
Teams
Use teamIds to assign the Space to one or more teams.
{
"teamIds": ["team1", "team2"]
}Space Data
Use data to pass standard Space information such as company and contact details.
{
"data": {
"companyName": "Example Inc.",
"companyWebsite": "https://example.com",
"contactEmail": "[email protected]",
"contactFirstName": "First",
"contactLastName": "Last",
"companyLogoUrl": "https://example.com/logo.png"
}
}You can also pass Space settings such as:
{
"blockNavigationEnabled": true,
"commentsOpenByDefault": true
}