VictoriaAI
Getting started
View as Markdown

Quickstart

Create an API key, verify it, and add your first lead to a campaign with the Victoria AI REST API.

Last updated

This guide takes you from a new API key to a lead enrolled in a campaign. You need a Victoria AI account with at least one campaign.

Base URL

Every endpoint lives under one versioned base URL:

https://api.versionseven.ai/v1

1. Create an API key

Create a key in the Victoria AI app under Settings → API Keys. Organization owners and admins can manage keys. Keys start with vk_, and the full key is shown only once, when you create it, so store it somewhere safe, such as a secret manager.

The examples below read the key from an environment variable:

export VICTORIA_API_KEY="vk_your_api_key"

2. Verify the key

GET /v1/auth/verify confirms the key works and returns the organization it belongs to. It needs no scope, which makes it the right first call from a new integration.

curl https://api.versionseven.ai/v1/auth/verify \
  -H "Authorization: Bearer $VICTORIA_API_KEY"
{
  "success": true,
  "message": "API key is valid",
  "organization_id": "7f1c2b9e-4d3a-4f6b-9a2e-1c5d8e7f9a0b",
  "organization_name": "Acme"
}

A missing or unknown key answers 401 UNAUTHORIZED. Authentication covers keys, scopes and every authentication error.

3. Find a campaign

GET /v1/campaigns lists your campaigns, newest first. Note the id of the campaign you want to add a lead to.

curl "https://api.versionseven.ai/v1/campaigns?limit=20" \
  -H "Authorization: Bearer $VICTORIA_API_KEY"

4. Add a lead to the campaign

POST /v1/leads creates a lead and, because the body includes campaign_id, enrols it in that campaign. A lead needs first_name, last_name, and an email or linkedin_url.

curl -X POST https://api.versionseven.ai/v1/leads \
  -H "Authorization: Bearer $VICTORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "campaign_id": "550e8400-e29b-41d4-a716-446655440000",
    "lead": {
      "first_name": "Sarah",
      "last_name": "Johnson",
      "email": "sarah.johnson@acmecorp.com",
      "company": "Acme Corp",
      "title": "VP of Sales"
    }
  }'

The Idempotency-Key header makes the request safe to retry. If the connection drops and you send the request again with the same key, you get the original response back instead of a second attempt. See Idempotency.

A 201 response carries the new lead and its enrolment. The lead object below is shortened:

{
  "success": true,
  "message": "Lead successfully added to campaign",
  "lead_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "sequence_lead_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "campaign_id": "550e8400-e29b-41d4-a716-446655440000",
  "enrollment": {
    "sequence_lead_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "campaign_id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "lead": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "first_name": "Sarah",
    "last_name": "Johnson",
    "email": "sarah.johnson@acmecorp.com",
    "company": "Acme Corp",
    "title": "VP of Sales"
  }
}

The enrolment starts in the campaign's backlog, and the lead is contacted once the campaign has sending capacity for it.

If a lead with the same email or LinkedIn URL already exists in your organization, that lead is enrolled instead, and the response is 200 with lead_created: false. Sending a lead that's already in the campaign answers 409 LEAD_ALREADY_IN_CAMPAIGN.

5. Hear when the lead replies

Register a webhook on the campaign with POST /v1/campaigns/{campaign_id}/webhooks, and Victoria AI sends a prospect_response event to your URL when a prospect replies. Receiving webhooks walks through the setup, and Verifying signatures shows how to confirm each delivery came from Victoria AI.

Next steps