Entity Bind and Python

1. 01

   One call, to see the shape

   Send at least one identifying field. Unknown fields are rejected rather than ignored, which is deliberate: a field dropped in silence is a wrong answer arriving in silence. client_ref takes up to 200 characters, comes back verbatim, and is how the response joins to your data on your own key.

   One call, to see the shape

   import os
   import httpx
   
   response = httpx.post(
       f"{os.environ['ENTITYBIND_BASE_URL']}/v1/resolve",
       headers={"Authorization": f"Bearer {os.environ['ENTITYBIND_API_KEY']}"},
       json={
           "name": "Acme Widgets Ltd",
           "domain": "acmewidgets.co.uk",
           "country": "GB",
           "depth": "research",
           "client_ref": "crm-4417",
       },
       timeout=60.0,
   )
   response.raise_for_status()
   result = response.json()

2. 02

   Branch on the outcome first

   A match below 0.90 confidence is unrepresentable. The record comes back as an abstention with a ranked shortlist instead. The rule lives in the model that carries the result rather than in a caller who could skip it. Enforced as a domain invariant on the resolution outcome and again by a predicate called on the online, batch and replay paths, so a sub-floor accepted match cannot be constructed on any of them. A cached replay whose inherited confidence has fallen below the floor is withheld rather than re-served. So an accepted match has already cleared the floor by the time you read it. Branch on whether the record resolved and treat every abstention as a work list. If your policy needs a stricter threshold, measure what it costs you in coverage on labelled records first. Confidence bounds depend on the recorded evidence population; there is no universal score for every match. Read match_confidence_basis and the evidence. A 0.99 filter can return some v8 adjudicated matches while excluding valid identifier matches, so validate its coverage cost on your own inputs.

   Branch on the outcome first

   if result["decision"] == "match":
       entity_id = result["entity_id"]
       decision_id = result["decision_id"]      # reopens the evidence trail
   else:
       # Not an error. A ranked shortlist, a typed reason, the column that
       # would have decided, and a review id — and it cost nothing.
       reason = result["reason_code"]
       shortlist = result["candidates"]
       prescription = result.get("prescription_fields")

3. 03

   Batch when you have more than a handful

   Up to 500 records a request, treated as an unordered set, with a repeated idempotency key recognised as the same request and one ledger row written per outcome. Batches run one at a time rather than queueing, so plan a large file as a window rather than as a rate. A byte-identical replay is free — per tenant, per exact content, with no expiry — so an interrupted job restarts without paying twice for the rows it already did.

4. 04

   Read the usage block rather than counting calls

   Every metered response carries a usage block, and the module that quotes the price in that block is the same module that writes the ledger row and serves the public pricing endpoint. The number in your response, the number in your usage export and the number you are charged cannot drift apart, so there is nothing to reconcile and no reason to keep a count of your own.

Python sits with Snowflake and Salesforce on the same shelf: nothing to install. If you are weighing a shipped integration against a pattern, the line between the two shelves is drawn on the hub.