Review account details from a conversation through the API

Analyze a bounded text sample, check for existing customer records and explicitly confirm an atomic account capture.

Account capture uses POST operations under /v1/organizations/me/communications/account-capture/. See API reference and the complete operation index for schemas. Web, Android and manual capture use the same contract. The former identity-resolution, preview and raw graph apply operations are removed.

Start, prepare and confirm

Start a private review with start/:

{"source":{"source_type":"text_conversation","source_id":"cconv_0123456789abcdef"},"identity":{"identity_kind":"phone","identity_value":"+16135550123"},"action":"create_account"}

A representative response includes:

{"uid":"acdraft_0123456789abcdef","revision":1,"status":"draft","origin":"manual","expires_at":"2026-10-07T12:00:00Z","data":{"action":"create_account","account_display_name":"","people":[],"locations":[]},"capabilities":{"ai":true},"confirmation":null,"operations":[],"issues":[]}

Responses also contain the complete editable data, duplicate matches and per-operation capabilities. Preserve the returned data when editing. Starting again resumes the actor's unexpired draft for the same source.

1. Send session_uid and revision to analyze/. Only direct text conversations support AI. Read review.attempt_status separately from review.status: an additional failed attempt can retain a ready first result.
2. Poll review/ with session_uid while processing. messages/ accepts an optional before_uid cursor or up to 40 message_uids from this conversation. A second analyze/ accepts either earlier_messages: true or selected message_uids. Additional suggestions remain separate for explicit acceptance.
3. Send session_uid, revision and edited data to prepare/. The server returns normalized data, a new revision, exact operations, scoped duplicate matches and blocking issues. A confirmation is issued only for a valid plan. Editing invalidates the client's previous confirmation immediately.
4. Show the operations to the person and wait for explicit confirmation. Send only these fields to apply/, with an Idempotency-Key:

{"session_uid":"acdraft_0123456789abcdef","revision":4,"confirmation":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}

A successful response includes the account, contacts, locations and linked conversation with opaque references. Repeat the exact command and key after an uncertain network result. A changed draft, source, permission or saved record requires another preparation. Raw CRM fields are rejected by apply/.

Send discard/ with session_uid to abandon a draft. Drafts expire after 24 hours. All responses are private and uncached.

Access and audit

AI needs organization AI enabled, org.communications.ai.account_capture.enabled, SMS and accounts entitlements, plus .use, .read and .apply permissions under communications.account_capture. Daily usage uses org.communications.ai.account_capture.requests.daily.max and the shared governor. Manual capture remains subject to source and CRM access.

Each chosen create or update requires its exact CRM permission, record scope and entitlement. Custom fields use their own policies. Explicit main-contact, relationship and primary-method changes require update permissions. Strong account/contact matches require reuse or communications.account_capture.duplicates.override, the current matched UIDs and a reason. Shared names or addresses alone never authorize merging.

CRM changes, linking, audit, durable follow-ups and the idempotent result commit atomically. Audit includes actor, source/session references, revisions, decisions, model/prompt version, bounded source references, field provenance, explicit changes and created/reused records. Raw prompts and message bodies are excluded. Disabling AI invalidates derived reviews, including requests still in flight.

Bounds

Each of at most two samples contains up to 40 messages and 12,000 UTF-8 bytes of message content; full input is capped at 24,000 bytes and output at 4,000 tokens. Three paid attempts are allowed. Holds and deferrals preserve the attempt allowance. Each save supports 10 people and 10 addresses. Attachments and conversation-wide uploads are excluded.

Resume an addressed review

A review drawer stores only its session_uid in the page path. The existing review/ read returns source and identity alongside the review data so the client can restore the correct conversation context. Ownership, expiry, source access and AI access checks still apply. Reopening the drawer reads that private session; it does not analyze again, confirm changes or create customer records.