Skip to content

Workspace Management

Workspaces are the foundation of every CarvOS integration. Each workspace maps one of your clients (tenants) to a CarvOS organization. You must provision a workspace before you can push candidates, vacancies, applications, or use meeting intelligence for that client.

Prerequisites

Entity Mapping

CarvOS maps your ATS identifiers to internal entities:

Your ATS CarvOS Sent Via
Client (client_id) Workspace X-ATS-Client-ID header
User (user_id) Member X-ATS-User-ID header

Every API request includes these headers so CarvOS knows which workspace and member the operation belongs to.

Step 1: Create a Workspace

Workspace creation includes an initial admin member. Provide the admin's name and email alongside the workspace details — the admin is provisioned automatically.

curl -X POST "https://api.carvos.io/v1/workspaces" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "acme-corp",
    "name": "Acme Corp",
    "admin_name": "Admin User",
    "admin_email": "admin@acme.com"
  }'

curl -X POST "https://api.carvos.io/v1/webhooks/your-ats-id" \
  -H "X-Webhook-Signature: t=1234567890,v1=abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "event": "workspace.created",
    "event_id": "evt-ws-001",
    "client_id": "acme-corp",
    "user_id": "admin-user",
    "name": "Acme Corp",
    "admin_name": "Admin User",
    "admin_email": "admin@acme.com"
  }'

Warning

Wait for the workspace.provisioned outgoing webhook before sending any entities to this workspace. Requests sent before provisioning completes will fail.

See the API Reference for the full schema.

Step 2: Add Members

Each user in your client's organization who will interact with CarvOS (e.g., recruiters, hiring managers) should be added as a member:

curl -X POST "https://api.carvos.io/v1/workspaces/acme-corp/members" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "recruiter-001",
    "name": "Jane Smith",
    "email": "jane@acme.com"
  }'

CarvOS confirms with a workspace.member_added outgoing webhook.

See the API Reference for the full member schema.

Step 3: Use the Workspace

Once provisioned, use the workspace's client_id in request headers to push entities:

curl -X POST "https://api.carvos.io/v1/candidates" \
  -H "X-API-Key: your-api-key" \
  -H "X-ATS-Client-ID: acme-corp" \
  -H "X-ATS-User-ID: recruiter-001" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

All entities (candidates, vacancies, applications) are scoped to the workspace identified by X-ATS-Client-ID.

Managing Workspaces

Updating

Update workspace details via the workspace.updated incoming webhook or the REST API.

Removing Members

Remove members via the member.deleted incoming webhook or the REST API.

Deleting

Delete a workspace via the workspace.deleted incoming webhook or the REST API. This removes the workspace and all its members.

Outgoing Events Reference

Event When
workspace.provisioned Workspace is ready for use
workspace.member_added Member added to workspace

For full event payload schemas, see the API Reference.

Incoming Events Reference

Event When
workspace.created Create a new workspace
workspace.updated Update workspace details
workspace.deleted Remove a workspace
member.created Add a member
member.deleted Remove a member

Next Steps