Skip to content
VocenyaDocs

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

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:

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

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

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:

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

4. Create a lead

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

Shell
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