# Quickstart

Create an API key and make your first request to the Vocenya API in a few minutes.

The Vocenya API gives your own systems the calls, leads, bookings and chats your AI receptionist handles, and lets them add leads, queue compliant outbound AI calls, keep your Do Not Call list and subscribe to webhooks. Everything is JSON over HTTPS.

## 1. Create an API key

An account owner creates keys in the Vocenya portal, under [Developers](https://vocenya.com/app/developers). Give the key a name you will recognise later (for example "CRM sync") and pick only the scopes the integration needs.

Start with a **test key**: switch the Developers page to **Test** before you create it. Test keys start with `vk_test_`, work on a separate set of sample data and never ring anyone, and they are available even before your account is fully set up. Switch to a live key (`vk_live_`) when your integration is ready. See [Test mode](https://vocenya.com/docs/test-mode).

The full key is shown **once**, when you create it. Vocenya stores only a hash, so copy it straight into your secrets manager. If you lose it, revoke it and create another.

Keep the key out of your code and read it from an environment variable. Every example in these docs uses `VOCENYA_API_KEY`:

```bash
export VOCENYA_API_KEY="paste-your-key-here"
```

## 2. Make your first request

`GET /me` works with any valid key and tells you which account and key you are using. It is the quickest way to check your setup.

```bash
curl https://vocenya.com/api/public/v1/me \
  -H "Authorization: Bearer $VOCENYA_API_KEY"
```

```javascript
const response = await fetch('https://vocenya.com/api/public/v1/me', {
  headers: { Authorization: `Bearer ${process.env.VOCENYA_API_KEY}` },
});

console.log(await response.json());
```

```php
$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://vocenya.com/api/public/v1/me', [
    'headers' => ['Authorization' => 'Bearer '.getenv('VOCENYA_API_KEY')],
]);

print_r(json_decode((string) $response->getBody(), true));
```

```python
import os

import requests

response = requests.get(
    "https://vocenya.com/api/public/v1/me",
    headers={"Authorization": f"Bearer {os.environ['VOCENYA_API_KEY']}"},
)
print(response.json())
```

The response names your organization, whether it is in HIPAA mode, whether the key is live or test (`data.livemode`), and the key's own name, prefix and scopes. A `401` means the key is missing, mistyped, expired or revoked.

## 3. Read your leads

With the `leads:read` scope, list the most recent leads:

```bash
curl "https://vocenya.com/api/public/v1/leads?per_page=5" \
  -H "Authorization: Bearer $VOCENYA_API_KEY"
```

Lists are newest first and come back as `{"data": [...], "links": {...}, "meta": {...}}`. Pass `meta.next_cursor` back as `cursor` for the next page: see [Pagination](https://vocenya.com/docs/pagination).

## 4. Create a lead

With `leads:write`, add a lead from another system, such as a website form. `reason` is the only required field.

```bash
curl -X POST https://vocenya.com/api/public/v1/leads \
  -H "Authorization: Bearer $VOCENYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Maria Rivera", "phone_number": "(512) 555-0123", "reason": "Wants a quote for a water heater replacement"}'
```

The response is `201 Created` with the new lead in `data`.

## Next steps

- [Authentication and scopes](https://vocenya.com/docs/authentication): what each scope allows.
- [Webhooks](https://vocenya.com/docs/webhooks): get leads, calls and chats pushed to you instead of polling.
- [Outbound calls](https://vocenya.com/docs/outbound-calls): have the AI call people back, within the calling rules.
- [API reference](https://vocenya.com/docs/reference): every endpoint, with code samples.
- Working with an AI assistant? Connect it to the [MCP servers](https://vocenya.com/docs/mcp).