Account Setup

Overview

Before you start, you need an organization. Click Get started at delivr.ai/api to sign up with your work email. Verify the email, set your password, and sign in at app.delivr.ai. If your team already has an account, an admin invites you from Settings > Members instead. Contract customers are invited by their Delivr contact. From there, everything is self-serve, including inviting teammates.

Signing up creates your organization and its first project, named after your organization. To query your site's events, you need that project's ID and at least one pixel. An intent audience needs a project only.

Creating the credential itself is dashboard-only. Once you hold an organization API key + secret, everything else in this guide is available via API.

Most integrations only need an organization API key + secret pair. That covers querying events, audiences, taxonomy, and identity lookup across every project in the org, plus full management of your organization, projects, pixels, and members. To give a client or integration access to one project only, create a project-scoped key instead.

Managing your organization, projects, pixels, and members works with the organization API key (X-Api-Key + X-Api-Secret) directly. You can read, update, or delete your own organization (https://api.delivr.ai/api/v1/organization). You also get full project and pixel CRUD (https://api.delivr.ai/api/v1/project* and https://api.delivr.ai/api/v1/pixel*) and organization- and project-member management (.../api/v1/organization/user* and .../api/v1/project/user*). On the org-key path, a project-scoped call names its target project in the request. Writes use a project_id field. Reads use a ?project_id= query parameter.

Base URL: https://api.delivr.ai for everything: management, events, audiences, taxonomy, and lookup.

Concepts

Step 1: Create an Organization API Key

The organization API key + secret pair is the credential for everything in this guide. It covers creating projects and pixels, and querying events, audiences, taxonomy, and identity lookup. Create it in the dashboard:

1. Sign in at app.delivr.ai.
2. Open https://app.delivr.ai/{org_id}/settings/api-keys and click Create API key.
3. Under Environment, choose Live. New keys default to Test.
4. Click Create key.
5. Copy the key and secret. The secret is shown once.

This guide creates a real pixel, so it needs a live key. A test key gets a sample pixel ID from the sandbox, and no pixel is created.

The pair goes in two headers on every request:

X-Api-Key: dlvr_xxxxxxxx
X-Api-Secret: xxxxxxxx

There is no separate token exchange. The key authenticates directly, and every call is scoped to the key's own organization, so you never pass an organization_id.

Step 2: Find Your Project ID

Signing up created your first project, named after your organization. Use it for the pixel and the data calls below. List your projects to get its ID:

curl https://api.delivr.ai/api/v1/project/get \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET"

Response

{
  "response": {
    "projects": [
      {
        "project_id": "5b6f6b47-5ba7-...",
        "name": "Acme",
        "status": "active",
        "created_at": "2026-01-01 10:00:00"
      }
    ]
  }
}

Save the project_id. You will pass it to the Events and Audiences APIs. Create your pixel in this project. If you create the pixel in a second project, its events go to that project and this one stays empty.

Create Another Project (Optional)

Create a project only if you need more than one, for example one per client site. If the list above comes back empty, create one here:

curl -X POST https://api.delivr.ai/api/v1/project/create \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "project": {
      "name": "Client Site"
    }
  }'

The project is created in the organization the key belongs to. There is no organization_id header on this path. The response carries the new project_id:

{
  "response": {
    "project_id": "9c1d2e34-7f80-..."
  }
}

Provisioning a project per tenant? This endpoint is the one to automate against. It needs no dashboard session and no token refresh, so a server-side job can call it with a stored key pair.

Prefer the UI? Create projects from Projects in your organization's sidebar.

Step 3: Create a Pixel

Create a pixel for your project. Either via API:

curl -X POST https://api.delivr.ai/api/v2/pixel/create \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "YOUR_PROJECT_ID",
    "title": "My Website Pixel",
    "allowed_origins": ["example.com"]
  }'

The target project is named in the body and must belong to your key's organization. allowed_origins lists the sites the pixel runs on. If one pixel runs on many sites, such as an agency's client sites, send "allow_any_origin": true instead. See Declare Where Your Pixel Runs.

Or from the dashboard:

1. In your project, open Activate > Connections. Click Add Connection and select Pixel.
2. On General details, enter a Pixel title and click Continue.
3. On Websites, choose My websites.
4. List each site the pixel runs on, one per line.
5. Click Create pixel.
6. On Pixel setup, copy the install snippet. To install it later, click Finish later and choose Keep pixel.

Response

{
  "response": {
    "pixel_id": "8a755c42-b2b1-...",
    "installation_url": "https://cdn.delivr.ai/pixels/8a755c42-b2b1-.../p.js",
    "allowed_origins": ["example.com"],
    "allow_any_origin": false,
    "origins_status": "declared"
  }
}

Add the install snippet to your site's <head>:

<script id="delivr-ai" src="https://cdn.delivr.ai/pixels/YOUR_PIXEL_ID/p.js" async></script>

Verify your first event

Before you build anything on top of the pixel, confirm an event actually arrives. Load a page on your site so the pixel fires, then check either way:

• In the dashboard: keep the Pixel setup step open, or open the pixel's Settings > Install tab later. It shows Listening for your first event... and changes to First event received when data arrives.
• From the API (once you have the key from Step 1): query the base event tier and confirm rows come back.

curl -s "https://api.delivr.ai/api/v3/events/web_event?project_id=YOUR_PROJECT_ID&limit=10" \
  -H "X-Api-Key: dlvr_xxxxxxxx" \
  -H "X-Api-Secret: YOUR_SECRET"

If rows come back, your pixel is wired up correctly.

Summary: What You Have Now

Full credential walkthrough: Authentication.

Next Steps

You now have a project, a pixel, and an API key + secret pair. Choose your path:

Path 1: On-Domain Events (Pixel)

Query visitor events from your installed pixel. New integrations should use the per-tier Events API v3, where the route you call fixes the price.

On-Domain Events API · Events API v3

Path 2: Intent Audiences

Create intent-based audiences on your project and download the results.

Intent Audiences API