Quickstart
Get up and running with the Vocalis API in just a few steps.
1Create your API key
Navigate to Settings → API Keys in the Vocalis dashboard to create your API key. Keep this key secure as it provides full access to your account.
Go to API Keys Settings2List your contact lists
Make your first API request to list all contact lists in your account:
curl -X GET "https://vocalis.io/api/v1/contact-lists" \-H "x-api-key: YOUR_API_KEY"
3Create a contact list with schema
Create a new contact list with a custom schema to define the fields for your contacts:
curl -X POST "https://vocalis.io/api/v1/contact-lists" \-H "x-api-key: YOUR_API_KEY" \-H "Content-Type: application/json" \-d '{"name": "Sales Leads Q1","schema": {"fields": [{ "name": "firstName", "type": "string", "required": true },{ "name": "lastName", "type": "string", "required": true },{ "name": "phoneNumber", "type": "phone", "required": true },{ "name": "company", "type": "string" },{ "name": "leadScore", "type": "number" }]}}'
4Import contacts
Import contacts to your list. You can provide contacts directly as JSON or via a file URL:
curl -X POST "https://vocalis.io/api/v1/contact-lists/{listId}/contacts" \-H "x-api-key: YOUR_API_KEY" \-H "Content-Type: application/json" \-d '{"contacts": [{"firstName": "John","lastName": "Doe","phoneNumber": "+14155551234","company": "Acme Corp","leadScore": 85},{"firstName": "Jane","lastName": "Smith","phoneNumber": "+14155555678","company": "Tech Inc","leadScore": 92}]}'
Async processing
Large imports are processed asynchronously. The response includes an import job ID that you can use to track progress.
5Check import status
For large imports, check the status of your import job:
curl -X GET "https://vocalis.io/api/v1/import-jobs/{jobId}" \-H "x-api-key: YOUR_API_KEY"
The response will include the job status and progress:
{"id": "job_abc123","status": "completed","progress": {"total": 100,"processed": 100,"successful": 98,"failed": 2},"createdAt": "2024-01-15T10:30:00Z","completedAt": "2024-01-15T10:30:45Z"}
File URL imports
For large datasets, you can provide a URL to a JSON or CSV file instead of sending contacts directly. The file will be downloaded and processed asynchronously.