Signals API quickstart

If you are deciding between manual import, a connector, and the API, start with Import evidence into Discovery. If you already know you want the API, this page shows the smallest working path:

• create one signal
• let Zentrik queue processing automatically
• confirm the signal appears in Discovery
• move to the production template when you are ready for batching or pagination

Before you send a request, prepare:

• a workspace API key from Settings → API Keys
• your workspace base URL including /api
• one real record to send, usually as a transcript, support ticket, review, or discovery report

For a product-level first test, use manual import in Discovery before automating anything.

Start with one transcript. This example creates a signal and waits for processing to finish.

#!/usr/bin/env python3
import json
import os
import time
import urllib.request

payload = {
    "name": "Advisor onboarding call",
    "signalType": "transcript",
    "text": "Customer interview transcript goes here.",
    "additionalContext": "Imported from an onboarding call.",
    "sourceLinks": [
        {
            "name": "Open source call",
            "url": "https://meetings.example.com/calls/advisor-onboarding-call",
            "type": "transcript",
            "primary": True,
        }
    ],
}

def request_json(method, path, body=None):
    request = urllib.request.Request(
        f"{os.environ['ZENTRIK_API_BASE'].rstrip('/')}{path}",
        data=json.dumps(body).encode("utf-8") if body is not None else None,
        method=method,
        headers={
            "Authorization": f"Bearer {os.environ['ZENTRIK_API_KEY']}",
            "Content-Type": "application/json",
            "Accept": "application/json",
        },
    )
    with urllib.request.urlopen(request, timeout=60) as response:
        raw = response.read().decode("utf-8")
        return response.status, json.loads(raw) if raw else None

code, created = request_json("POST", "/external/v1/signals", payload)
public_id = created["publicId"]
print(f"Created {public_id} jobId={created['jobId']}")

for _ in range(36):
    code, signal = request_json("GET", f"/external/v1/signals/{public_id}")
    print(f"{public_id} status={signal.get('status')} insights={len(signal.get('insightIds') or [])}")
    if signal.get("status") in {"processed", "failed"}:
        print(json.dumps(signal, indent=2))
        break
    time.sleep(5)

Expected result:

• the create response returns a publicId and jobId
• the signal moves from processing to processed
• the signal appears in Discovery with linked insights when processing succeeds
• the source link appears on Signal and insight evidence surfaces so reviewers can open the original record

Use the signal type that matches the source material:

• transcript for interviews, onboarding calls, sales calls, and meeting notes with direct user evidence
• support_ticket for support cases, ticket exports, or issue threads
• review for public reviews, app-store reviews, or shorter rating-backed comments
• feedback_record for survey rows, NPS verbatims, CSV feedback, or form responses
• discovery_report for synthesized research notes or analyst writeups

If you are unsure, start with the source that is closest to the original customer wording instead of a summarized derivative.

Whenever the source has a stable final URL, include sourceLinks. Use the primary link for the place a reviewer should land first: the exact review, ticket, Reddit comment, report, meeting, source row, or source-system record. Omit sourceLinks only when the provider has no durable user-facing URL.

For recurring imports, also send a stable sourceKey + externalId, source-date occurredAt, and canonical source fields (providerType, evidenceKind, analysisProfile) so filtering, source labels, and processing remain predictable as volume grows.

The create endpoint queues processing automatically. You do not need to call a second endpoint for the first run.

The main fields to watch are:

• status
• insightIds
• processing.lastJobId
• processing.processedAt
• processing.lastError

Use the explicit process endpoint only when you want to rerun an existing signal.

Participant handling is opt-in so existing clients keep the same behavior.

• Omit participantPolicy or use none to create only the Signal.
• Use match_existing to link one exact existing Person without creating records.
• Use create_missing to match or create reliably identified People. Mark colleagues as internal and uncertain relationships as unknown. With this explicit policy, an omitted affiliation is treated as non-internal and can create a Person.
• Set createMissingAccounts only when Zentrik may also create an Account from one unambiguous professional email domain. It defaults to false.

{
  "sourceKey": "crm.call",
  "externalId": "call-2026-08-24-001",
  "name": "Onboarding interview",
  "signalType": "transcript",
  "text": "Customer interview transcript goes here.",
  "participants": [
    {
      "email": "mira@northwind.example",
      "name": "Mira Chen",
      "role": "Operations lead",
      "affiliation": "external"
    }
  ],
  "participantPolicy": "create_missing",
  "createMissingAccounts": false
}

The response returns resolved contactIds and accountIds. Public email domains can create an unassigned Person under create_missing, but never an Account. See People and Accounts for the matching rules.

When the Hello World flow works, move to one of these:

• Signals import template for batching, retries, polling, and richer payload mapping
• Signals API reference for the full endpoint contract
• Import evidence into Discovery if you need the product-level decision guide