Customers & Identification

Overview

You resolve a customer with GET /customers/lookup: pass a phone or a POS customer id, get back one at-a-glance projection. The single rule that shapes everything on this page: a stranger is not an error. All four identity states resolve to HTTP 200 with a status field, never a 404, so your point-of-sale can render a "register this customer" call-to-action instead of routing a normal lookup through an error path.

This is the most-leveraged read in the surface. You hit it at the start of nearly every order, before basket, before offers, before payment.

The 4-state cashier-panel model

GET /customers/lookup returns one of four identity states. You branch your panel UI on data.status. The state, not the HTTP code, is the business answer.

A fifth case folds into the third on purpose. A disabled identity (an operator-shut-off record) surfaces as not_found: no PII, no register affordance for a deliberately disabled flow.

Why a cross-enterprise customer is also not_found

Tenant isolation is structural. Every lookup query scopes to the enterprise resolved from the verified POS-terminal JWT, never from request input. The same phone at a different enterprise resolves a different row set, so a cross-enterprise read is impossible: it surfaces as not_found (HTTP 200), not a 403. A 403 is reserved for a token that is not authorized for the merchant or branch scope it claims.

Look up a customer

GET /customers/lookup is Beta: callable today, shape may still tighten. Authenticate with a POS-terminal JWT. Pass at least one of phone or provider_customer_id.

curl -G https://api.feddi.io/v1/partner/customers/lookup \
  -H "Authorization: Bearer $TERMINAL_JWT" \
  --data-urlencode "phone=+97433001122"

{
  "ok": true,
  "data": {
    "status": "registered",
    "customer": {
      "name": "Layla Hassan",
      "phone": "+97433001122",
      "state": "VERIFIED",
      "member_since": "2025-11-02T08:14:00Z",
      "balance": {
        "spendable_minor": 12500,
        "locked_promo_minor": 0,
        "currency": "QAR"
      },
      "activity": {
        "lifetime_spend_minor": 184000,
        "visit_count": 27,
        "visit_count_last_90d": 9,
        "last_visit_at": "2026-06-01T19:42:00Z"
      },
      "badge": "vip"
    },
    "unclaimed_cashback": null,
    "branch_id": "22222222-2222-2222-2222-222222222222",
    "fetched_at": "2026-06-05T09:10:00Z"
  },
  "error": null,
  "meta": {
    "request_id": "req_lk1",
    "idempotency_replayed": false,
    "api_version": "2026-06-01",
    "data_completeness_score": 80
  }
}

The projection

The lookup returns identity, both money classes, lifetime activity, and a badge in one payload.

This read merely surfaces a proto-wallet. It never credits, releases, or moves money. PENDING_PROOF gates every money side-effect elsewhere; lookup is read-only.

Identity resolution is one resource, not this one

There is no standalone POST /customers/identify. Identity resolution is deliberately a single resource in the contract, and it lives elsewhere. The folded path exists in the spec only so an integrator who searches for /customers/identify finds the redirect.

Use one of these instead:

Both return a CustomerContext and never a debit or authorize token. Identity and money are strictly separated: resolving who the customer is never grants the right to move their balance. That invariant is covered in Identity & Credentials.

Operations in this domain

Availability is per-operation and load-bearing. Build against Beta today. Everything marked Planned is shape-frozen but not yet mounted, and Preview is reserved pending a founder and legal call. The authoritative, live list of mounted routes is always GET /capabilities and GET /openapi, never this page alone.

Non-purchase signals (Planned)

POST /customers/{phone}/events records a check-in, a survey response, a loyalty-card scan, or a feedback submission so the Brain captures the full interaction graph, not just transactions. This is the counterfactual surface for the customer domain: the things a customer does that are not a purchase.

The event is idempotent on the Idempotency-Key header, so a retried report replays the original recorded event and never double-logs.

{
  "event_type": "check_in",
  "attributes": {
    "source": "loyalty_card_scan",
    "note": "Walked in, browsed, did not buy"
  }
}

An unknown event_type is a VALIDATION_ERROR that lists the supported set. The event publishes to the domain-event bus only after the write commits. This operation is Planned: wire it, but treat it as not-callable until it flips.

Correcting and merging identity (Planned)

PATCH /customers/{customerId} corrects a mistyped name or phone. A phone correction re-triggers verification: the record returns to (or stays in) PENDING_PROOF and a fresh verification link is sent to the new number. A typo'd proto-wallet that accrued a LOCKED grant keeps its claimable promo, which follows the corrected identity, so it is never lost. A name-only correction does not re-verify.

Because a phone change moves the (enterprise, normalized_phone) identity key, the new number must not already resolve to a different existing customer. If it does, you get a VALIDATION_ERROR, and you use the merge resource for a genuine duplicate. This operation is Planned.

Data subject rights: export and erasure (Preview)

The GDPR/PDPL surface is Preview: the request and response shapes are stable, but whether these ship day-one or in v1.5 is an open founder and legal call. The shape will not shift under you, so you can wire against it now.

{
  "customer_id": "usr_5512",
  "outcome": "anonymized",
  "prior_state": "VERIFIED",
  "transactions_retained": true,
  "pii_scrubbed": true,
  "erased_at": "2026-06-05T09:20:00Z"
}

Where to go next