ackDB

Create a person by hand

The split-runbook primitive: when two humans were fused onto one person (a shared inbox, a bad key), delete the offending key, create the second human here, then re-point their edge with PATCH /contacts/{contactId} { personId }.

Key types must be person-scope (linkedin_url, email_address, or a universal type registered with scope: person). Values are normalized (lowercased email / canonical LinkedIn) and validated: blank or null-sentinel values and role inboxes (info@, sales@, …) are 422 — a mailbox is not a human. A key already owned by another person is 409 naming the owner: keys are first-writer-wins and are never re-pointed.

Email is a fallback anchor (#575). If the submitted keys include BOTH a linkedin_url and an email_address, the email key is DROPPED at mint (the person is anchored by linkedin; the email would be a recyclable global pointer). The response then carries a suppressed: { keyType, values, stored: false, reason } block — this door has no contact edge, so a dropped email is not stored anywhere. An email-ONLY create still keeps the email as its sole anchor.

No creation event is emitted (a person mint is bookkeeping, like an ingest-auto-created company); an audit log is written instead.

post/api/v1/ackdb/persons

Request

  • Base URL
    http://localhost:3009
  • Auth
    HTTP bearer

Request body

namestring nullable
avatarUrlstring nullable

Photo URL (http(s) only). ackDB stores the link, never the bytes.

Example request

{
  "name": "Elly Chen",
  "avatarUrl": "https://media.licdn.com/dms/image/v2/abc/profile.jpg",
  "keys": [
    {
      "externalIdType": "email_address",
      "externalIdValue": "elly@newco.com"
    }
  ]
}

Response

{ data: { person, keys } } — the new person and its stored (normalized) keys.

dataunknown required

Changes

No recorded changes to this operation across all 1 revision of this API.