> ## Documentation Index
> Fetch the complete documentation index at: https://help.hoopai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# HoopAI Platform API
> Complete REST API reference for the HoopAI Platform. Build integrations for contacts, calendars, conversations, payments, automations, and more.
The HoopAI Platform API is a RESTful API that gives you programmatic access to every feature in the platform — contacts, conversations, calendars, opportunities, payments, automations, funnels, and more.
New to HoopAI? Start with the [Getting Started guide](/getting-started/overview) to set up your account before diving into the API.
## What you can build
Use the API to build marketplace apps, automate workflows, sync external systems, and extend the platform. Common use cases include:
* **CRM automation** — Create contacts, update pipelines, and trigger workflows
* **Appointment booking** — Manage calendars, slots, and booking widgets
* **Messaging** — Send SMS, email, and chat messages across channels
* **Commerce** — Process orders, manage products, and generate invoices
* **Marketing** — Schedule social posts, manage funnels, and track campaigns
## Available APIs
### Generally available
| API | Description | Endpoints |
| ------------------------------------------------------ | ----------------------------------------------------------------- | --------- |
| [Contacts](/api-reference/contacts/overview) | Full contact lifecycle — create, search, tag, enroll in campaigns | 19 |
| [Conversations](/api-reference/conversations/overview) | Send and receive messages across all channels | 17 |
| [Calendars](/api-reference/calendars/overview) | Booking, appointments, free slots, and availability | 24 |
| [Opportunities](/api-reference/opportunities/overview) | Manage pipeline stages and deal values | 8 |
| [Payments](/api-reference/payments/overview) | Orders, transactions, subscriptions, and providers | 16 |
| [Products](/api-reference/products/overview) | Product catalog, pricing, inventory, and collections | 18 |
| [Invoices](/api-reference/invoices/overview) | Create, send, and track invoices and estimates | 30 |
| [Accounts](/api-reference/locations/overview) | Manage locations, custom fields, and templates | 16 |
| [Users](/api-reference/users/overview) | Manage team members and user accounts | 4 |
| [Forms](/api-reference/forms/overview) | Form builder, submissions, and exports | 29 |
| [Funnels](/api-reference/funnels/overview) | Funnel pages, domains, and builder | 163 |
| [Workflows](/api-reference/workflows/overview) | List and trigger automation workflows | 1 |
| API | Description |
| -------------------------------------------------------------- | ------------------------------------------------- |
| [Blogs](/api-reference/blogs/overview) | Blog post management, authors, and categories |
| [Businesses](/api-reference/businesses/overview) | Business entity management |
| [Campaigns](/api-reference/campaigns/overview) | List and manage drip campaigns |
| [Custom Fields](/api-reference/custom-fields/overview) | Define custom fields on contacts and objects |
| [Emails](/api-reference/emails/overview) | Email builder, templates, and campaign stats |
| [Trigger Links](/api-reference/links/overview) | Create and manage workflow trigger links |
| [Media Library](/api-reference/medias/overview) | Upload and manage files and folders |
| [Objects](/api-reference/objects/overview) | Custom data objects and records |
| [Associations](/api-reference/associations/overview) | Define relationships between objects |
| [Social Planner](/api-reference/social-media-posting/overview) | Schedule and manage social media posts |
| [Store](/api-reference/store/overview) | Shipping zones, carriers, and storefront settings |
| [Surveys](/api-reference/surveys/overview) | Survey management and submission data |
## Base URL
All API requests go to:
```
https://services.leadconnectorhq.com
```
The base URL uses a platform infrastructure domain. This is the API service that powers HoopAI — all data belongs to your HoopAI account.
## Authentication
The HoopAI Platform API uses **OAuth 2.0**. Every request requires two headers:
| Header | Value | Required |
| --------------- | ----------------------- | --------------------- |
| `Authorization` | `Bearer ` | Yes |
| `Version` | `2021-07-28` | Yes |
| `Content-Type` | `application/json` | For POST/PUT requests |
Get a token by following the [OAuth 2.0 Authorization Code flow](/api-reference/oauth/authorization). Tokens expire after **24 hours** — use the refresh token to get a new one.
The `Version` header is required on every request. Always send `2021-07-28` to ensure stable, predictable behavior across API updates.
## Quick start
```bash cURL theme={null}
# List contacts for a location
curl -X GET "https://services.leadconnectorhq.com/contacts/?locationId=YOUR_LOCATION_ID&limit=20" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Version: 2021-07-28"
```
```javascript JavaScript theme={null}
const response = await fetch(
'https://services.leadconnectorhq.com/contacts/?locationId=YOUR_LOCATION_ID&limit=20',
{
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Version': '2021-07-28'
}
}
);
const { contacts } = await response.json();
```
```python Python theme={null}
import requests
response = requests.get(
'https://services.leadconnectorhq.com/contacts/',
params={'locationId': 'YOUR_LOCATION_ID', 'limit': 20},
headers={
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Version': '2021-07-28'
}
)
contacts = response.json()['contacts']
```
## Rate limits
| Scope | Limit |
| ------------- | ------------------------- |
| Per account | 100 requests / 10 seconds |
| Token refresh | 5 requests / minute |
Responses include `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers. Retry `429` responses with exponential backoff.
## Error responses
All errors return a JSON body:
```json theme={null}
{
"message": "Invalid token",
"statusCode": 401
}
```
| Status | Meaning |
| ------ | ------------------------------------------------- |
| `400` | Bad request — missing or invalid parameters |
| `401` | Unauthorized — token missing, expired, or invalid |
| `403` | Forbidden — token lacks required scope |
| `404` | Not found |
| `422` | Unprocessable — validation error |
| `429` | Rate limit exceeded |
| `500` | Internal server error |
## Next steps
Get your access token and start making requests
Create and manage your CRM contacts
Send messages across SMS, email, and chat
Manage bookings, appointments, and availability
Process orders and manage subscriptions
React to real-time platform events