Quick start

Get up and running with the HoopAI Platform API. By the end of this guide, you’ll have made your first API call and retrieved contacts from an account.

Prerequisites

A HoopAI account (sign up here)
A Private Integration app or an OAuth app from the Marketplace
An access token (see Authentication)

For quick testing, use a Private Integration — it gives you a long-lived API key without the full OAuth flow. Go to Settings > Integrations > Private Integrations in your HoopAI account.

Make your first API call

cURL
JavaScript
Python

Set your credentials

export HOOPAI_TOKEN='your-access-token'
export LOCATION_ID='your-location-id'

Fetch contacts

curl -X GET "https://services.leadconnectorhq.com/contacts/?locationId=$LOCATION_ID&limit=5" \
  -H "Authorization: Bearer $HOOPAI_TOKEN" \
  -H "Version: 2021-07-28"

Install dependencies

npm install node-fetch

Create quickstart.js

const TOKEN = 'your-access-token';
const LOCATION_ID = 'your-location-id';

const response = await fetch(
  `https://services.leadconnectorhq.com/contacts/?locationId=${LOCATION_ID}&limit=5`,
  {
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'Version': '2021-07-28'
    }
  }
);

const data = await response.json();
console.log(`Found ${data.contacts.length} contacts:`);
data.contacts.forEach(c => console.log(`  - ${c.name} (${c.email})`));

Run it

node quickstart.js

Install dependencies

pip install requests

Create quickstart.py

import requests

TOKEN = 'your-access-token'
LOCATION_ID = 'your-location-id'

response = requests.get(
    'https://services.leadconnectorhq.com/contacts/',
    params={'locationId': LOCATION_ID, 'limit': 5},
    headers={
        'Authorization': f'Bearer {TOKEN}',
        'Version': '2021-07-28'
    }
)

data = response.json()
print(f"Found {len(data['contacts'])} contacts:")
for c in data['contacts']:
    print(f"  - {c.get('name', 'N/A')} ({c.get('email', 'N/A')})")

Run it

python quickstart.py

Example response

{
  "contacts": [
    {
      "id": "abc123",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "phone": "+15551234567",
      "tags": ["lead", "website-visitor"],
      "dateAdded": "2025-01-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "total": 142,
    "currentPage": 1,
    "nextPage": 2
  }
}

What just happened?

You sent a GET request to the Contacts API
The Authorization header carried your OAuth bearer token
The Version header (2021-07-28) tells the API which version to use
The API returned contacts scoped to your locationId (account)

Try something more

Create a contact

curl -X POST "https://services.leadconnectorhq.com/contacts/" \
  -H "Authorization: Bearer $HOOPAI_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "YOUR_LOCATION_ID",
    "name": "Test Contact",
    "email": "test@example.com"
  }'

Send a message

curl -X POST "https://services.leadconnectorhq.com/conversations/messages" \
  -H "Authorization: Bearer $HOOPAI_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SMS",
    "contactId": "CONTACT_ID",
    "message": "Hello from HoopAI!"
  }'

Next steps

Authentication

Set up OAuth 2.0 for production use

Making requests

Learn request patterns, pagination, and filtering

Webhooks

React to real-time events from HoopAI

First Steps

Guides

Prerequisites

Make your first API call

Example response

What just happened?

Try something more

Create a contact

Send a message

Next steps

Authentication

Making requests

Webhooks

First Steps

Guides

​Prerequisites

​Make your first API call

​Example response

​What just happened?

​Try something more

Create a contact

Send a message

​Next steps

Authentication

Making requests

Webhooks

Prerequisites

Make your first API call

Example response

What just happened?

Try something more

Next steps