# Quickstart

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

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:

```text
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:

```bash
export VICTORIA_API_KEY="vk_your_api_key"
```

## 2. Verify the key

[`GET /v1/auth/verify`](https://docs.versionseven.ai/api-reference/auth/verify-api-key) 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.

```bash
curl https://api.versionseven.ai/v1/auth/verify \
  -H "Authorization: Bearer $VICTORIA_API_KEY"
```

```json
{
  "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](https://docs.versionseven.ai/guides/authentication) covers keys, scopes and every authentication error.

## 3. Find a campaign

[`GET /v1/campaigns`](https://docs.versionseven.ai/api-reference/campaigns/list-campaigns) lists your campaigns, newest first. Note the `id` of the campaign you want to add a lead to.

```bash
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`](https://docs.versionseven.ai/api-reference/leads/create-lead) 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`.

```bash
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](https://docs.versionseven.ai/guides/idempotency).

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

```json
{
  "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`](https://docs.versionseven.ai/api-reference/campaigns/create-webhook), and Victoria AI sends a [`prospect_response`](https://docs.versionseven.ai/api-reference/webhooks/prospect-response) event to your URL when a prospect replies. [Receiving webhooks](https://docs.versionseven.ai/guides/webhooks) walks through the setup, and [Verifying signatures](https://docs.versionseven.ai/guides/verifying-webhooks) shows how to confirm each delivery came from Victoria AI.

## Next steps

- [Connect your AI](https://docs.versionseven.ai/guides/connect-your-ai): do all of this from Claude, ChatGPT or Claude Code instead, signing in once and approving each write.
- [Set up a campaign by API](https://docs.versionseven.ai/guides/set-up-a-campaign): create a campaign, write its sequence, add AI fields and senders, and activate it.
- [Errors](https://docs.versionseven.ai/guides/errors): the error body and what every error code means.
- [Pagination](https://docs.versionseven.ai/guides/pagination) and [Rate limits](https://docs.versionseven.ai/guides/rate-limits), before you sync large lists.
- The [API Reference](https://docs.versionseven.ai/api-reference), for every endpoint.