Quickstart

This guide walks you through making your first request to the Qualia API: creating an actor and fetching the briefing once enrichment completes.

1. Get an API key

Create a key in Settings → API Keys. Copy the plaintext. It is shown once.

export QUALIA_API_KEY="qk_live_..."

To persist across shells, append the line above to ~/.zshrc or ~/.bashrc.

2. Create an actor

// app/qualia.ts
import { Qualia } from "@qualiaso/sdk";

const qualia = new Qualia({
  auth: () => process.env.QUALIA_API_KEY!,
});

const { data, error } = await qualia.createActor({
  body: {
    email: "anna@ridgeline.co",
    name: "Anna Park",
    source: "product_signup",
  },
});

if (error) throw error;

const { actorId, status } = data;

The response is { actorId, status }. status is "created" for a new actor (enrichment is enqueued) or "already_exists" if an actor with this email already exists in your organization.

3. Read the briefing

Enrichment runs asynchronously. Poll the actor until status is "enriched" (success) or "failed" (terminal failure).

// app/qualia.ts
const { data: actor, error } = await qualia.getActor({
  path: { actorId },
});

if (error) throw error;

console.log(actor.status, actor.summary, actor.score);

Once status is "enriched", the contact-card fields (summary, highlights, bio, companyDescription, title, linkedinUrl, companyName, ...) and the ICP fit score are populated.

4. When status is "failed"

If an actor lands as failed, the response carries a failureReason describing which gate stopped enrichment:

const { data: actor } = await qualia.getActor({ path: { actorId } });

if (actor.status === "failed" && actor.failureReason === "insufficient_context") {
  // Re-call with the missing context - same email, plus a name or company hint.
  // The actor transitions back to "pending" and enrichment is re-queued.
  await qualia.createActor({
    body: { email: actor.email, name: "Anna Park", metadata: { company: "Ridgeline" } },
  });
}

The auto-rescue applies to every eligibility-related failure reason. It does NOT apply to quota_exceeded: the cap is org-level and retrying won't help.

See SDK quickstart for the full table with a worked example.

Next

• Concepts. The shape of an actor and a briefing.
• API reference. Every operation page with request and response schemas.