API Documentation

Complete reference for the Weaver API endpoints

🔑

Authentication Required

All API endpoints require a Customer-Key header for authentication. You can obtain your Customer Key from the dashboard after connecting your workspace.

📡

Base URL

https://weaver.somee.ai/api
🤖

AI Prompt Responses

Many endpoints return a prompt field that provides AI-friendly guidance on how to interpret and communicate the response to end users. These prompts are designed to help AI assistants handle sensitive information appropriately and provide helpful context.

GoHighLevel (GHL) Integration

▶ GET /api/GHL/freeSlots

Retrieve available time slots for a calendar

Query Parameters:

calendarId (required) - The GHL calendar ID
timezone (optional, default: UTC) - Timezone for the slots
more (optional, default: false) - Fetch additional slot details

Success Response (200):

{
  "status": true,
  "slots_available": ["2026-01-21T10:00:00Z", "2026-01-21T11:00:00Z"],
  "error": null
}
▶ GET /api/GHL/contactExists

Check if a contact exists in GHL

Query Parameters (at least one required):

email - Contact email address
phone or user_phone_number - Contact phone number

Success Response (200):

{
  "contact_exists": true,
  "contactId": "12345",
  "contact": { /* contact object */ }
}
▶ POST /api/GHL/createContact

Create a new contact in GHL

Request Body:

{
  "name": "John Doe",
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+1 888-888-8888",
  "tags": ["tag1", "tag2"]
}

Success Response (200):

{
  "contactId": "12345",
  "contact": { /* full contact object */ },
  "status": true,
  "error": null
}
▶ POST /api/GHL/createAppointment

Create a new appointment

Request Body:

{
  "calendarId": "78910",
  "contactId": "654321",
  "startTime": "2023-07-19T10:00:00Z"
}

Shopify Integration

▶ POST /api/shopify/fetch-products

Fetch products from Shopify store

Query Parameters:

customer_id (required)
store_id (required)
call_id (required)

Success Response (200):

{
  "fetchProducts": {
    "edges": [
      {
        "node": {
          "id": "gid://shopify/Product/123456789",
          "title": "Sample Product"
        }
      }
    ]
  },
  "prompt": "Products fetched successfully. Do not disclose internal details..."
}

AI Prompt Field:

The prompt field provides AI guidance on how to present data to users.

▶ POST /api/shopify/search-customer

Basic search for a customer (for passphrase verification)

⚠️ Verification Not Required

This endpoint does NOT require call verification. Designed for retrieving passphrases.

Query Parameters:

query_type (required) - "email" or "phone"
query (required) - Email or phone to search

Success Response (200):

{
  "searchCustomer": {
    "customer": {
      "id": "gid://shopify/Customer/123",
      "email": "[email protected]",
      "note": "passphrase: secret-word-here"
    }
  }
}
▶ POST /api/shopify/search-full-customer

Search for full customer details (requires verification)

🔒 Verification Required

This endpoint REQUIRES call verification before returning full customer data.

Success Response (200):

{
  "searchFullCustomer": {
    "customer": {
      "id": "gid://shopify/Customer/123",
      "email": "[email protected]",
      "firstName": "John",
      "addresses": [/* address data */],
      "orders": [/* order history */]
    }
  }
}

Cal.com Integration

▶ POST /api/calcom/createBooking

Create a new booking in Cal.com

Request Body:

{
  "customer_id": 23,
  "cal_id": 142,
  "start_date": "2024-08-13",
  "start_time": "09:00",
  "eventTypeId": 123,
  "attendee": {
    "name": "John Doe",
    "email": "[email protected]",
    "timeZone": "America/New_York"
  }
}

Success Response (201):

{
  "createBooking": {
    "id": 12345,
    "uid": "booking_uid_abc123",
    "startTime": "2024-08-13T09:00:00Z"
  }
}
▶ POST /api/calcom/getFreeSlots

Get available time slots

Request Body:

{
  "customer_id": 23,
  "cal_id": 142,
  "start": "2024-08-13",
  "end": "2024-08-15",
  "timeZone": "America/Denver",
  "eventId": 118322
}

Note: Date range max 14 days

Authentication Verification

ℹ️

Verification Flow

  1. Create verification session when call starts
  2. Use search-customer to retrieve passphrase
  3. Verify caller's identity with passphrase
  4. Set verification status to true
  5. Access protected endpoints
▶ POST /api/auth/createVerificationSession

Initialize verification session

Request Body:

{
  "customer_id": 23,
  "call_id": "14312341612341123611232"
}

Success Response (201):

{
  "session": {
    "call_id": "14312341612341123611232",
    "verified": false,
    "expires_at": "2026-01-21T12:00:00Z"
  }
}
▶ POST /api/auth/setStatus

Set verification status

Request Body:

{
  "customer_id": 23,
  "call_id": "14312341612341123611232",
  "status": true
}
▶ POST /api/auth/checkStatus

Check verification status

Request Body:

{
  "customer_id": 23,
  "call_id": "14312341612341123611232"
}

Error Responses

Many endpoints include AI-friendly error prompts:

{
  "status": false,
  "prompt": "You will not be able to help the caller today. Advise them to email support..."
}
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid Customer-Key
403 Forbidden - Verification required
404 Not Found - Credentials not found
💬

Need Help?

If you need assistance with the API or have questions about integration, our support team is here to help.

Contact Support