API

API reference

The Konvox REST API lets you manage campaigns, contacts, connections, and senders from your own code. All endpoints return JSON and require an API key.

Authentication

Create an API key in Settings > API keys. Pass it as a Bearer token on every request:

Authorization: Bearer kvx_live_your_key_here

You can also use the X-API-Key header as an alternative:

X-API-Key: kvx_live_your_key_here

ⓘ

API keys are scoped. A read key can list and fetch records. A full key can create, update, and delete. Keep full-scope keys out of client-side code.

Response format

Every response wraps its payload in an envelope:

{
  "data": { /* result or null */ },
  "error": null,           // string message on failure
  "meta": { "total": 24 }  // present on list endpoints
}

Campaigns

GET /api/campaigns

Returns all campaigns for the authenticated company, ordered by creation date descending. Includes a targetsByState breakdown on each record.

Query parameters

Parameter	Type	Description
`status`	string	Filter by status: `draft`, `active`, `paused`, `completed`

POST /api/campaigns

Creates a new campaign. Returns the created campaign with status 201.

Body

Field	Type	Required	Description
`name`	string	required	Campaign name shown in the dashboard
`channel`	string	required	`email`, `linkedin`, or `multi`
`profileId`	string	optional	ID of the AI communication profile to use
`senderIdentityId`	string	optional	Sender email address ID (required for email campaigns)

GET /api/campaigns/:id

Returns a single campaign with its targetsByState counts.

PATCH /api/campaigns/:id

Updates a campaign. Accepts the same fields as POST. You can also set status to active, paused, or completed.

DELETE /api/campaigns/:id

Deletes a campaign and all its enrollments. This cannot be undone. Returns { "success": true }.

Contacts

GET /api/contacts

Returns all contacts. Supports pagination and filtering.

Query parameters

Parameter	Type	Description
`status`	string	`active`, `unsubscribed`, `bounced`
`limit`	number	Max records to return (default 50, max 200)
`offset`	number	Offset for pagination

POST /api/contacts

Creates a contact. Duplicate emails within the same company return the existing record.

Body

Field	Type	Required	Description
`email`	string	required	Contact's email address
`firstName`	string	optional	First name
`lastName`	string	optional	Last name
`companyName`	string	optional	Contact's company
`linkedinUrl`	string	optional	LinkedIn profile URL
`title`	string	optional	Job title

Sender identities

GET /api/sender-identities

Returns all sender email addresses for the company, with warmup and daily limit data.

POST /api/sender-identities

Creates a new sender address. The full address is constructed as localPart@yourslug.konvox.io. A Mailgun inbound route is registered automatically.

Body

Field	Type	Required	Description
`localPart`	string	required	The part before the @. Only lowercase letters, numbers, and hyphens.
`displayName`	string	optional	Name shown in the From field

⚠

Sender limits apply per plan: Start = 1, Growth = 10, Scale = 50. Attempting to create more returns HTTP 403.

Connections

GET /api/connections

Returns all channel accounts (LinkedIn, email, social) connected to the company. Does not include secrets or passwords.

POST /api/connections

Creates a channel account connection.

Body

Field	Type	Required	Description
`name`	string	required	Display name for the account
`platform`	string	required	`linkedin`, `email`, `twitter`, `instagram`
`connectionMethod`	string	required	`socialcrabs`, `oauth_personal`, `oauth_company`, `oauth_page`, `oauth_konvox_app`, `oauth_own_app`
`username`	string	optional	Username or handle
`disclaimerAccepted`	boolean	optional	Required `true` for `socialcrabs` accounts

Webhooks

GET /api/webhooks

Returns all webhook endpoints registered for the company.

POST /api/webhooks

Registers a new webhook endpoint.

Body

Field	Type	Required	Description
`url`	string	required	HTTPS endpoint that will receive POST requests
`events`	array	required	Array of event names to subscribe to. See the event reference.
`active`	boolean	optional	Defaults to `true`

Error codes

HTTP status	Meaning
`400`	Validation error. Check the `error` field for the specific problem.
`401`	Missing or invalid API key.
`403`	Valid key but insufficient scope, or plan limit reached.
`404`	Record not found, or it belongs to a different company.
`409`	Conflict: duplicate record (e.g. email already exists).
`500`	Internal server error. Try again in a few seconds.