How can we help?

Zapier API Documentation

PocketSuite Zapier API Documentation

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

Endpoint URL
Authorization URL https://api.pocketsuite.io/gateway/oauth/authorize
Token URL https://api.pocketsuite.io/gateway/oauth/token
Token Refresh URL https://api.pocketsuite.io/gateway/oauth/token

OAuth Scopes

The integration requires the following 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

Once authorized, all API requests include the OAuth access token in the Authorization header: 

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

Resource Endpoint Path
Clients /clients
Bookings /booking
Payments /payment
Subaccounts /subaccounts
Client Notes /client/notes
Webhooks /webhooks

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.

4.1 Client Created

  • Event: Triggered when a new client is created in PocketSuite
  • Webhook URL: Generated by Zapier
  • Method: POST

Webhook Payload Example

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "created_date": "2025-01-15T14:30:00Z"
  }
}

4.2 Client Updated

  • Event: Triggered when an existing client's information is modified
  • Webhook URL: Generated by Zapier
  • Method: POST

Webhook Payload Example

{
  "id": "client_abc123",
  "owner": {
    "id": "owner_xyz789",
    "name": "John Smith"
  },
  "lead_source": {
    "id": "referer_def456",
    "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:00Z",
  "last_modified_date": "2025-01-02T10:30:00Z",
  "first_payment_date": "2025-01-05T14:20:00Z",
  "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
  • Webhook URL: Generated by Zapier
  • Method: POST

Webhook Payload Example

{
  "event": "booking.created",
  "timestamp": "2025-01-15T16:00:00Z",
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "type": "service",
    "client": { "id": "...", "name": "John Doe" },
    "date": "2025-01-20T10:00:00Z",
    "total": 150.00
  }
}

4.4 Booking Completed

  • Event: Triggered when a booking is marked as completed
  • Webhook URL: Generated by Zapier
  • Method: POST

Webhook Payload Example

{
  "event": "booking.completed",
  "timestamp": "2025-01-20T11:00:00Z",
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "completed_date": "2025-01-20T11:00:00Z"
  }
}

4.5 Payment Received

  • Event: Triggered when a payment is received and processed
  • Webhook URL: Generated by Zapier
  • Method: POST

Webhook Payload Example

{
  "event": "payment.received",
  "timestamp": "2025-01-20T11:05:00Z",
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "amount": 150.00,
    "client": { "id": "...", "name": "John Doe" },
    "created_date": "2025-01-20T11:05:00Z"
  }
}

4.6 Subaccount Created

  • Event: Triggered when a new subaccount is created
  • Webhook URL: Generated by Zapier
  • Method: POST

4.7 Subaccount Updated

  • Event: Triggered when a subaccount is modified
  • Webhook URL: Generated by Zapier
  • Method: POST

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 in PocketSuite

Required Fields

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

Optional Fields

line1, line2, city, state, postal_code, country_code, birthday, utm_source, utm_medium, utm_campaign, utm_content, utm_term, google_click_id, facebook_click_id, tiktok_click_id, and all custom fields

Request Example

POST /gateway/v1/zapier/clients HTTP/1.1
Host: api.pocketsuite.io
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "name": "Jane Smith",
  "email": "jane@example.com",
  "phone": "+1234567890",
  "line1": "123 Main St",
  "city": "New York",
  "state": "NY",
  "postal_code": "10001"
}

Success Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "phone": "+1234567890",
  "created_date": "2025-01-15T14:30:00Z"
}

5.2 Update Client

  • Method: PUT
  • Endpoint: https://api.pocketsuite.io/gateway/v1/zapier/clients
  • Description: Updates an existing client's information

Updatable Fields

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

Request Example

PUT /gateway/v1/zapier/clients HTTP/1.1
Host: api.pocketsuite.io
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "phone": "+1987654321",
  "city": "Los Angeles",
  "state": "CA"
}

Success Response (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Jane Smith",
  "phone": "+1987654321",
  "city": "Los Angeles",
  "state": "CA",
  "last_modified_date": "2025-01-15T15:45:00Z"
}

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

Request Example

POST /gateway/v1/zapier/client/notes HTTP/1.1
Host: api.pocketsuite.io
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "note": "Client prefers morning appointments"
}

Success Response (201 Created)

{
  "id": "880e8400-e29b-41d4-a716-446655440003",
  "client_id": "550e8400-e29b-41d4-a716-446655440000",
  "note": "Client prefers morning appointments",
  "created_date": "2025-01-15T16:00:00Z"
}

6. Error Handling

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

HTTP Status Codes

Status Code Description
200 OK Request successful
201 Created Resource successfully created
400 Bad Request Invalid request parameters or missing required fields
401 Unauthorized Missing or invalid OAuth access token
404 Not Found Resource not found
422 Unprocessable Entity Request validation failed
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error, please contact PocketSuite Customer Support

Error Response Format

{
  "error": {
    "code": "validation_error",
    "message": "Missing required field: name",
    "field": "name"
  }
}

7. Rate Limiting

Rate Limits

  • OAuth: On /oauth/token, 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. For complete field descriptions, data types, and constraints, please refer to the original PocketSuite Fields Documentation.

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
Have more questions? Submit a request

Related articles

Powered by Zendesk