Get access

Get started · 3 / 42

Quickstart

Prove one caller-memory lifecycle: recall before the interaction, submit the completed call, then verify with a later controlled recall that the call appears. The 204 confirms a durable write; a later recall normally returns it but may lag.

Complete one Northsun caller-memory lifecycle against the frozen public REST contract: recall context before an interaction, submit the completed interaction, and verify with a later controlled recall that it appears.

1. Recall before the interaction

Use a controlled test phone number. The route creates a caller record on a miss and returns caller memory plus any enrichment that completed within the request deadline.

curl -sS -X POST https://mcp.northsun.ai/v1/recall_and_enrich \
  -H "Authorization: Bearer $NORTHSUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15551234567",
    "trigger": "answered",
    "session_id": "call_demo_01"
  }'

Inspect these fields:

  • known: whether the caller record existed before this request;
  • caller: profile fields and call count;
  • memory: summary and recent processed calls;
  • enrichment: nullable person, company, and phone blocks;
  • trace_id: correlation value for this recall;
  • timing_ms: measurements for this request, not a published benchmark;
  • degraded: present and true when an authenticated caller-memory read returned the safe degraded shape.

Do not block the conversation on a missing enrichment block, and do not treat enrichment as identity verification.

2. Submit the completed interaction

Reuse the session ID and send the normalized transcript after hangup:

curl -i -sS -X POST https://mcp.northsun.ai/v1/calls/end \
  -H "Authorization: Bearer $NORTHSUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15551234567",
    "session_id": "call_demo_01",
    "transcript": [
      {
        "role": "user",
        "text": "Please call me Tuesday morning.",
        "ts_ms": 0
      },
      {
        "role": "agent",
        "text": "I will record that callback request.",
        "ts_ms": 2400
      }
    ],
    "duration_s": 18,
    "outcome": "callback_requested"
  }'

A successful request returns 204 No Content, which confirms the interaction is committed durably. A later recall normally returns it but may lag. See Hangup, and what happens next for what the 204 confirms and what it does not cover, enrichment included.

3. Verify the write-back

Repeat the recall with a new session ID:

curl -sS -X POST https://mcp.northsun.ai/v1/recall_and_enrich \
  -H "Authorization: Bearer $NORTHSUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+15551234567",
    "trigger": "answered",
    "session_id": "call_demo_02"
  }'

Verify the unique callback request appears in memory.summary or memory.recent_calls. The call normally appears, but a recall can lag, so repeat the recall after a short, bounded interval before treating its absence as a failure. If it still does not, retain both trace IDs, the UTC timestamps, and the redacted session IDs. Follow Troubleshooting instead of creating an unbounded retry loop.

What this proves

When all three steps succeed and the later recall contains the controlled observation, you have proved:

  • API-key authentication and tenant scope for the test key;
  • request/response mapping for the frozen caller endpoints;
  • partial-enrichment handling;
  • that the durable write from calls/end is visible to a later controlled recall for that lifecycle.

It does not prove a vendor-platform mapping, a latency percentile, proactive Beacon behavior, or another tenant's configuration.

Next steps