Workspaces

Workspaces is a RESTful API that you can use to manage the workspaces where your typeforms are stored. Use the Workspaces API to add and delete workspaces, give Typeform team members access to your workspaces (and revoke access as needed), and move typeforms in and out of different workspaces — all without using the Typeform admin panel.

Need help with an error? Head to Troubleshooting and errors for information about Workspaces errors.

PRO+ account holders can invite anyone with a Typeform account to collaborate on typeforms in shared workspaces.

All Typeform accounts start with a default workspace, known as "My Workspace." The typeforms you create are automatically stored there. You cannot delete the default "My Workspace," even if you rename it.

As you create more typeforms, you can add multiple workspaces to keep your typeforms organized. For example, you can create workspaces to organize your typeforms by the quarters of the year, company departments, or specific campaigns. Then, you can create new typeforms in each workspace.

In your workspaces, typeforms are always listed in order of creation, starting with the most recent. Account holders have access to all workspaces in their accounts, except team members’ personal workspaces.

Data privacy

To protect data privacy, you can specify which team members can access each of your workspaces. For example, you may want your designers and developers to collaborate on creating a new typeform, although you do not want them to have access to the typeform's results. In this case, you can create separate "Design and Develop" and "Results" workspaces. If you give your design and development team members access to only the "Design and Develop" workspace, you can just move the typeform into the "Results" workspace when it's ready to go live, and your designers and developers will no longer have access to the typeform or its results.

Move typeforms

You can move existing typeforms to different workspaces, whether to protect data privacy, manage your data collection and analysis pipeline, or just keep your typeforms organized.

For example, suppose you set up workspaces for each stage in your data collection process. A typeform might start in the "Copywriting" workspace, then move to the "Design" workspace, then to the "Data" workspace when it's ready to go live, and finally to the "Archive" workspace when you've collected all the results and ended the campaign.

Moving a typeform from one workspace to another does not affect the typeform's configuration or results.

Add a workspace

Imagine you want to create workspaces for each stage in your data collection and analysis process: Development, Collection, and Analysis. To do this, send three requests to POST https://api.typeform.com/workspaces, specifying the names of the workspaces as values for name. Here's what the request looks like in cURL:

curl -X POST \
  https://api.typeform.com/workspaces \
  -H 'Authorization: bearer {your_access_token}' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Development"}'

The JSON response will include:

• The total number of typeforms in the workspace (since this is a new workspace, the number of typeforms will be 0).
• The URL for the workspace (href).
• The workspace ID, which you'll need when you want to update the workspace.
• A list of the team members who have access to the workspace (you will be the only team member listed for a new workspace)

Repeat this request two more times to add the "Collection" and "Analysis" workspaces.

Update a workspace name

Suppose that you renamed the "Development" stage to "Design and Development." To change the workspace name, you'll use PATCH https://api.typeform.com/workspaces/{workspace_id}. Here's the request in cURL:

curl -X PATCH \
  https://api.typeform.com/workspaces/{workspace_id} \
  -H 'Authorization: bearer {your_access_token}' \
  -H 'Content-Type: application/json' \
  -d '[{"op":"replace","path":"/name","value":"Design and Development"}]'

Add and remove team members in a workspace

Imagine that you're getting ready to start a new research campaign. You need to make sure the right team members have access to your "Research Campaign" workspace. Here's the workflow:

1. Get the workspace ID for the "Research Campaign" workspace: send a request to GET https://api.typeform.com/workspaces. The response will list all the workspaces in your account, along with their workspace IDs. Make a note of the "Research Campaign" workspace's ID.

2. Find out which team members currently have access to the "Research Campaign" workspace by sending a request to GET https://api.typeform.com/workspaces/{workspace_id}. Replace {workspace_id} in the request URL with the "Research Campaign" workspace ID you collected in step 1. The JSON response will list the team members who currently have access.

3. Based on the list of team members who currently have access to the "Research Campaign" workspace, suppose you need to remove Rachel and add Samuel. Confirm that you have the email addresses Rachel and Samuel are using for their Typeform accounts. When you add Samuel, you have an option to choose what role Samuel will have in the workspace. Let's assume the email addresses are rachel123@email.com and samuel123@email.com and we choose 'can edit' role for Samuel.

4. Send a request to PATCH https://api.typeform.com/workspaces/{workspace_id}, using the operator remove for Rachel and add for Samuel. Here's what the request looks like in cURL:

curl -X PATCH \
  https://api.typeform.com/workspaces/{workspace_id} \
  -H 'Authorization: bearer {your_access_token}' \
  -H 'Content-Type: application/json' \
  -d '[{"op":"remove","path":"/members","value":{"email":"rachel123@email.com"}}]' \
  -d '[{"op":"add","path":"/members","value":{"email":"samuel123@email.com","role":"member"}}]'

Add and remove forms in a workspace

Before you start the new research campaign, you want to move any old typeforms from the "Research Campaign" workspace to the "Archive" workspace and create a new typeform in the "Research Campaign" workspace to get the team started. First, you'll move the old forms to the "Archive" workspace and then you'll create the new form in the "Research Campaign" workspace. Here's the workflow:

1. Get the workspace IDs for both workspaces by sending a request to GET https://api.typeform.com/workspaces. The response will list all the workspaces in your account, along with their workspace IDs. Make a note of the "Archive" and "Research Campaign" workspace IDs.

2. Find out which typeforms are currently in the "Research Campaign" workspace by sending a request to GET https://api.typeform.com/forms?workspace_id={workspace_id}. The response will list all the typeforms in the workspace, along with their form IDs.

3. Move the old typeforms to the "Archive" workspace by sending one request per form to PATCH https://api.typeform.com/forms/{form_id}. Here's what it looks like in cURL:

curl -X PATCH \
  https://api.typeform.com/forms/{form_id} \
  -H 'Authorization: bearer {your_access_token}' \
  -H 'Content-Type: application/json' \
  -d '[{"op":"replace","path":"/workspace","value":{"href":"https://api.typeform.com/workspaces/{archive_workspace_id}"}}]'

4. Add the new typeform in the "Research Campaign" workspace by sending a request to POST https://api.typeform.com/forms.

Read up on our Create API. The Workspaces API works in concert with Create to give you complete control over how typeforms are organized into your workspaces.

To learn more about how our APIs work, check out the Get started page. If you have a Typeform personal access token and know how to use it, head to the Workspaces endpoints documentation.