Actors

An actor is one person you send to Qualia, identified by email. You create actors with POST /v1/actors and read them with GET /v1/actors/{actorId}. This page covers the fields you send, how repeat emails behave, and the statuses an actor moves through.

What you send

{
  "email": "anna@ridgeline.co",
  "name": "Anna Park",
  "source": "signup_form",
  "metadata": {
    "company": "Ridgeline",
    "plan": "free",
    "utmSource": "newsletter"
  }
}

source

Use source to tell your signup paths apart, for example signup_form, google_oauth, or team_invite. You can filter by source in the dashboard and in Slack delivery. Qualia keeps the source from the first request for an email and never changes it.

metadata

Send any context you already have: company, job title, plan, UTM parameters, or onboarding answers. Qualia stores it and uses it as extra context during research.

Some keys also tell Qualia who the person is. They matter most for signups from personal email addresses, such as Gmail or Proton addresses:

Key matching ignores case and punctuation, so companyName, company_name, and Company-Name all work. Values must be non-empty strings.

A signup from a personal email address with no name and none of these keys is rejected with insufficient_context, because there is nothing to research. See Handle rejected signups.

One actor per email

Each email maps to one actor in your organization. POST /v1/actors is safe to retry:

A repeat request does not research the person again and uses no credit. Qualia also ignores the name, source, and metadata it contains.

The one exception is a rejected actor. If the actor was rejected for any reason other than quota_exceeded, and the new request passes Qualia's signup checks, Qualia saves any new name and metadata and starts research again. This is how you fix a signup that was missing context. See Handle rejected signups.

Emails match without regard to case: Anna@Ridgeline.co and anna@ridgeline.co are the same actor.

Lifecycle

An actor's status tells you where it is:

The usual path is pending, then enriching, then enriched.

Some signups take a different path:

• Rejected at creation. Qualia checks every signup when you send it. A signup that fails the check is rejected from the start. The create request still returns 201 Created, so read the actor to see the status.
• Rejected during research. Some checks run after the signup is accepted. The status can move from enriching to rejected. This also happens when your credits run out before research starts.
• Failed, then retried. After an error, Qualia retries the run up to two more times, about a minute apart. The status can move from failed back to enriching.
• Rejected, then fixed. When a later request for the same email passes the signup checks, for example by adding a missing name, a rejected actor moves back to pending. This never happens for quota_exceeded.

For polling code that handles each case, see Get briefing results.

Coming later

Today an actor is created from a signup. Sending product events and CRM records for the same actor is planned and not yet available.

Next steps

• Briefings and ICP fit. What an enriched actor contains.
• Send signups to Qualia. Where to add the call in your backend.
• Create an actor. The full endpoint reference.