Create an actor

Creates an actor for the given email and enqueues enrichment. Idempotent on email within an organization. Returns 201 with status "created" for a new actor, or 200 with status "already_exists" if an actor with this email already exists in your organization.

Authorization

bearerAuth

AuthorizationBearer <token>

API key issued via the dashboard. Format: qk_live_<random>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

email*string

Email address of the actor (required, RFC 3696 max length).

Match^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$

Formatemail

Lengthlength <= 320

name?string

Display name for the actor, if known.

Lengthlength <= 255

source?string

Free-form label describing where the actor came from (e.g. 'signup_form', 'admin_import'). First-touch only; never overwritten on subsequent calls.

Lengthlength <= 50

metadata?

Arbitrary additional fields to attach to the actor. The API does not enforce a schema on this object. Send whatever context you have (company, title, plan, UTM params, onboarding progress, etc.). Stored verbatim and available to the enrichment agent as additional context.

Response Body

`application/json`

curl -X POST "https://qualia.so/v1/actors" \  -H "Content-Type: application/json" \  -d '{    "email": "user@example.com"  }'

{
  "actorId": "string",
  "status": "created"
}

{
  "actorId": "string",
  "status": "created"
}

{
  "error": {
    "code": "bad_request",
    "message": "string",
    "requestId": "string"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "string",
    "requestId": "string"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "string",
    "requestId": "string"
  }
}

{
  "error": {
    "code": "unprocessable_entity",
    "message": "string",
    "requestId": "string"
  }
}

{
  "error": {
    "code": "internal_server_error",
    "message": "string",
    "requestId": "string"
  }
}

Create an actor

Authorization

Request Body

Response Body

200application/json

201application/json

400application/json

401application/json

404application/json

422application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`