Production API base: https://api.vertextlabs.com

---

Authentication

All requests must include a valid access token in the Authorization HTTP header:

Authorization: Bearer youraccesstoken

• The access token identifies the user making the request, and all actions performed will affect that user’s resources (chatbots, contacts, etc).
• If the header is missing, the response will always be 400 Bad Request.
• If the token is expired or invalid, the response will always be 401 Unauthorized.

---

Common Parameters

All endpoints support the following query parameters:

Parameter	Type	Default	Description
page	Integer	0	Offset into the resource collection. Must be ≥ 0.
per_page	Integer	100	Number of resources to return. Must be > 0.

Example: With page=3 and per_page=40, the API will return entries starting at index 120 (3×40), up to 40 resources.

---

Resource Models

Below are the definitions of the resources available through the API.

Only meta_psid and widget_conversation_id in the Contact model can be null. This is because contacts may originate either from Meta apps (Facebook, Instagram, etc.) or from the embedded widget. All other fields are guaranteed to be present.

Timestamp fields such as created_at, first_interaction, and last_interaction are Unix timestamps.

---

Chatbot

{
  "id": "7a81c98d-12c3-4edf-41ac-df1e6762d677",
  "name": "Demo",
  "description": "Chatbot used for internal testing.",
  "prompt": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
  "temperature": 0.7,
  "created_at": 1751661250,
  "user_id": "dae7cf95-1376-476a-b249-01b1cb2d3345",
  "status": "Active"
}

---

Contact

{
  "id": "8f2c1a50-3c70-4e25-a903-da8995d244a3",
  "name": "John Doe",
  "email": "[email protected]",
  "phone": "555-1234",
  "notes": "",
  "source": "Widget",
  "meta_psid": null,
  "widget_conversation_id": "d39c8220-69ec-438b-8633-b9c827e976ca",
  "is_automation_enabled": true,
  "first_interaction": 1755605814,
  "last_interaction": 1755605815,
  "chatbot_id": "7a81c98d-12c9-4edf-a1ac-df136762d677",
  "is_unread": true,
  "lifecycle": "Lead"
}

---

Error Responses

• The API uses standard HTTP status codes.
• Errors include a plain-text response body for direct usage without extra parsing.
• Rarely, a 500 Internal Server Error may occur. Please report these with details of the attempted operation.

---

Available Endpoints

---

GET /chatbots/list

Lists chatbots owned by the authenticated user, sorted by creation date (ascending).

Request Example

curl -X GET "https://api.vertextlabs.com/chatbots/list?page=0&per_page=2" \
  -H "Authorization: Bearer youraccesstoken"

Example Response 200 OK

[
  {
    "id": "7a81c98d-12c3-4edf-41ac-df1e6762d677",
    "name": "Demo",
    "description": "Chatbot used for internal testing.",
    "prompt": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
    "temperature": 0.7,
    "created_at": 1751661250,
    "user_id": "dae7cf95-1376-476a-b249-01b1cb2d3345",
    "status": "Active"
  },
  {
    "id": "2b9e1f4a-8c21-4e3b-bc7a-5f2e8a1d1234",
    "name": "SupportBot",
    "description": "Chatbot for customer support.",
    "prompt": "How can I assist you with your support needs today?",
    "temperature": 0.5,
    "created_at": 1751661350,
    "user_id": "dae7cf95-1376-476a-b249-01b1cb2d3345",
    "status": "Active"
  }
]

Errors

Code	Meaning
—	No specific errors.

---

POST /chatbots/{chatbot_id}/zapier_subscriptions

Creates a new Zapier webhook subscription for the given chatbot.

Parameters (Form Body)

Parameter	Type	Required	Description
target_url	String	Yes	The Zapier webhook URL where events will be sent.

Request Example

curl -X POST "https://api.vertextlabs.com/chatbots/{chatbot_id}/zapier_subscriptions" \
  -H "Authorization: Bearer youraccesstoken" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "target_url=https://hooks.zapier.com/hooks/standard/12345678/45110d9a83444db193a48e561cdf9b40/"

Example Response 201 Created

{
  "id": "2e4459a9-bfd2-4e4b-b4ab-c35805cc0e20",
  "chatbot_id": "95c1dbaf-e291-43fc-a9b4-c48f1a86afeb",
  "target_url": "https://hooks.zapier.com/hooks/standard/12345678/45110d9a83444db193a48e561cdf9b40/"
}

Errors

Code	Meaning
404 Not Found	Chatbot does not exist or does not belong to the user.

---

DELETE /chatbots/{chatbot_id}/zapier_subscriptions/{id}

Deletes a Zapier subscription by ID for the given chatbot.

Request Example

curl -X DELETE "https://api.vertextlabs.com/chatbots/{chatbot_id}/zapier_subscriptions/{id}" \
  -H "Authorization: Bearer youraccesstoken"

Example Response 204 No Content

Errors

Code	Meaning
404 Not Found	Chatbot does not exist or does not belong to the user.
404 Not Found	Zapier subscription with the given ID not found.

---

GET /contacts/{chatbot_id}

Lists contacts for a given chatbot.

Request Example

curl -X GET "https://api.vertextlabs.com/contacts/{chatbot_id}?page=0&per_page=2" \
  -H "Authorization: Bearer youraccesstoken"

Example Response 200 OK

[
  {
    "id": "8fb610b3-a7d1-4407-9940-98bab3ffa8cc",
    "name": "",
    "email": "",
    "phone": "",
    "notes": "",
    "source": "Widget",
    "meta_psid": null,
    "widget_conversation_id": "c8e5796b-13f5-470b-b92a-61f67fc2b3ff",
    "is_automation_enabled": true,
    "first_interaction": 1755349448,
    "last_interaction": 1755356254,
    "chatbot_id": "7a81c98d-12c9-4edf-a1ac-df136762d677",
    "is_unread": true,
    "lifecycle": "Lead"
  }
]

Errors

Code	Meaning
404 Not Found	Chatbot does not exist or does not belong to the user.