> ## 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.

# Quick start

> Make your first HoopAI API call in under 5 minutes.

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](https://platform.hoopai.com))
* A **Private Integration** app or an **OAuth app** from the [Marketplace](https://marketplace.hoopai.com/)
* An access token (see [Authentication](/developer/guide/authentication))

<Note>
  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.
</Note>

## Make your first API call

<Tabs>
  <Tab title="cURL">
    <Steps>
      <Step title="Set your credentials">
        ```bash theme={null}
        export HOOPAI_TOKEN='your-access-token'
        export LOCATION_ID='your-location-id'
        ```
      </Step>

      <Step title="Fetch contacts">
        ```bash theme={null}
        curl -X GET "https://services.leadconnectorhq.com/contacts/?locationId=$LOCATION_ID&limit=5" \
          -H "Authorization: Bearer $HOOPAI_TOKEN" \
          -H "Version: 2021-07-28"
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="JavaScript">
    <Steps>
      <Step title="Install dependencies">
        ```bash theme={null}
        npm install node-fetch
        ```
      </Step>

      <Step title="Create quickstart.js">
        ```javascript theme={null}
        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})`));
        ```
      </Step>

      <Step title="Run it">
        ```bash theme={null}
        node quickstart.js
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Python">
    <Steps>
      <Step title="Install dependencies">
        ```bash theme={null}
        pip install requests
        ```
      </Step>

      <Step title="Create quickstart.py">
        ```python theme={null}
        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')})")
        ```
      </Step>

      <Step title="Run it">
        ```bash theme={null}
        python quickstart.py
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

### Example response

```json theme={null}
{
  "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?

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

## Try something more

<CardGroup cols={2}>
  <Card title="Create a contact" icon="user-plus">
    ```bash theme={null}
    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"
      }'
    ```
  </Card>

  <Card title="Send a message" icon="message">
    ```bash theme={null}
    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!"
      }'
    ```
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={3}>
  <Card title="Authentication" icon="lock" href="/developer/guide/authentication">
    Set up OAuth 2.0 for production use
  </Card>

  <Card title="Making requests" icon="code" href="/developer/guide/making-requests">
    Learn request patterns, pagination, and filtering
  </Card>

  <Card title="Webhooks" icon="bell" href="/developer/guide/webhooks">
    React to real-time events from HoopAI
  </Card>
</CardGroup>