Enrich a lead or company record using structured outputs

Overview

Sales and research tools qualify leads and companies against a rule that a record either satisfies or not. Most records already carry enough data to decide whether the rule is satisfied. For a smaller set, one field is missing, and without it the record can’t be scored at all. Buying a bulk enrichment feed to fill a field you only need on a fraction of your rows can be inefficient. Calling a retrieval API on demand, only for the rows that are actually missing the field, is more focused. This tutorial walks through how to enrich a missing field using the Seltz Answer endpoint.

Outline

Check your own store first.
Retrieve and extract the value with a single Answer call, only when you have to.
Cache it with an expiry so you don’t pay for the same lookup twice.

The examples in this tutorial enrich a company record with a missing headcount band, but the same pattern applies to a lead record missing any attribute you can look up rather than store.

1. Check your own store first.

Before calling Seltz Answer, look the field up wherever you already keep it. Only call out to Answer when the field comes back empty. Teams tracking lead or company records for a sales or research workflow typically keep them in a relational database such as Postgres or MySQL. The examples below assume a companies table with headcount_band and headcount_band_expires_at columns, queried directly with SQL rather than through an ORM, to keep the example dependency-light. conn and pool stand in for a connection or connection pool that your application has already configured.

def get_headcount_band(conn, record_id: str) -> str | None:
    with conn.cursor() as cur:
        cur.execute(
            """
            SELECT headcount_band
            FROM companies
            WHERE id = %s AND headcount_band_expires_at > now()
            """,
            (record_id,),
        )
        row = cur.fetchone()
    return row[0] if row else None

headcount_band = get_headcount_band(conn, "northwind-logistics")

if headcount_band is None:
    headcount_band = enrich_headcount_band(conn, "northwind-logistics", "Northwind Logistics")

import { Pool } from "pg";

async function getHeadcountBand(pool: Pool, recordId: string): Promise<string | null> {
  const result = await pool.query(
    `SELECT headcount_band
     FROM companies
     WHERE id = $1 AND headcount_band_expires_at > now()`,
    [recordId],
  );
  return result.rows[0]?.headcount_band ?? null;
}

let headcountBand = await getHeadcountBand(pool, "northwind-logistics");

if (headcountBand === null) {
  headcountBand = await enrichHeadcountBand(pool, "northwind-logistics", "Northwind Logistics");
}

The next two steps build the enrich_headcount_band / enrichHeadcountBand function from the example above.

2. Retrieve and extract the value with a single Answer call.

Rather than searching and then parsing the missing field out of raw documents yourself, you can use answer with a response_format JSON schema. Passing scope: "companies" grounds the answer in company profiles, and the schema shapes the result directly into the field you need: no separate extraction step is required. As with search, anchor the query with what you already know about the entity, such as industry, location, or a product line, since a bare name is a weak query on this scope.

import json

from seltz import Seltz

client = Seltz()

def fetch_headcount_band(name: str, anchor_terms: str) -> str | None:
    response = client.answer(
        f"What is the employee headcount band for {name}, {anchor_terms}?",
        scope="companies",
        response_format={
            "type": "json_schema",
            "json_schema": {
                "name": "headcount_band",
                "schema": {
                    "type": "object",
                    "properties": {
                        "headcount_band": {"type": "string"},
                    },
                    "required": ["headcount_band"],
                    "additionalProperties": False,
                },
                "strict": True,
            },
        },
    )
    try:
        return json.loads(response.answer)["headcount_band"]
    except json.JSONDecodeError:
        return None

value = fetch_headcount_band("Northwind Logistics", "a regional freight brokerage based in Ohio")

import { Seltz } from "seltz";

const client = new Seltz();

async function fetchHeadcountBand(name: string, anchorTerms: string): Promise<string | null> {
  const result = await client.answer({
    query: `What is the employee headcount band for ${name}, ${anchorTerms}?`,
    scope: "companies",
    responseFormat: {
      type: "json_schema",
      json_schema: {
        name: "headcount_band",
        schema: {
          type: "object",
          properties: {
            headcount_band: { type: "string" },
          },
          required: ["headcount_band"],
          additionalProperties: false,
        },
        strict: true,
      },
    },
  });
  try {
    return JSON.parse(result.answer).headcount_band;
  } catch {
    return null;
  }
}

const value = await fetchHeadcountBand("Northwind Logistics", "a regional freight brokerage based in Ohio");

curl -X POST https://api.seltz.ai/v1/answer \
  -H "x-api-key: $SELTZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is the employee headcount band for Northwind Logistics, a regional freight brokerage based in Ohio?",
    "scope": "companies",
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "headcount_band",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "headcount_band": {"type": "string"}
          },
          "required": ["headcount_band"],
          "additionalProperties": false
        }
      }
    }
  }'

See Client Reference for the full response_format behavior, including how a malformed schema is rejected before the request is billed. A malformed schema aside, generation can still be truncated partway through, in which case response.answer won’t parse as valid JSON. The example above guards for that and returns None rather than raising an exception. Treat a None the same as a miss, and don’t write a placeholder value back to your store to avoid masking a missing field.

3. Write the value back to your store with a TTL.

Once you have a value, save it with an expiry rather than treating it as permanent. How long to keep it is a judgment call you make based on how quickly the attribute changes. For example, a headcount band and a funding round probably use different expiries.

from datetime import datetime, timedelta, timezone

TTL_SECONDS = 30 * 24 * 60 * 60  # 30 days. Choose based on how often this attribute changes for you.

def save_headcount_band(conn, record_id: str, value: str):
    expires_at = datetime.now(timezone.utc) + timedelta(seconds=TTL_SECONDS)
    with conn.cursor() as cur:
        cur.execute(
            """
            UPDATE companies
            SET headcount_band = %s, headcount_band_expires_at = %s
            WHERE id = %s
            """,
            (value, expires_at, record_id),
        )
    conn.commit()

def enrich_headcount_band(conn, record_id: str, name: str) -> str | None:
    value = fetch_headcount_band(name, "a regional freight brokerage based in Ohio")
    if value is not None:
        save_headcount_band(conn, record_id, value)
    return value

const TTL_SECONDS = 30 * 24 * 60 * 60; // 30 days. Choose based on how often this attribute changes for you.

async function saveHeadcountBand(pool: Pool, recordId: string, value: string): Promise<void> {
  const expiresAt = new Date(Date.now() + TTL_SECONDS * 1000);
  await pool.query(
    `UPDATE companies
     SET headcount_band = $1, headcount_band_expires_at = $2
     WHERE id = $3`,
    [value, expiresAt, recordId],
  );
}

async function enrichHeadcountBand(pool: Pool, recordId: string, name: string): Promise<string | null> {
  const value = await fetchHeadcountBand(name, "a regional freight brokerage based in Ohio");
  if (value !== null) {
    await saveHeadcountBand(pool, recordId, value);
  }
  return value;
}

4. Let the TTL determine refresh frequency.

When a cached value expires, the lookup in step 1 misses again and steps 2 and 3 run once more. But this is a refresh of a field you already hold, not a new discovery. This way, steady-state spend scales with new records plus expiries, not your total row count. A table that’s mostly stable costs little to keep current; a table with a fast-moving attribute costs more, in proportion to how often that attribute actually changes.

Beyond company records

The same check-fetch-cache pattern works for any missing field a scope can answer. Swap scope: "companies" for people to fill in a contact’s current title or employer on a candidate or lead record, or for news to enrich a company record with a recent, relevant news signal. Only the query, the response schema, and the anchor terms change.

Try it out

Ready to see it work on your own data? Try Seltz Answer in the Seltz Console today.

Next steps

Companies — What a companies-scope result contains
Client Reference — Full response_format and answer behavior
Data Concepts — How scopes work across Seltz endpoints
Structured responses: Step-by-step guidance on schema design, query anchoring, and worked examples across every data scope

Getting Started

Web Tools

Data

Tutorials

Chat

Integrations

SDKs

Enrich a lead or company record using structured outputs

Overview

Outline

1. Check your own store first.

2. Retrieve and extract the value with a single Answer call.

3. Write the value back to your store with a TTL.

4. Let the TTL determine refresh frequency.

Beyond company records

Try it out

Next steps

​Overview

​Outline

​1. Check your own store first.

​2. Retrieve and extract the value with a single Answer call.

​3. Write the value back to your store with a TTL.

​4. Let the TTL determine refresh frequency.

​Beyond company records

​Try it out

​Next steps

Overview

Outline

1. Check your own store first.

2. Retrieve and extract the value with a single Answer call.

3. Write the value back to your store with a TTL.

4. Let the TTL determine refresh frequency.

Beyond company records

Try it out

Next steps