REST API reference
The Cortex Voice API is a standard REST API using JSON for all requests and responses. Authentication is handled via an API key passed in the HTTP header.
Base URL: https://api.comulead.com/v1
Required header: Authorization: Bearer YOUR_API_KEY
Format: Content-Type: application/json
| Endpoint | Method | Description |
|---|---|---|
/surveys | GET | List all surveys on the account |
/surveys/{id} | GET | Details of a specific survey |
/surveys/{id}/responses | GET | All responses for a survey |
/responses/{id} | GET | Details of a response (score + verbatim + themes) |
/contacts | POST | Add or update contacts |
/reports/nps | GET | Aggregated NPS score for a period |
The complete API documentation with request and response examples is available at api.comulead.com/docs. You can test each endpoint directly from the interface by authenticating with your test API key (sandbox environment).
Downloadable CSV templates
Cortex Voice accepts CSV files for contact imports and bulk survey sending. Use the official templates to avoid formatting errors.
| Template | Required columns | Optional columns |
|---|---|---|
| Standard contact import | email | firstname · lastname · company |
| Enriched contact import | email | firstname · segment · purchase_date · product |
| CRM contact import | email · crm_id | firstname · account_owner · contract_value |
In Cortex Voice → Surveys → New survey → Distribution step → Email channel → click Download CSV template. The file opens directly in Excel or Google Sheets.
Follow these rules to avoid import errors:
- UTF-8 encoding is mandatory (special characters and accents)
- Delimiter: comma (
,) — not semicolons - First row = column headers (exact names from the template)
- No empty rows or merged cells
- Email addresses in lowercase, format
name@domain.com
Excel on Windows sometimes saves in ANSI encoding by default, which corrupts accented characters. To force UTF-8 in Excel: File → Save As → File type: CSV UTF-8 (comma delimited). In Google Sheets, CSV exports are always UTF-8.
Survey template library
Cortex Voice provides ready-to-use templates for the most common SMB use cases.
| Template | Use case | No. of questions |
|---|---|---|
| Standard Relational NPS | Quarterly program, overall satisfaction | 2 |
| Post-purchase NPS | Triggered 48 hours after transaction | 3 |
| Onboarding NPS | 30 days after service activation | 3 |
| Renewal NPS | 45 days before contract expiry | 4 |
| Support NPS | After a support ticket is resolved | 3 |
Downloadable resources
These resources are available in Cortex Voice → Resources (bottom sidebar menu):
- Quick-start guide (PDF, 8 pages) — Summary of the first 5 steps in a printable format
- NPS tracking spreadsheet (Google Sheets) — Monthly tracking template with automatic formulas and charts
- Follow-up email templates (DOCX) — 6 templates for responding to detractors, passives and promoters
- Bill 25 compliance checklist (PDF) — 10 verification points for your surveys and data handling
- NPS & CX glossary (PDF) — 35 key definitions to build an NPS culture across your team
API limits and quotas
| Limit | Value | Reset |
|---|---|---|
| API requests | 1,000 / hour | Every hour |
| Contact import | 5,000 per file | Per import |
| Email sends | 10,000 / day | Midnight EST |
| Active webhooks | 10 per account | Permanent |
| Data retention | 24 rolling months | Monthly |
If your usage exceeds these quotas, contact support@comulead.com to discuss a tailored plan. Email send limits can be increased on request after verifying your domain's deliverability setup.
Key takeaways
- The REST API is documented interactively at
api.comulead.com/docs— test each endpoint in the sandbox - Always use the official CSV template and export in UTF-8 to avoid character corruption
- 5 ready-to-use survey templates cover the most common SMB use cases
- Downloadable resources (templates, Bill 25 checklist, glossary) are in the Resources menu of Cortex Voice
- Limit of 1,000 API requests per hour — use pagination for large data exports