API Reference

Validate an activation token.

Called when user clicks the activation link in their email.
Returns user and workspace info if valid.

Does NOT require authentication - the token is the authentication.

Get current user information.

If workspace_id is provided, also returns the member record for that workspace.

Stream provisioning progress via Server-Sent Events.

No authentication required - the job_id acts as a secret token.

Events:
• status: RUNNING, COMPLETED, FAILED
• progress: 0-100
• current_step: validating, creating_user, running_migrations, etc.
• result.message: Human-readable status message

On COMPLETED:
• result.access_token, result.refresh_token
• result.workspace_id, result.workspace_name

Get details about a Stripe payment invite.

This endpoint is used when a user clicks the registration link from
their onboarding email after paying via Stripe Checkout.

Does NOT require authentication - the invite code is the authentication.

Get user information by ID

Requires permission to view the user (must have same or higher role).

Complete account activation by setting password.

Called after user enters their password in the activation form.
Returns access tokens on success.

Does NOT require authentication - the token is the authentication.

Resend activation email to a user.

Useful if the original email was lost or expired.

Check if a Clerk-authenticated user exists in our database.

This endpoint is called from the frontend after a user signs in with Clerk.
It does NOT create users - users must go through our signup/payment flow first.

Flow:
1. Frontend authenticates user via Clerk
2. Frontend calls this endpoint with Clerk user info
3. We check if user exists by email (or clerk_id if stored)
4. If exists: return tokens for session
5. If not exists: return { exists: false } - frontend redirects to payment

Security: This endpoint is protected by X-Clerk-Secret header validation.

Exchange an impersonation token for user authentication tokens.

This endpoint is called by the frontend to convert an impersonation token
into a regular user session. The token must be valid and not expired.

Security:
• Token is verified and decoded
• Token must have type="impersonation"
• User must exist and be active
• Token expiration is checked

Login user

Logout user (client should delete tokens)

Look up a payment invite by email address.

Used by the /final-process page where users enter their email and access code
to find their invite and continue to registration.

Access code is validated but not strictly enforced for security through obscurity.

Does NOT require authentication.

Upload profile picture for current user

Refresh access token

Register a new user (legacy endpoint - use /signup for full registration)

Request a password reset email

This endpoint will:
1. Find the user by email
2. Generate a secure password reset token
3. Store the token with expiration (1 hour)
4. Send password reset email with token link

Note: For security, this endpoint always returns success even if user doesn't exist

Reset password using the token from email

This endpoint will:
1. Validate the reset token
2. Check token expiration
3. Update user's password
4. Clear the reset token

Complete registration flow with workspace creation and Stripe trial.

This endpoint:
1. Creates user account
2. Creates workspace based on company name
3. Provisions tenant database with migrations
4. Creates Member record in tenant database
5. Seeds initial data (actions, recordsets)
6. Creates Stripe customer and subscription with 3-day trial

If payment_method_id is provided:
• Creates subscription immediately with trial
• User is charged automatically after trial ends unless canceled

If payment_method_id is NOT provided:
• Returns a Stripe Checkout URL for payment
• User must complete checkout to activate subscription

Complete registration using a Stripe payment invite.

This endpoint is for users who have already paid via Stripe Checkout
but don't have an account yet. Their payment is already processed,
so we just need to:

1. Validate the invite code
2. Create user account
3. Create workspace
4. Provision tenant database
5. Link workspace to existing Stripe subscription
6. Mark invite as used

Does NOT require authentication - the invite code is the authentication.

Password is optional if clerk_id is provided (user authenticated via Clerk social login).
In that case, a random secure password is generated - the user will sign in via Clerk.

Async signup with streaming progress.

Returns immediately with a job_id. Client should connect to the
stream endpoint to receive real-time progress updates.

When provisioning completes, the stream will include tokens and
workspace info for the client to use.

Flow:
1. POST /signup/stripe-invite/async -> {job_id, stream_url}
2. GET /signup/jobs/{job_id}/stream -> SSE stream with progress
3. On COMPLETED event: {access_token, workspace_id, ...}

Upload profile picture for a user

• POST /me/avatar: Upload for current user
• POST /{user_id}/avatar: Upload for another user (requires permission)

Uploads to Google Cloud Storage with path:
{bucket_name}/{workspace_id}/profile-image/{filename}

Update current user profile

Update user profile by ID

Requires permission to edit the user (must have same or higher role).
Can update: name, email, title, phone, bio, avatar_url, role.

List all workspaces for the current user

Get invitation details without accepting it

This endpoint does NOT require authentication - used to check if user needs to set password.

Get a specific workspace

List all members of a workspace with their status

Shows:
• Active members
• Pending invitations (users who haven't accepted yet)
• Member details (email, name, role, etc.)

Create a new workspace

The workspace database is provisioned with an empty schema.
No sample data is seeded - tenants start with a clean slate.

Accept a workspace invitation using the token from email

This endpoint does NOT require authentication - the token is the authentication.
If the user doesn't have a password, one must be provided.
After accepting, the user can log in and access the workspace.

Cancel a pending workspace invitation

Requires admin or owner role in the workspace.

Provision a new workspace with an owner (Admin/Superuser only).

This will:
1. Check if user with email exists, if not create them
2. Create the workspace
3. Create WorkspaceMember (owner role) in main database
4. Provision tenant database with migrations
5. Create Member in tenant database

Requires: current_user must be is_superuser or is_staff

Switch to a different workspace

Invite a user to a workspace via email

The user must already be registered in the system. They will receive
an email with an invitation link to join the workspace.

Requires admin or owner role in the workspace.

Generate an invite link without sending email.

Returns the invite URL for copying/sharing via Slack etc.
Generates a new token (invalidates any previous token).

Requires admin or owner role in the workspace.

Resend an invitation email to a user

Generates a new invitation token and sends a new email.

Requires admin or owner role in the workspace.
Accepts either member_id (WorkspaceMember ID) or user_id (User ID).

Send a password reset email for a workspace member (admin-triggered).

Requires admin or owner role in the workspace.

Generate a password reset link without sending email.

Returns the reset URL for copying/sharing via Slack etc.
Uses 24-hour expiry (longer than email-triggered resets).

Requires admin or owner role in the workspace.

Update a workspace (requires owner or admin role)

Remove a member from a workspace

Handles three scenarios:
1. If member hasn't accepted invite: Delete WorkspaceMember and InvitationToken
2. If they have accepted invite: Delete Member from tenant DB, then WorkspaceMember
3. If they have no other workspace memberships: Also delete the User

Requires admin or owner role in the workspace.

List all members in the current workspace with pagination support.

Note: Members table is in tenant database, but we join with Users from main database

Get all workspace members with minimal fields for client-side caching.

Returns all active members without pagination. Designed for efficient
bulk loading into browser memory for instant access in dropdowns,
@mentions, and assignment selectors.

Fields returned: id, email, full_name, display_name, avatar_url, role

Get the current member's full profile.

Returns the authenticated user's member record for the current workspace,
including their role, profile information, and onboarding status.

Get the current member's onboarding tour completion status.

Returns a dictionary of tour IDs to completion status.

Get a specific member by ID

Get deletion info for a member.

Returns:
• workspace_count: Number of workspaces this user belongs to
• can_delete_user: True if user can be permanently deleted (only in 1 workspace)

Get all items owned by or assigned to a member.

This is used for offboarding to show what needs to be reassigned
before removing a member from the workspace.

Create a new member (invite to workspace)

This will:
1. Check if user exists in main database
2. Create WorkspaceMember in main database
3. Create Member in tenant database

Update a tour's completion status for the current member.

Call this when a user completes or skips a tour.

Upload a profile avatar for a member.

• Members can upload their own avatar
• Admins/owners can upload avatars for any member
• Files are stored in GCS (cloud) or local uploads folder (development)
• Returns a signed URL for GCS or local path

Bulk reassign all items from one member to another.

This should be called before removing a member from the workspace
to ensure continuity of ownership for actions, goals, records, etc.

Update a member

Reset tour completion status for the current member.

If tour_id is provided, resets only that tour.
If tour_id is None, resets all tours.

Remove a member from workspace

This will:
1. Delete Member from tenant database
2. Optionally remove WorkspaceMember from main database

Permanently delete a user and remove them from all workspaces.

This will:
1. Check if user is only in this workspace (required)
2. Delete Member from tenant database
3. Delete WorkspaceMember from main database
4. Delete User from main database

CAUTION: This action is irreversible!

List all teams in the current workspace.

Get a specific team by ID

List all members of a team

Create a new team (requires can_create_team permission)

Add a member to a team

Update a team

Update a team member's role

Delete a team (requires can_delete_team permission)

Remove a member from a team

List all available permissions.

Optionally filter by resource (e.g., "action", "member").

Check if the current user has a specific permission.

Returns true/false based on the user's role and the permission settings.

List all permissions grouped by resource for easier UI display.

Get the current user's permissions based on their role.

Get permissions for all roles.

Returns a dict mapping each role to its permissions.
Only admins and owners can view this.

Get all permissions for a specific role.

Reset a role's permissions to defaults.

This removes all custom permission settings and reverts to the
default permissions defined in the system.

Seed default permissions for this workspace.

This creates all the standard permissions if they don't exist.
Usually called automatically when a workspace is created.

Update multiple permissions for a role at once.

Only workspace admins and owners can modify permissions.
Owner permissions cannot be modified.

Set a single permission for a role.

Only workspace admins and owners can modify permissions.

List all API keys for the current company.

Query parameters:
• skip: Number of keys to skip (pagination)
• limit: Maximum number of keys to return
• is_active: Filter by active status
• is_revoked: Filter by revoked status

Returns:
• List of API keys (without full keys, only prefixes shown)

Get total count of API keys.

Query parameters:
• is_active: Filter by active status
• is_revoked: Filter by revoked status

Returns:
• {"count": number}

Get a specific API key by ID.

Returns:
• API key object (full key is NOT included, only prefix)

Create a new API key.

IMPORTANT: The full API key is only shown once in this response.
Store it securely - you won't be able to retrieve it again!

Required permissions: Admin or API key management permission

Returns:
• API key object with full key (only shown once!)

Revoke an API key.

Revoked keys cannot be used for authentication and cannot be un-revoked.
The key record is kept for audit purposes.

Required permissions: Admin or API key management permission

Returns:
• Revoked API key object

Rotate an API key (generate new key, revoke old one).

This creates a new API key with the same settings and revokes the old one.
The new key is only shown once in this response!

Required permissions: Admin or API key management permission

Returns:
• New API key object with full key (only shown once!)

Toggle API key active status (enable/disable).

This allows you to temporarily disable a key without revoking it.

Returns:
• Updated API key object

Update an API key.

You can update the name, description, scopes, and active status.
You cannot change the key itself - use the rotate endpoint for that.

Required permissions: Admin or API key management permission

Returns:
• Updated API key object

Delete an API key.

This permanently removes the API key. Consider using the revoke endpoint
instead if you want to keep the key record for audit purposes.

Required permissions: Admin or API key management permission

Returns:
• 204 No Content on success

Get default/recommended notification preferences.

Returns the recommended notification settings for new users,
organized by category (Assigned Actions, Owned Actions, etc.).

Returns:
• Dictionary of notification types with recommended settings

Get the current user's email delivery preference.

Email delivery modes:
• instant: Send email notifications immediately when events occur
• digest: Batch notifications into periodic digest emails

Digest frequency options:
• 30: Every 30 minutes
• 60: Every hour

Returns:
• email_delivery_mode: "instant" or "digest"
• digest_frequency_minutes: "30" or "60"

Get notifications for the current user.

Parameters:
• unread_only: If true, only return unread notifications
• limit: Max number of notifications to return (default 50)
• offset: Number of notifications to skip (for pagination)

Returns:
• List of notifications with total count

Get notification preferences for the current user.

Returns:
• List of notification preferences for the authenticated user

Get all notification preferences for the current user (v2 format).

Returns preferences for all event types, with defaults filled in.

Returns:
• Dictionary of event types to their preference settings

Server-Sent Events (SSE) endpoint for real-time notifications.

Connect via the Next.js proxy at /api/notifications/stream which handles auth.

Usage:
```javascript
// Frontend uses Next.js proxy (auth via cookies)
const eventSource = new EventSource('/api/notifications/stream', {
withCredentials: true
});

eventSource.addEventListener('notification', (event) => {
const notification = JSON.parse(event.data);
console.log('New notification:', notification);
});

// Workspace events (e.g., members_updated):
eventSource.addEventListener('workspace_event', (event) => {
const data = JSON.parse(event.data);
if (data.event_type === 'members_updated') {
// Refresh member list
}
});
```

Returns:
• SSE stream with notification and workspace_event events

Get count of unread notifications.

Returns:
• {"count": <number of unread notifications>}

Mark notification(s) as read.

Request body:
• notification_id: Optional ID of specific notification to mark as read
• If not provided, marks all notifications as read

Returns:
• {"updated": <count of updated notifications>}

Create a notification preference for the current user.

Returns:
• Created notification preference

Reset notification preferences to default recommended settings.

This deletes all current preferences and creates new ones based on
the default/recommended settings.

Returns:
• List of newly created default notification preferences

Update the current user's email delivery preference.

Choose how you want to receive email notifications:

• instant: Get notified immediately when important events happen
• digest: Receive a summary email every 30 or 60 minutes with all your notifications grouped together

Digest emails are helpful to:
• Reduce email volume during busy periods
• Get a summary of what happened while you were away
• Easily identify items that need your attention (highlighted in the digest)

Request body:
• email_delivery_mode: "instant" or "digest"
• digest_frequency_minutes: "30" or "60" (only applies when mode is "digest")

Returns:
• Updated preference settings

Bulk update notification preferences for the current user.

This allows updating multiple preferences at once, which is useful
for the settings page where users can toggle many checkboxes.

Request body:
• preferences: List of preferences to update/create

Returns:
• List of updated/created notification preferences

Update a notification preference for the current user.

Returns:
• Updated notification preference

Update notification preference for a specific event type.

Parameters:
• event_type: The notification event type to update

Request body:
• inapp_enabled: Enable/disable in-app notifications
• email_enabled: Enable/disable email notifications
• whatsapp_enabled: Enable/disable WhatsApp notifications
• muted: Mute all notifications for this event type

Returns:
• Updated preference settings

Delete a notification preference.

Returns:
• 204 No Content on success

List activity export jobs for the current user.

Get the status of an activity export job.

Download an activity export file.

Returns the file content directly (for inline data) or redirects to signed GCS URL.

Get a download URL for the export file.

For GCS-stored files, returns the signed URL.
For inline-stored data, returns a data URL that can be downloaded directly.

Get the activity feed for the current workspace.

Pulls activities from the Activity model which logs events as they happen:
• Actions (created, completed, messages, files, etc.)
• Goals (created, progress updates)
• Integrations (sync events)
• Records (creates, updates, imports)
• Team (member changes)

Query Parameters:
• types: Filter by activity types (comma-separated: action,goal,record,integration,user)
• search: Search activities by description
• start_date: Filter activities from this date (ISO format)
• end_date: Filter activities until this date (ISO format)
• scope: 'mine' to show only your activities, 'all' for everyone (default: all)
• user_ids: Filter by specific user/member IDs (comma-separated)
• team_ids: Filter by team IDs (comma-separated, shows activity from team members)
• limit: Number of activities to return (default: 20, max: 100)
• offset: Pagination offset

Returns:
• List of activities sorted by timestamp (newest first)

Get activity statistics for the dashboard.

Returns counts and metrics for different activity types based on the Activity table.

Start an async activity export job.

Returns a job_id immediately. The export runs in the background.
Check job status at /api/v1/activity/export/jobs/{job_id}

When complete, the job output_data will contain a download URL.
You'll also receive a notification based on your notification settings.

List all module settings for the current company.

Returns:
• List of module settings

Get settings for a specific module.

Returns:
• Module settings object

Create settings for a module.

Required permissions: Admin

Returns:
• Created module settings

Toggle module enabled status.

Required permissions: Admin

Returns:
• Updated module settings

Update settings for a module.

Required permissions: Admin

Returns:
• Updated module settings

Get workspace health check - check what features are configured.

Returns flags indicating setup status for various features:
• brand: Whether a brand profile has been created
• migration_required: Whether tenant database migration is required
• personal_onboarding_complete: Whether the current user's onboarding is complete
• company_onboarding_complete: Whether workspace onboarding is complete

Returns HTTP 503 Service Unavailable if migration is required.
Returns HTTP 200 if everything is up to date.

Stream tenant migration progress via Server-Sent Events (SSE).

This endpoint provides real-time updates on the migration job progress.
The frontend should connect to this endpoint and listen for status updates.

Events:
• status: QUEUED, RUNNING, COMPLETED, FAILED
• progress: 0-100
• current_step: Human-readable description of current step
• error_message: Error message if status is FAILED

On COMPLETED:
• Migration is complete, workspace is ready
• Frontend should remove maintenance banner and show success toast

On FAILED:
• Migration failed, error details in error_message
• Frontend should log to Sentry and show error message

Trigger tenant database migration.

This endpoint:
1. Checks if migration is already running (prevents duplicates via Redis lock)
2. Sets a Redis lock to prevent concurrent migrations for the same workspace
3. Runs migration synchronously in the API process (has DB access)
4. Returns job_id and stream_url for progress tracking

The frontend should connect to the stream_url to receive real-time updates.

Note: Migrations run in the same API process (not job_processor) to ensure
database access. They run in a background task to avoid blocking the request.

List records from recordsets the user has access to.

If recordset_id is provided, checks can_view on that recordset.
Otherwise, returns records from all accessible recordsets.

Stream records for map display, optionally with bounding box filtering.

Returns NDJSON (newline-delimited JSON) for efficient streaming.
Each line is a JSON object with: id, geometry (GeoJSON), geometry_type, title, and optional fields.
For Point geometries, lat/lng are also included for backwards compatibility.
The final line contains metadata: {"__meta__": {"count": N, "truncated": bool}}

If bbox is not provided, all records with geometry are returned (use clustering/heatmaps for large datasets).
If limit is omitted, the response is uncapped and streams all matching records.
This endpoint is optimized for large datasets with PostGIS spatial indexing.
Supports any geometry type: Point, MultiPolygon, LineString, etc.

Get a specific record by ID.

Requires can_view permission on the parent recordset.

List all comments for a record

List version history for a record with user info

List all relationships for a record

Create a new record.

Requires can_create permission on the target recordset.

Bulk delete records.

If 'all' is True, deletes ALL records in the recordset (requires can_delete permission).
Otherwise, deletes records specified by record_ids.

For specific IDs, each record is checked:
• User needs can_delete permission on the recordset, OR
• can_delete_own if they own the record

Filter records from one recordset by spatial relationship with another.

Use cases:
• Show all leads (points) that intersect with zip codes (polygons) where income > X
• Show all properties (points) within selected census tracts (polygons)
• Exclude records that fall within certain geographic boundaries
• Show all locations within X meters of gas stations (point-to-point)

The source recordset (polygons/lines/points) is used as the filter geometry.
The target recordset (points/features) returns matching record IDs.

Buffer support:
• For WITHIN_DISTANCE: buffer_meters is the search radius (required)
• For other operations: buffer_meters expands source geometries before comparison

Create a comment on a record

Dismiss (soft remove) a record from a specific tool view.
This clears the tool status so the record no longer appears in that tool's view,
but the record itself is NOT deleted.

Restore a record to a previous version from history.

This creates a new version with the field_values from the specified history entry.
Requires can_edit permission on the parent recordset.

Create a relationship between records

Update a record (creates a new version).

Requires can_edit permission on the parent recordset,
OR can_edit_own if the current user created/owns the record.

Delete a record (soft delete by setting status=deleted).

Requires can_delete permission on the parent recordset,
OR can_delete_own if the current user created/owns the record.

List all recordsets the current user has access to.

Access is determined by:
• Workspace admins/owners see all recordsets
• Recordset owners see their owned recordsets
• Users see recordsets they have explicit grants for (direct or via team)

Automatically creates missing recordsets for actively connected integrations.

List all soft-deleted (trashed) recordsets.

These recordsets will be permanently deleted after 30 days.
Requires workspace admin/owner role to view trash.

Get the pipeline associated with a recordset

Get a specific recordset by slug with accurate record count.

Requires can_view permission on the recordset.

List all access grants for a recordset.

Requires can_admin permission on the recordset.

Get current user's permissions on a recordset.

This endpoint is always accessible to check what permissions the user has.

List all views for a recordset

Create a new recordset

Note: Database is already scoped to workspace via TenantDB dependency.
Slug is auto-generated from name if not provided, with duplicate handling.

Restore a soft-deleted recordset from trash.

Requires workspace admin/owner role.

Enable map mode on a recordset and queue GIS backfill job.

This endpoint:
1. Updates recordset settings with GIS field mapping
2. Sets recordset mode to MAP
3. Creates a background job to backfill promoted_gis_1 column

The GIS backfill processes all existing records in batches,
extracting lat/lng values from field_values and populating
the promoted_gis_1 PostGIS column for spatial queries.

Requires can_admin permission on the recordset.

Create a pipeline for a specific recordset

Grant access to a member or team on a recordset.

Requires can_admin permission on the recordset.

Either member_id OR team_id must be provided (not both).

Resync promoted columns for all records in a recordset.

Use this after changing promoted field mappings or after bulk imports.
Requires can_admin permission on the recordset.

Create a new view for a recordset

Update a recordset.

Requires can_admin permission on the recordset.
Note: Slug is NOT updated after creation to preserve bookmarks.

Update a recordset view

Permanently delete a recordset and all its records.

This action cannot be undone!
Requires workspace admin/owner role.

Soft delete a recordset (move to trash).

Sets is_active=False and deleted_at timestamp.
Recordset will be auto-purged after 30 days.
Use /trash endpoint to view deleted recordsets.
Use DELETE /trash/{slug} to permanently delete.

Requires can_admin permission on the recordset.

Revoke a member's access to a recordset.

Requires can_admin permission on the recordset.

Revoke a team's access to a recordset.

Requires can_admin permission on the recordset.

Delete a recordset view

List all records with pagination and filters.

The database is automatically scoped to the current workspace via TenantDB dependency.

Get a specific record by ID.

Create a new record.

The record will be created in the current workspace's schema.
All user references use the member (tenant-scoped user).

Update a record (full update).

This creates a new version of the record if versioning is enabled.

Partially update a record (only provided fields).

Delete a record.

This soft-deletes the record by setting is_latest to False and status to DELETED.

List all recordsets with pagination and filters.

Automatically creates missing recordsets for actively connected integrations.
Uses a single optimized query with JOIN to get record counts efficiently.

Get a specific recordset by ID with accurate record count.

Uses a single query with subquery for the count.

Create a new recordset.

Sync all recordset record counts using a single bulk UPDATE.

This is an admin utility for fixing desynchronized counters.
Uses efficient bulk update instead of loading all records into memory.

Update a recordset (full update).

Partially update a recordset.

Delete a recordset (cascades to records).

List all attachments for a record.

Upload a file attachment for a record.

• record_id: ID of the record to attach the file to
• file: File to upload (multipart/form-data)

Delete a file attachment.

List insights for a record

List interactions for a record (timeline view)

List tasks for a record

Get tracking dashboard with metrics for a recordset

Mark action taken on an insight

Dismiss an insight

Mark a task as complete

Get AI analysis of a record

Draft an AI message related to a record

Generate AI insights for a record

Log a new interaction for a record

Create a new task for a record

Generate AI follow-up suggestions for a recordset

Update an existing interaction

Update an existing task

Delete an interaction

Delete a task

List geocoding jobs for the current workspace.

Get the status of a geocoding job.

Stream geocoding job progress via Server-Sent Events (SSE).

Connect to this endpoint to receive real-time progress updates.
The stream will close when the job completes or fails.

Public endpoint to download an import error report.

Uses signed URL with expiration - no authentication required.
This allows direct browser downloads without auth headers.

List all import/export jobs for the current workspace.

Jobs are ordered by creation date (newest first).

Get detailed information about a specific import/export job.

Includes validation summary and report download URL if available.

Get a fresh signed URL for downloading the job's error report.

Signed URLs expire, so use this endpoint to get a new URL if the original has expired.

Get the status of an import job (legacy endpoint).

Use /import/jobs/{job_id} for more detailed information.

Create an export job for a recordset.

Start an async geocoding job for a recordset.

Converts address fields to lat/lng coordinates using Google Maps Geocoding API.
Returns job_id immediately. Use /geocode/jobs/{job_id}/stream for SSE progress.

The job will:
1. Find all records without coordinates
2. Extract address from specified fields
3. Geocode via Google Maps API
4. Update lat/lng fields and PostGIS geometry

Create a recordset and start async import from the uploaded file.

This endpoint:
1. Creates the recordset with the specified schema
2. Queues a background job to import records from the file
3. Returns immediately with the recordset ID and job ID

Import runs asynchronously. On completion:
• A report is generated with any validation errors
• The report is stored in GCS
• An email notification is sent to the user

Use the /import/jobs/{job_id} endpoint to check import progress.

Cancel all active (pending/queued/running/processing) import/export jobs.

Cancel a queued or running import/export job.

Cancellation is best-effort for already-running workers. Status is updated
immediately so UI reflects cancellation intent.

Import records from an uploaded file into an existing recordset.

The field_mappings should map CSV columns to existing recordset fields.
Use the /import/upload endpoint first to upload and analyze the file.

Upload a CSV/Excel/GeoJSON/JSON file and analyze its headers.

The file is uploaded to GCS and analyzed to:
• Extract column headers
• Infer field types based on sample data
• Count total rows

Returns a file URI to be used in the subsequent import step.

Analyze headers/types for an already-uploaded file URI.

Create a signed URL for direct browser upload to GCS.

Delete a completed/failed/cancelled job from history.

Query records directly from the staging table for an integration recordset.

This endpoint is for VIRTUAL integration recordsets that store data in staging tables
(like shopify_products, meta_ads, etc.) rather than duplicating into the records table.

For Fivetran: If the recordset doesn't exist, it will be auto-created on-the-fly.

Get the total count of records in the staging table.

Get a single record from the staging table.

List contacts with filtering and pagination.

Sort options:
• updated_at: Most recently updated
• created_at: Most recently created
• full_name: Alphabetical
• relationship_score: Highest relationship score first
• last_interaction_at: Most recent interaction
• days_since_contact: Longest time since contact (needs attention)

Get a contact with all related data (interactions, tasks, insights, property links)

List all interactions for a contact

Get CRM dashboard summary.

Returns key metrics and action items for the current user.

List AI-generated insights.

These are actionable intelligence items the AI has identified:
• Follow-up needed
• Relationship health alerts
• Opportunities
• Risks

List contact discovery proposals.

Pending proposals are contacts discovered by AI awaiting review.

Get a specific discovery proposal

List entity relationships with filtering.

Use this to find all relationships for a specific entity,
or filter by relationship type.

Get all relationships for a specific entity.

Direction:
• source: Entity is the source (outgoing relationships)
• target: Entity is the target (incoming relationships)
• both: All relationships involving the entity

List tasks across all contacts.

Great for seeing your daily/weekly follow-up queue.

Get comprehensive AI analysis of a contact.

Returns:
• Relationship health assessment
• Communication pattern analysis
• Sentiment trends
• Recommended next actions
• Opportunities and risks

Trigger AI to discover contacts related to an entity.

The AI will search various sources and create discovery proposals
for contacts it finds related to the specified entity.

Have AI draft a personalized message for a contact.

The AI considers:
• Contact's communication style
• Recent interaction history
• Relationship context
• Purpose of outreach

Generate AI-prioritized follow-up suggestions.

The AI reviews all contacts (or specified ones) and returns
prioritized suggestions for who needs attention.

Create a new contact.

The AI will automatically:
• Analyze the contact type and suggest optimal engagement strategy
• Set initial relationship score
• Schedule initial follow-up task

Mark an insight as actioned