Skip to main content

​
Overview

Workspaces represent physical locations, branches, or departments within your organization. Each workspace can have its own:
  • Inventory levels
  • Users and permissions
  • Sales and operational data
  • Preferred document settings
Resources like invoices, products, and contacts can be scoped to specific workspaces, enabling multi-location inventory management and reporting.

​
Workspace Object

​
id
integer
Unique identifier for the workspace
​
name
string
Workspace name (e.g., “Main Store”, “Warehouse”, “Branch 2”)
​
owner_id
integer
User ID of the workspace owner
​
created_at
timestamp
Creation timestamp
​
updated_at
timestamp
Last update timestamp
​
members
array
Array of users who have access to this workspace
​
owner
object
Workspace owner details

​
List Workspaces

Retrieve all workspaces the authenticated user has access to.

​
Response

{
  "data": [
    {
      "id": 1,
      "name": "Main Store",
      "owner_id": 1,
      "owner": {
        "id": 1,
        "name": "Admin User",
        "email": "[email protected]"
      },
      "is_owner": true,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": 2,
      "name": "Warehouse",
      "owner_id": 1,
      "owner": {
        "id": 1,
        "name": "Admin User",
        "email": "[email protected]"
      },
      "is_owner": false,
      "created_at": "2024-02-01T00:00:00Z",
      "updated_at": "2024-02-01T00:00:00Z"
    }
  ]
}

​
Example

curl -X GET https://acme.yourdomain.com/api/v1/workspaces \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"
Users only see workspaces they have access to. Users with the view_all_locations permission can see all workspaces in the tenant.

​
Create Workspace

Create a new workspace.

​
Request Body

​
name
string
required
Workspace name (must be unique within the tenant)

​
Response

{
  "data": {
    "id": 5,
    "name": "New Branch",
    "owner_id": 1,
    "created_at": "2024-03-20T14:00:00Z"
  },
  "message": "¡Sucursal creada correctamente!"
}

​
Example

curl -X POST https://acme.yourdomain.com/api/v1/workspaces \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "New Branch"}'
When you create a workspace, you automatically become its owner and are added as a member. The workspace becomes your current active workspace.

​
Update Workspace

Update workspace details.

​
Path Parameters

​
id
integer
required
Workspace ID

​
Request Body

​
name
string
New workspace name

​
Response

{
  "data": {
    "id": 5,
    "name": "Updated Branch Name",
    "updated_at": "2024-03-20T15:00:00Z"
  },
  "message": "¡Sucursal actualizada correctamente!"
}
Only workspace owners can update workspace settings.

​
Switch Workspace Context

Switch your current active workspace. This affects which workspace is used by default for subsequent operations.

​
Path Parameters

​
id
integer
required
Workspace ID to switch to

​
Response

{
  "data": {
    "current_workspace_id": 3,
    "workspace": {
      "id": 3,
      "name": "Warehouse"
    }
  },
  "message": "Workspace context updated."
}

​
Example

curl -X PATCH https://acme.yourdomain.com/api/v1/workspace-context/3 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"
Switching workspace context updates your user’s current_workspace_id. All subsequent requests will use this workspace by default unless you specify a different one with the X-Workspace-ID header.

​
Clear Workspace Context

Clear the current workspace context (useful for operations that don’t require a specific workspace).

​
Path Parameters

​
id
integer
required
Workspace ID

​
Response

{
  "message": "Workspace context cleared."
}

​
Workspace Members

​
List Members

Retrieve all members of the current workspace.

​
Response

{
  "data": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "[email protected]",
      "role": "admin",
      "added_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": 2,
      "name": "Jane Smith",
      "email": "[email protected]",
      "role": "member",
      "added_at": "2024-02-15T10:00:00Z"
    }
  ]
}

​
Update Member Role

Update a workspace member’s role.

​
Request Body

​
role
string
required
Role name: admin, member, viewer, or custom role

​
Response

{
  "message": "Member role updated successfully."
}

​
Remove Member

Remove a user from the workspace.
You cannot remove the workspace owner. Transfer ownership first if needed.

​
Response

{
  "message": "Member removed from workspace."
}

​
Workspace Invitations

​
Send Invitation

Invite a user to join the workspace.

​
Request Body

​
email
string
required
Email address of the user to invite
​
role
string
default:"member"
Role to assign to the invited user

​
Response

{
  "data": {
    "id": 45,
    "email": "[email protected]",
    "role": "member",
    "token": "abc123def456",
    "expires_at": "2024-03-27T14:00:00Z"
  },
  "message": "Invitation sent successfully."
}
The invited user will receive an email with a link to accept the invitation. The invitation expires after 7 days.

​
Workspace Roles

​
List Roles

Retrieve all roles available in the workspace.

​
Response

{
  "data": [
    {
      "id": 1,
      "name": "admin",
      "display_name": "Administrator",
      "permissions": [
        "invoices:view",
        "invoices:create",
        "invoices:edit",
        "invoices:delete",
        "products:view",
        "products:create"
      ]
    },
    {
      "id": 2,
      "name": "member",
      "display_name": "Member",
      "permissions": [
        "invoices:view",
        "invoices:create",
        "products:view"
      ]
    }
  ]
}

​
Create Custom Role

Create a custom role for the workspace.

​
Request Body

​
name
string
required
Role name (unique, alphanumeric with underscores)
​
display_name
string
required
Human-readable role name
​
permissions
array
required
Array of permission identifiers

​
Response

{
  "data": {
    "id": 15,
    "name": "sales_rep",
    "display_name": "Sales Representative",
    "permissions": [
      "invoices:view",
      "invoices:create",
      "quotations:view",
      "quotations:create",
      "contacts:view"
    ]
  },
  "message": "Role created successfully."
}

​
Update Role

Update a custom role’s permissions.
Built-in roles (admin, member) cannot be modified. You can only update custom roles.

​
Delete Role

Delete a custom role. Users assigned to this role will need to be reassigned.

​
Workspace Settings

​
Set Preferred Document Subtype

Set the preferred document subtype (NCF sequence) for a workspace.

​
Response

{
  "message": "Preferred document subtype updated."
}

​
Multi-Workspace Operations

When working with multiple workspaces:
  1. Default Context: Operations use your current_workspace_id by default
  2. Override Context: Use the X-Workspace-ID header to specify a different workspace
  3. Permission Check: You must have access to the specified workspace

​
Example: Create Invoice in Specific Workspace

curl -X POST https://acme.yourdomain.com/api/v1/invoices \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Workspace-ID: 3" \
  -H "Content-Type: application/json" \
  -d '{...}'
Stock levels, invoices, and contacts are automatically scoped to the workspace context. You cannot access another workspace’s resources without proper permissions.

Inventory

Workspace-specific stock levels

Users

Manage workspace members and roles

Permissions

Configure role-based access control

Build docs developers (and LLMs) love

Get started for freeTalk to us