Concepts
How Qualia works
The path a signup takes through Qualia, and the terms these docs use.
This page explains what happens after you send a signup, and defines the terms used across the docs and the API.
From signup to briefing
- You send a signup. Your backend calls
POST /v1/actorswith the person's email. Qualia creates an actor and replies right away with its ID. - Qualia checks the signup. Disposable, fake, and context-free signups are declined before any research starts. The actor's status becomes
rejected, and you are not charged. - Qualia researches the person and company. It looks for the person's role, their employer, what the company does, and recent facts worth knowing.
- Qualia scores the fit. It compares what it found with your ICP and sets a score from 0 to 100.
- The briefing is ready. The actor's status becomes
enriched. Read the briefing withGET /v1/actors/{actorId}, in the dashboard, or in Slack if you connected it.
Terms
| Term | Meaning |
|---|---|
| Actor | One person you sent to Qualia, identified by email. The API resource is /v1/actors. Each email maps to one actor in your organization. |
| Briefing | What Qualia writes about an actor: a summary, highlights, the person's role, and company details. In the API, these are fields on the actor. |
| ICP | Your ideal customer profile. You describe it during onboarding and refine it in Settings → ICP. |
| ICP fit score | A number from 0 to 100 in the actor's score field. It measures how closely the person and company match your ICP. It does not measure intent to buy. |
| Status | Where an actor is in its lifecycle: pending, enriching, enriched, rejected, or failed. See Actors. |
| Credit | The unit of usage. One briefing uses one credit. See Credits. |
| Organization | Your Qualia account. API keys, actors, credits, and your ICP all belong to it. |
| API key | A secret that starts with qk_live_ and authenticates requests for your organization. See Manage API keys. |
Credits
Each briefing Qualia delivers uses one credit from your organization's balance.
- An actor uses a credit when its status becomes
enriched. - Rejected and failed actors use no credits.
- Reading actors with
GETis free. - Sending an email that already exists creates no new briefing and uses no credit.
When the balance is empty, every POST /v1/actors request returns 402 Payment Required, even for an email Qualia already has, and Qualia does not record the signup. If the balance runs out after Qualia accepted a signup, that actor ends as rejected with rejectionReason: "quota_exceeded". Qualia does not research it later, even after you add credits.
Check your balance, change plans, or buy more credits in Settings → Billing.
Where results appear
| Place | What you get | How to set it up |
|---|---|---|
| API | The briefing and score as JSON fields on the actor. | Call GET /v1/actors/{actorId}. See Get briefing results. |
| Dashboard | Every signup with its briefing and the reasoning behind its score. | Nothing to set up. Open the dashboard. |
| Slack | A message in your channel for each researched signup, filtered by score and source. | Connect Slack. See Deliver briefings to Slack. |
Next steps
- Actors. What you send, how duplicates work, and every status.
- Briefings and ICP fit. Every field in a briefing and how the score works.