Actors

An actor is one person, identified by email, ingested into your organization. Create one with POST /v1/actors.

Shape

{
  "email": "anna@ridgeline.co",
  "name": "Anna Park",
  "source": "product_signup",
  "metadata": { "plan": "pro" }
}

Field	Type	Required	Description
`email`	string	yes	Email address (RFC 3696, max 320 chars).
`name`	string	no	Display name for the actor, if known.
`source`	string	no	Free-form label describing where the actor came from (e.g. `signup_form`). First-touch only; never overwritten on subsequent calls.
`metadata`	object	no	Arbitrary key/value pairs passed through as additional context for the engine.

POST /v1/actors is idempotent on the email field, scoped to your organization. Posting an email that already exists in your organization returns the original actor instead of creating a new one. The response status is 200 instead of 201, and the body's status is already_exists. If you submit different fields (such as a new name or metadata) for an email that already exists, the existing actor is returned and the submitted fields are ignored. GET requests are naturally safe to retry.

Lifecycle

Every actor moves through four states, exposed as the status field on getActor.

Status	Meaning
`pending`	Actor row written; enrichment job not yet picked up.
`enriching`	A worker is running the engine against this actor.
`enriched`	Terminal success state. `enrichment` and `intelligence` are populated.
`failed`	Terminal failure state. Contact support with the actor id if needed.

See the engine for state-transition details.

Future inputs (not yet shipped)

The actor surface is designed to accept additional inputs (product events from PostHog, Segment, or a custom stream, and CRM records from HubSpot, Salesforce, or Attio) against the same resource. Those ingest paths ship in a future release.

Briefings. What the engine writes back.
API reference. The createActor operation page.

Shape

Resolution

Lifecycle

Future inputs (not yet shipped)

Next

On this page