Zapier Integration API Documentation

Overview

This documentation describes the API for integrating with Zapier. The integration allows you to send lead information collected from your chats to Zapier, which can then be used to trigger actions in other platforms.

Authentication

All API requests require authentication using a chat ID and an API key.

• chat_id: The unique identifier for your chat

• api_key: A unique API key generated for the Zapier integration

Authentication parameters should be included in all API requests as query parameters.

Example:

https://your-api-domain.com/api/integrations/zapier/test_connection?chat_id=123&api_key=zc-a1b2c3d4e5f6...

Endpoints

Test Connection

Used to verify that the authentication credentials are valid.

• URL: /api/integrations/zapier/test_connection

• Method: GET

• Authentication Required: Yes

• Query Parameters:

  • chat_id: Your chat ID

  • api_key: Your Zapier integration API key

Successful Response

{
  "message": "Connection successful"
}

Status Code: 200 OK

Create Webhook Endpoint

Used to register a webhook URL where lead data will be sent.

• URL: /api/integrations/zapier/create_endpoint

• Method: POST

• Authentication Required: Yes

• Query Parameters:

  • chat_id: Your chat ID

  • api_key: Your Zapier integration API key

• Request Body:

  {
    "hookUrl": "https://hooks.zapier.com/hooks/catch/123456/abcdef/"
  }

Successful Response

{
  "message": "Endpoint created"
}

Status Code: 200 OK

Error Responses

{
  "message": "Endpoint creation failed"
}

Status Code: 422 Unprocessable Entity

{
  "message": "Invalid body"
}

Status Code: 422 Unprocessable Entity

Delete Webhook Endpoint

Used to delete a registered webhook URL.

• URL: /api/integrations/zapier/destroy_endpoint

• Method: DELETE (or POST depending on your implementation)

• Authentication Required: Yes

• Query Parameters:

  • chat_id: Your chat ID

  • api_key: Your Zapier integration API key

• Request Body:

  {
    "hookUrl": "https://hooks.zapier.com/hooks/catch/123456/abcdef/"
  }

Successful Response

{
  "message": "Endpoint destroyed"
}

Status Code: 200 OK

Error Response

{
  "message": "Endpoint not found"
}

Status Code: 422 Unprocessable Entity

Webhook Payloads

When a new lead is created in the system, a webhook notification is sent to all registered Zapier endpoints.

Lead Created Event

This webhook is triggered when a new lead is created.

Payload

{
  "email_address": "[e-mail]",
  "phone_number": "1234567890",
  "channel": "email" or "whatsapp",
  "marketing_consent": true or false
}

• email_address: The lead's email address (if available)

• phone_number: The lead's phone number (if available)

• channel: The channel through which the lead was acquired (either "email" or "whatsapp")

• marketing_consent: Whether the lead has provided consent for marketing communications

Error Handling

Authentication Errors

If the provided chat_id and api_key combination is invalid or not found:

{
  "message": "Unauthorized"
}

Status Code: 401 Unauthorized

Validation Errors

If the request body is invalid or missing required fields:

{
  "message": "Invalid body"
}

Status Code: 422 Unprocessable Entity

Best Practices

1. Store the webhook URL securely

2. Implement appropriate error handling in your Zapier workflows

3. Consider adding retry logic for failed webhook deliveries

4. Monitor webhook delivery success rates

5. Respect marketing consent flags when using lead data for marketing purposes