HeavySet Zapier API Documentation

Getting Your API Token

Before you can use the HeavySet Zapier API, you need to generate an API token from your HeavySet admin panel.

Steps to generate your API token:

1. Log in to your HeavySet admin panel
2. Navigate to: https://admin.heavyset.tech/settings/appointment-page/page/access-tokens
3. Click the "Generate Access Token" button
4. Important: Copy and save the token immediately - it will only be displayed once
5. If you lose your token, you'll need to generate a new one by repeating these steps

Security Note: Keep your API token secure and never share it publicly. If you believe your token has been compromised, generate a new one immediately.

Add HeavySet Tech Integration to Zapier

We are still in beta but you can use our Zap actions by adding HeavySet Tech to your Zapier account with this link.

Not signed up to HeavySet Tech yet, contact us for a demo here.

Authentication

All API endpoints require authentication using the x-heavyset-token header. This token must be a valid HeavySet API token that has been properly encrypted and signed.

Header Format:

x-heavyset-token: your_encrypted_api_token_here

Base URL

https://api.heavyset.tech/api/v1/zaps

Endpoints

1. Authentication Test (GET /auth-test)
   Validates your API token and returns basic page details.

2. Submit Lead (POST /lead)
   Creates a new lead and returns a one-time token for appointment booking.

3. Get Time Slots (GET /slots)
   Retrieves available appointment slots using a one-time token.

4. Book Appointment (POST /appointment)
   Confirms an appointment using a one-time token and selected slot information.

1. Authentication Test

Purpose: Validates the API token and returns basic page information. Used by Zapier to test authentication during setup.

Endpoint: GET /auth-test

Headers:

• x-heavyset-token (required): Your HeavySet API token

Response:

Success (200):

{
  "ok": true,
  "pageId": "page_123",
  "label": "Your Page Name"
}

Error responses:

• 400 Bad Request: Missing token
• 401 Unauthorized: Invalid token
• 403 Forbidden: Demo mode (not allowed)

cURL Example:

curl -X GET "https://api.heavyset.tech/api/v1/zaps/auth-test" \
  -H "x-heavyset-token: your_encrypted_api_token_here" \
  -H "Content-Type: application/json"

---

2. Submit Lead

Purpose: Creates a new lead in the system and returns a one-time token for appointment booking.

Endpoint: POST /lead

Headers:

• x-heavyset-token (required): Your HeavySet API token
• x-idempotency-key (optional): Custom idempotency key to prevent duplicate submissions

Request Body:

{
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "[phone]",
  "address1": "123 Main St",
  "zip": "12345",
  "email": "[e-mail]",
  "comments": "Interested in your services",
  "source": "zapier",
  "sourceType": "web_form",
  "sourceName": "Contact Form",
  "product": "Premium Service"
}

Field Descriptions:

• name (optional): Full name (if not provided, will be constructed from firstName + lastName)
• firstName (optional): First name
• lastName (optional): Last name
• phone (required): Phone number
• address1 (optional): Street address
• zip (required): ZIP/postal code
• email (optional): Email address
• comments (optional): Additional comments or notes
• source (optional): Lead source identifier
• sourceType (optional): Type of source (e.g., "web_form", "social_media")
• sourceName (optional): Human-readable source name
• product (optional): Product or service of interest
• forceNewLead(optional): If true, force creation of a new lead, even if it already exists. This works best with i360 which creates eLeads & lead sources without duplicating accounts or prospects.
• deferCrmSaveUntilAppointment (optional): Boolean, defers lead creation until an appointment is created. (e.g. true, false)
• gtrLeadId(optional): String, an ID from Get The Referral saved to the CRM for future tracking for Get The Referral.

Response:

Success (200):

{
  "ok": true,
  "oneTimeToken": "otp_abc123xyz",
  "leadId": "lead_456"
}

Error responses:

• 400 Bad Request: Missing token or validation errors
• 401 Unauthorized: Invalid token
• 403 Forbidden: Demo mode

cURL Example:

curl -X POST "https://api.heavyset.tech/api/v1/zaps/lead" \
  -H "x-heavyset-token: your_encrypted_api_token_here" \
  -H "Content-Type: application/json" \
  -H "x-idempotency-key: unique_key_123" \
  -d '{
    "name": "John Doe",
    "phone": "[phone]",
    "zip": "12345",
    "email": "[e-mail]",
    "source": "zapier",
    "comments": "Interested in your services"
  }'

---

3. Get Time Slots

Purpose: Retrieves available appointment time slots for a given one-time token.

Endpoint: GET /slots

Headers:

• x-heavyset-token (required): Your HeavySet API token

Query Parameters:

• oneTimeToken (required): One-time token obtained from a lead submission

Response:

Success (200):

{
  "ok": true,
  "oneTimeToken": "otp_abc123xyz",
  "timeZone": "America/New_York",
  "slots": [
    {
      "appointmentDate": "2025-08-10",
      "startTime": "10:00 AM",
      "endTime": "11:30 AM",
      "availableSlots": 6,
      "blockId": "a0p8X00000XRDoJQAX",
      "timeZone": "America/New_York"
    },
    {
      "appointmentDate": "2025-08-10",
      "startTime": "2:00 PM",
      "endTime": "3:30 PM",
      "availableSlots": 3,
      "blockId": "a0p8X00000XRDoKQAX",
      "timeZone": "America/New_York"
    }
  ]
}

Response Field Descriptions:

• ok: Boolean indicating success
• oneTimeToken: The one-time token that was used for the request
• timeZone: Overall timezone for the slots (may be undefined)
• slots: Array of available time slots
  • appointmentDate: Date in YYYY-MM-DD format
  • startTime: Start time in "HH:MM AM/PM" format
  • endTime: End time in "HH:MM AM/PM" format
  • availableSlots: Number of available appointments in this slot
  • blockId: Unique identifier for this time block
  • timeZone: Timezone for this specific slot

Error responses:

• 400 Bad Request: Missing token or one-time token
• 401 Unauthorized: Invalid token
• 403 Forbidden: Demo mode

cURL Example:

curl -X GET "https://api.heavyset.tech/api/v1/zaps/slots?oneTimeToken=otp_abc123" \
  -H "x-heavyset-token: your_encrypted_api_token_here" \
  -H "Content-Type: application/json"

---

4. Book Appointment

Purpose: Books an appointment using a one-time token. The blockId field now accepts either a block identifier (from /slots) or an ISO 8601 datetime string. If a datetime is passed, the server will automatically select the best matching slot within tolerance.

Endpoint: POST /appointment

Headers:

• x-heavyset-token (required): Your HeavySet API token
• x-idempotency-key (optional): Custom idempotency key to prevent duplicate bookings

Request Body:

{
  "blockId": "block_123",
  "oneTimeToken": "otp_abc123xyz",
  "source": "zapier",
  "sourceType": "automation",
  "sourceName": "Zapier Integration",
  "sliceStartTime": "10:00 AM"
}

Field Descriptions:

• blockId (required): Time slot block identifier from the slots endpoint
• oneTimeToken (required): One-time token from lead submission

  • If a block ID (e.g., "a0p8X00000XRDoJQAX"), the appointment is booked directly.

  • If an ISO 8601 datetime string (e.g., "2025-08-10T10:15:00-06:00"), the server finds the closest available slot (default tolerance ±60 minutes) and books it.

• timeZone  (optional): Required only if the blockId datetime has no offset.

• source (optional): Appointment source identifier
• sourceType (optional): Type of source
• sourceName (optional): Human-readable source name
• sliceStartTime (optional): Start time in "HH:MM AM/PM" format

Response:

Success (200):

{
  "ok": true,
  "appointmentId": "appt_789",
  "status": "confirmed"
}

Error responses:

• 400 Bad Request: Missing token, invalid one-time token, or validation errors
• 401 Unauthorized: Invalid API token
• 403 Forbidden: Demo mode

cURL Example:

curl -X POST "https://api.heavyset.tech/api/v1/zaps/appointment" \
  -H "x-heavyset-token: your_encrypted_api_token_here" \
  -H "Content-Type: application/json" \
  -H "x-idempotency-key: appt_unique_key_456" \
  -d '{
    "blockId": "block_123",
    "oneTimeToken": "otp_abc123xyz",
    "source": "zapier",
    "sliceStartTime": "10:00 AM"
  }'

Error Handling

All endpoints return consistent error responses:

400 Bad Request:

{
  "ok": false,
  "error": "missing_token" | "missing_one_time_token" | "validation_error"
}

401 Unauthorized: Returns HTTP 401 status without body for invalid tokens.

403 Forbidden: Returns HTTP 403 status without body when account is in demo mode.

Idempotency

The API supports idempotency through the x-idempotency-key header. If not provided, the system will generate a key based on the request payload to prevent duplicate submissions.

For lead submissions, the default key format is: {name}|{phone}|{zip} For appointment bookings, the default key format is: {blockId}|{sliceStartTime}

Rate Limiting

Standard rate limiting applies to all endpoints. Ensure your Zapier integration handles rate limit responses appropriately by implementing retry logic with exponential backoff.

Typical Workflow

1. Test Authentication - Use /auth-test to validate your API token
2. Submit Lead - Use /lead to create a lead and receive a one-time token
3. Get Available Slots - Use /slots with the one-time token to retrieve available appointment times
4. Book Appointment - Use /appointment to book a specific time slot

Support

For technical support or questions about this API, please contact the HeavySet development team.