PocketSuite API Documentation for Zapier Integration

1. Overview

This documentation outlines the PocketSuite API endpoints used to power our Zapier integration. These endpoints allow PocketSuite to securely connect with Zapier and automate workflows between PocketSuite and thousands of other apps. Use this guide to understand what data is available, how it's structured, and how it flows through automated integrations.

Integration Capabilities

• Triggers: Receive real-time notifications when events occur in PocketSuite
• Actions: Perform operations in PocketSuite from other applications

2. Authentication

PocketSuite uses OAuth 2.0 for secure authentication through Zapier. Users authorize the Zapier integration via OAuth, and Zapier manages token refresh automatically.

Authentication Method

• Protocol: OAuth 2.0
• Flow: Authorization Code Grant
• Token Type: Bearer

OAuth Endpoints

OAuth Scopes

• read:bookings – Read booking data
• read:payments – Read payment data
• read:clients – Read client data
• write:clients – Create and update clients
• read:subaccounts – Read subaccount data

Authenticated Request Format

Authorization: Bearer {access_token}
Content-Type: application/json

3. Base URL and Endpoint Structure

Base URL

https://api.pocketsuite.io/gateway/v1/zapier

Endpoint Paths

4. Triggers (Webhooks)

Triggers send real-time notifications to Zapier when specific events occur in PocketSuite. These are implemented as webhooks that POST data to Zapier's webhook URL.

Payload format: Every trigger sends the record itself as the full request body. There is no event, timestamp, or data wrapper on any trigger.

About IDs: On Client Created and Client Updated, the top-level id is the client record ID. On Booking, Payment, and Subaccount events, client.id is the person ID — the same ID that appears in the client's profile URL in PocketSuite. These two IDs never match. To connect a Client Created record to later events, match on the client's email or phone.

4.1 Client Created

• Event: Triggered when a new client is created in PocketSuite
• Method: POST

Does not fire for clients created by the Zapier “Create Client” action. Sends exactly the same fields as 4.2 Client Updated (see that example).

4.2 Client Updated

• Event: Triggered when an existing client's information is modified
• Method: POST

Webhook Payload Example

{
  "id": "550e8400-e29b-41d4-a716-446655440009",
  "owner": { "id": "550e8400-e29b-41d4-a716-446655440001", "name": "Jane Smith" },
  "lead_source": { "id": "550e8400-e29b-41d4-a716-446655440015", "name": "Sarah Johnson" },
  "name": "Jane Doe",
  "phone": "+14155551234",
  "email": "jane.doe@example.com",
  "line1": "123 Main Street",
  "line2": "Apt 4B",
  "city": "San Francisco",
  "state": "CA",
  "postal_code": "94102",
  "country_code": "US",
  "created_date": "2025-01-02T10:30:00+00:00",
  "last_modified_date": "2025-01-02T10:30:00+00:00",
  "first_payment_date": "2025-01-05T14:20:00+00:00",
  "birthday": "1990-05-15",
  "source": "online_booking",
  "utm_source": "google",
  "utm_medium": "cpc",
  "utm_campaign": "spring_promo",
  "utm_content": "ad_variant_a",
  "utm_term": "personal_trainer",
  "google_click_id": "gclid_example123",
  "facebook_click_id": "fbclid_example456",
  "tiktok_click_id": "ttclid_example789",
  "custom_field_name_1": "custom_value_1",
  "custom_field_name_2": "custom_value_2"
}

4.3 Booking Created

• Event: Triggered when a new booking is created
• Method: POST

Webhook Payload Example

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "type": "service",
  "date": "2025-01-20T10:00:00+00:00",
  "end_date": "2025-01-20T11:00:00+00:00",
  "confirmed_date": "2025-01-15T16:00:00+00:00",
  "completed_date": null,
  "paid_date": null,
  "cancelled_date": null,
  "memo": "First session",
  "owner": { "id": "550e8400-e29b-41d4-a716-446655440001", "name": "Jane Smith" },
  "client": { "id": "550e8400-e29b-41d4-a716-446655440009", "name": "John Doe", "phone": "+14155550000", "email": "john@example.com" },
  "item": { "id": "770e8400-e29b-41d4-a716-446655440020", "name": "60-min Session", "type": "service", "price": 150.00 },
  "lines": [
    { "id": "880e8400-e29b-41d4-a716-446655440021", "quantity": 1, "item": { "id": "770e8400-e29b-41d4-a716-446655440020", "name": "60-min Session", "type": "service", "price": 150.00 } }
  ],
  "subaccount": { "id": "550e8400-e29b-41d4-a716-446655440030", "name": "Max" },
  "rate": 150.00,
  "deposit": 0.00,
  "amount": 150.00,
  "discount_amount": 0.00,
  "tax_amount": 0.00,
  "gratuity_amount": 0.00,
  "total": 150.00,
  "line1": "123 Main Street",
  "line2": "Apt 4B",
  "city": "San Francisco",
  "state": "CA",
  "postal_code": "94102",
  "country_code": "US"
}

Any custom fields configured for bookings are also included, keyed by field name.

4.4 Booking Completed

• Event: Triggered when a booking is marked as completed
• Method: POST

Sends the same full booking payload as 4.3 Booking Created, with completed_date set. A booking that is completed and later marked paid fires Booking Completed again, with a new completed_date and paid_date set.

4.5 Payment Received

• Event: Triggered when a payment is received and processed
• Method: POST

Fires for card, bank (ACH), Apple Pay, card reader / tap to pay, and pay-later payments. Cash or check marked as paid does not fire Payment Received; on a booking, marking it paid fires 4.4 Booking Completed instead (with paid_date set).

Webhook Payload Example

{
  "id": "990e8400-e29b-41d4-a716-446655440002",
  "owner": { "id": "550e8400-e29b-41d4-a716-446655440001", "name": "Jane Smith" },
  "client": { "id": "550e8400-e29b-41d4-a716-446655440009", "name": "John Doe", "phone": "+14155550000", "email": "john@example.com" },
  "amount": 150.00,
  "total": 150.00,
  "memo": "60-min Session",
  "refnum": "A1B2C3D4",
  "created_date": "2025-01-20T11:05:00+00:00"
}

4.6 Subaccount Created

• Event: Triggered when a new subaccount is created
• Method: POST

Webhook Payload Example

{
  "id": "550e8400-e29b-41d4-a716-446655440030",
  "name": "Max",
  "birthday": "2015-08-20",
  "owner": { "id": "550e8400-e29b-41d4-a716-446655440001", "name": "Jane Smith" },
  "client": { "id": "550e8400-e29b-41d4-a716-446655440009", "name": "John Doe" },
  "line1": "456 Oak Avenue",
  "line2": "Suite 200",
  "city": "Austin",
  "state": "TX",
  "postal_code": "78702",
  "country_code": "US",
  "created_date": "2024-01-15T12:00:00+00:00",
  "last_modified_date": "2024-01-20T15:30:00+00:00"
}

Any custom fields configured for subaccounts are also included, keyed by field name. The parent client is client.id (the person ID).

4.7 Subaccount Updated

• Event: Triggered when a subaccount is modified
• Method: POST

Sends the same payload as 4.6 Subaccount Created, with last_modified_date updated.

5. Actions (API Endpoints)

Actions allow Zapier to perform operations in PocketSuite by making authenticated API requests.

5.1 Create Client

• Method: POST
• Endpoint: https://api.pocketsuite.io/gateway/v1/zapier/clients
• Description: Creates a new client. The client is matched first by phone, then by email; a new client is created only if nothing matches.

Required Fields

• name (string, required)
• phone OR email (at least one required)

Optional Fields

line1, line2, city, state, postal_code, country_code, birthday, UTM fields, click IDs, and all custom fields

Returns the full client record (same shape as 4.2 Client Updated).

5.2 Update Client

• Method: POST
• Endpoint: https://api.pocketsuite.io/gateway/v1/zapier/clients
• Description: Updates an existing client. Matched first by phone, then by email; created if nothing matches.

Updatable Fields

name, phone, email, line1, line2, city, state, postal_code, country_code, birthday, UTM fields, click IDs, and all custom fields

Returns the full client record (same shape as 4.2 Client Updated).

5.3 Add Client Note

• Method: POST
• Endpoint: https://api.pocketsuite.io/gateway/v1/zapier/client/notes
• Description: Adds a note to a client's record.

Required Fields

• note (string, required) – the note content
• The client's email or phone (to identify the client)

Optional Fields

• title (string, optional)

6. Error Handling

The API uses standard HTTP status codes and returns error messages in JSON format.

HTTP Status Codes

Error Response Format

{
  "error": "invalid_request",
  "error_description": "Missing required field: name"
}

7. Rate Limiting

Rate Limits

• OAuth: On /oauth/token, a rate limit of 10 invalid requests per IP address per hour. Requests with an expired access token are not considered invalid requests.

Handling Rate Limits

When rate limits are exceeded, retry after the limit period has lapsed or reach out to PocketSuite Customer Support.

8. Complete Field Reference

This section provides detailed information about all available fields for each resource type.

Available Resources

• Bookings: Complete booking details including client, dates, amounts, and line items
• Payments: Payment transaction details and client information
• Clients: Client profiles with contact info, address, UTM tracking, and custom fields
• Subaccounts: Subaccount information and details
• Custom Fields: Configurable custom fields for extended data capture

9. Support and Resources

Getting Help

• Zapier Integration Support: Contact PocketSuite support through your account
• Technical Documentation: Refer to complete field documentation
• Zapier Help: Visit help.zapier.com for Zapier-specific guidance