Internal reference — not the public API

This documents NearSync's internal action-dispatch surface, used by the apps themselves and by tenant automations. It is not the public API and carries no stability guarantee — actions may change or be removed without notice. For the supported, versioned public API see API Reference.

CRM Endpoints

Endpoints for managing deals, contacts, organizations, and CRM integrations. Includes AI-powered enrichment and two-way sync with external CRM platforms.

All endpoints use POST to the hyper-worker base URL with the type field specifying the action.

POST https://<project>.supabase.co/functions/v1/hyper-worker

---

prd (Create Deal)

Public - No authentication required.

Create a new deal (project request) with an optional AI-generated PRD (Product Requirements Document). Used by public-facing forms and the marketing website.

Rate limit: 5 requests per 60 seconds

Request

{
  "type": "prd",
  "clientName": "Jane Doe",
  "clientEmail": "client@example.com",
  "businessName": "Acme Corp",
  "industry": "retail",
  "userId": "<user-uuid>",
  "phone": "+1234567890",
  "rawData": {
    "problem": "Manual inventory tracking is time-consuming",
    "users": "Store managers and staff",
    "features": ["Real-time inventory", "Mobile app", "Reports"]
  },
  "generatedPrd": "# Product Requirements Document\n\n## Overview\n..."
}

Field	Type	Required	Description
clientName	string	Yes	Contact's full name
clientEmail	string	Yes	Contact's email address
businessName	string	Yes	Company name
industry	string	No	Industry vertical
userId	string	No	Submitting user's ID
phone	string	No	Contact phone number (E.164 format)
rawData	object	No	Structured requirements for AI PRD generation
generatedPrd	string	No	Pre-generated PRD text. If omitted and rawData is provided, a PRD is generated via AI

Process

1. If generatedPrd is not provided, generates one via Google Gemini using the rawData context
2. Deduplicates by phone number - returns the existing deal if a match is found
3. Creates a contact record
4. Creates a deal in the default pipeline with round-robin admin assignment
5. Sends an admin alert email

Response

{
  "success": true,
  "project": {
    "id": "<uuid>",
    "name": "Acme Corp - Inventory Management",
    "status": "new_lead",
    "assigned_to": "<uuid>"
  }
}

---

enrich-project

Authenticated - Requires JWT.

AI-enrich a deal with company data (industry, employee count, website, address, logo, summary). Uses Google Gemini to research the company based on its name.

Request

{
  "type": "enrich-project",
  "projectId": "<uuid>"
}

Field	Type	Required	Description
projectId	string	Yes	Deal ID to enrich

Response

{
  "success": true,
  "enriched": {
    "industry": "Retail",
    "employees": "50-100",
    "website": "https://acmecorp.com",
    "address": "Dubai, UAE",
    "logo": "https://...",
    "summary": "Leading retail solutions provider"
  }
}

---

enrich-organization

Authenticated - Requires JWT.

AI-enrich a CRM company record. Similar to enrich-project but targets the crm_companies table directly.

Request

{
  "type": "enrich-organization",
  "organizationId": "<uuid>"
}

Field	Type	Required	Description
organizationId	string	Yes	Company record ID to enrich

Response

{
  "success": true,
  "enriched": {
    "industry": "Retail",
    "description": "...",
    "founded": "2010",
    "employees": "50-100"
  }
}

---

CRM Sync

Endpoints for connecting and syncing data with external CRM platforms. Supported providers: HubSpot, Salesforce, Zoho, Pipedrive.

crm-init-oauth

Authenticated - Requires JWT.

Initiate an OAuth flow to connect an external CRM.

{
  "type": "crm-init-oauth",
  "provider": "hubspot",
  "orgId": "<org-uuid>",
  "userId": "<user-uuid>"
}

Field	Type	Required	Description
provider	string	Yes	One of: hubspot, salesforce, zoho, pipedrive
orgId	string	Yes	Organization ID
userId	string	Yes	User initiating the connection

Response:

{
  "authorizeUrl": "https://app.hubapi.com/oauth/authorize?client_id=...&redirect_uri=...&state=...",
  "state": "<pkce-state-string>"
}

Redirect the user to authorizeUrl to complete the OAuth flow. After authorization, the callback stores tokens and redirects back to your application.

---

crm-save-api-key

Authenticated - Requires JWT.

Save an API key for CRM providers that support key-based authentication. The key is validated with a test API call before being stored.

{
  "type": "crm-save-api-key",
  "provider": "hubspot",
  "orgId": "<org-uuid>",
  "userId": "<user-uuid>",
  "apiKey": "<api-key-string>",
  "instanceDomain": "domain.freshsales.io"
}

Field	Type	Required	Description
provider	string	Yes	CRM provider name
orgId	string	Yes	Organization ID
userId	string	Yes	User saving the key
apiKey	string	Yes	Provider API key
instanceDomain	string	No	Instance domain (for providers like Freshsales)

Response:

{
  "success": true
}

---

crm-connections

Authenticated - Requires JWT.

List all CRM connections for an organization.

{
  "type": "crm-connections",
  "orgId": "<org-uuid>"
}

Response:

{
  "connections": [
    {
      "id": "<uuid>",
      "provider": "hubspot",
      "status": "connected",
      "last_sync": "2026-03-21T10:00:00Z",
      "connected_at": "2026-03-15T10:00:00Z"
    }
  ]
}

---

crm-disconnect

Authenticated - Requires JWT.

Disconnect an external CRM integration. Revokes the OAuth token with the provider (if applicable) and clears stored credentials.

{
  "type": "crm-disconnect",
  "connectionId": "<uuid>",
  "orgId": "<org-uuid>"
}

Response:

{
  "success": true
}

---

crm-start-sync

Authenticated - Requires JWT.

Start a data sync from the connected CRM. This is an asynchronous operation - the endpoint returns a job ID immediately and sync runs in the background.

{
  "type": "crm-start-sync",
  "connectionId": "<uuid>",
  "orgId": "<org-uuid>",
  "userId": "<user-uuid>",
  "entities": ["contacts", "deals", "companies"]
}

Field	Type	Required	Description
connectionId	string	Yes	Integration connection ID
orgId	string	Yes	Organization ID
userId	string	Yes	User triggering the sync
entities	string[]	Yes	Entity types to sync: contacts, deals, companies

Response:

{
  "jobId": "<uuid>",
  "status": "in_progress",
  "progress": {
    "contacts": {
      "status": "syncing",
      "total": 150,
      "imported": 45,
      "failed": 0
    },
    "deals": {
      "status": "queued",
      "total": 0,
      "imported": 0,
      "failed": 0
    }
  }
}

---

crm-sync-status

Authenticated - Requires JWT.

Poll the status of a running sync job.

{
  "type": "crm-sync-status",
  "jobId": "<uuid>",
  "orgId": "<org-uuid>"
}

Response:

{
  "jobId": "<uuid>",
  "status": "completed",
  "started_at": "2026-03-21T10:00:00Z",
  "completed_at": "2026-03-21T10:15:00Z",
  "progress": {
    "contacts": {
      "status": "completed",
      "total": 150,
      "imported": 148,
      "failed": 2
    }
  },
  "error_log": []
}

The status field transitions through: queued -> in_progress -> completed (or failed).

---

crm-sync-history

Authenticated - Requires JWT.

Get the sync history for an organization, ordered by most recent first.

{
  "type": "crm-sync-history",
  "orgId": "<org-uuid>",
  "limit": 10
}

Field	Type	Required	Description
orgId	string	Yes	Organization ID
limit	number	No	Max records to return (default: 10)

Response:

{
  "jobs": [
    {
      "jobId": "<uuid>",
      "provider": "hubspot",
      "status": "completed",
      "started_at": "2026-03-21T10:00:00Z",
      "completed_at": "2026-03-21T10:15:00Z",
      "entities": ["contacts", "deals"],
      "summary": "Synced 148 contacts, 32 deals"
    }
  ]
}

---

Related

• AI Endpoints - AI enrichment uses the same Gemini provider as ai-chat
• Webhooks - Incoming WhatsApp messages auto-create leads in the default pipeline