Changelog

​

GET /account/credits: per-top-up breakdown with credit_topups

• type: how the top-up entered your account — purchase (one-time purchase), auto_topup (automatic reload), or granted (added by Crustdata).
• granted_credits / remaining_credits: what the top-up originally added and what’s still unspent.
• granted_at / expires_at: when it was added and when its unspent credits expire (expires_at is null for top-ups without an expiry).

​

Company Search: filter by any office location with locations.all_office_addresses

• Substring match: office addresses are free-text strings (e.g. "HITEC City, Madhapur, Hyderabad, Telangana, 500081, IN"), so filter with a city or region substring using (.) / contains.
• Combines with HQ filters: pair it with locations.country in an and group to express queries like headquartered in the USA with an office in Hyderabad: locations.country = "USA" and locations.all_office_addresses (.) "Hyderabad".
• Not sortable: the field is filterable and returned, but not valid in sorts. See Locations in the search reference.

​

is_null and is_not_null filter operators on Person Search

• is_null — matches profiles where the field has no value. On nested-array fields the check is element-based: an empty experience.employment_details.current array matches experience.employment_details.current.name is_null.
• is_not_null — matches profiles where at least one non-null value is present for the field.
• value is required — send a literal "value": null; omitting the value key returns 400.

​

Every API response now reports what it cost: the X-Credits-Used header

• Exact decimal — 0.03 for a one-result person search, 3 for a three-company enrich. Fractional costs report exactly.
• Present on error responses too — errors report 0, so the header is there on every call you log.
• 0 is meaningful — endpoints that consume no credits report 0, and so do asynchronous submissions (batch jobs and background-job searches), which are billed when the job runs rather than at submit time.
• Readable from browsers — the header is exposed cross-origin, so dashboard-style apps can read it from JavaScript.
• Declared in the specs — every response in the OpenAPI specs documents the header.

​

Job Search: company job-board postings, job_details.source, and job_details.employment_type

• job_details.source — the platform each posting comes from. Present on every job: professional_network for the existing listings, or one of the job-board platforms — workday, smartrecruiters, greenhouse, workable, lever, icims, ashby, rippling, yc. Filterable (=, in, …) and groupable via group_by; not sortable. See the Job details catalog.
• job_details.employment_type — the employment type declared by the posting: full_time, part_time, contract, intern, or temporary. Currently populated for roughly 85% of job-board postings and null for now when source is professional_network. Filterable and groupable; not sortable.
• Search-only — both fields are returned by POST /job/search only; Live Search does not include them.

​

Company Search: geo_distance and geo_exclude on company headquarters

• geo_distance — returns companies headquartered inside the radius.
• geo_exclude — the inverse of geo_distance. It returns companies headquartered outside the radius and excludes the ones inside it, so you can skip a region you already cover. See the geographic radius filters reference.
• Setting the point and the distance — the point is what the radius is measured from. Pass it as location (a place name, geocoded server-side) or as lat_lng ([lat, lng], which skips geocoding), then add a distance and a unit such as km or mi.
• One field path — apply both operators to locations.headquarters, which targets the company’s geocoded headquarters point.
• Normalized location facets — locations.state and locations.city are newly filterable and match normalized values derived from geocoding the headquarters address, with search responses returning the same normalized values. locations.country accepts both ISO-3 codes ("USA") and full country names ("United States") — either form matches the same companies, so existing filters keep working — and responses return the normalized full country name. See Locations.

​

Auto top-up: refill credits automatically before the balance runs out

• Turn it on from the Credits page — save a card through a Stripe-hosted page and accept the auto-charge consent, then set two numbers: a threshold and a reload amount. Enabling requires a balance above the threshold you pick, so buy credits manually once if you are already below it. Turning it off is one click, any time.
• What a top-up does — the saved card is charged at the price shown during setup, the live balance refreshes right away, and you get a receipt email plus a real Stripe invoice in the Invoices tab, identical to a manual purchase.
• Monthly recharge limit — an optional cap on how many credits auto top-up can add per calendar month. It resets each calendar month.
• Safety rails — at most 3 auto top-ups per day per account, and double-charge protection means one threshold breach can only ever produce one charge.
• Failed charges — a declined or expired card gets an email with the reason and the fix, Crustdata retries after a cooldown, and after 3 consecutive failures auto top-up disables itself and says so. Cards nearing expiry get a warning email before they lapse.
• Thresholds and reload size — the threshold is an absolute credit balance, and the minimum reload is 500 credits. The exact price is shown before you save.
• Pricing — the feature is free, with no credit cost and no plan gate. Each top-up buys the selected credit package at the standard self-serve rate — the same volume-tiered pricing as a manual purchase.
• Coming next — negotiated per-account rates applied to auto top-ups. Every top-up charges the standard self-serve rate today.

​

Person Search: match conditions across different entries in a profile

• all_of — a composite operator whose conditions are each matched independently, by their own array entry. Use it for compound cross-entry queries, like a role at one company and a degree from another school, or a past job plus a current one. See the operator reference.
• has_all — shorthand for one field with several values (“worked at both A and B”). It expands to one all_of block per value.
• Works across person history — employment, education, certifications, and honors.
• Combines with document-level filters — nest all_of inside a plain and to add profile-level conditions, so you can ask for a role at a company and a person based in a given country in one query.
• One matching entry per condition — each condition is satisfied by at least one entry in the array. Conditions do not have to land on the same entry, and they do not have to cover every entry.
• Backward compatible — a plain and on one array path still matches within a single entry, so existing queries return exactly what they returned before.
• Pricing — included on all plans. These are new operators on an existing endpoint, so there is no new credit cost and the /person/search rate limit is unchanged.

​

Job Search: geo_distance and geo_exclude on job location

• geo_distance — returns job postings whose location falls inside the radius.
• geo_exclude — the inverse of geo_distance. It returns job postings whose location falls outside the radius and excludes the ones inside it, so you can skip a region you already cover. See the geographic radius filters reference.
• Setting the point and the distance — the point is what the radius is measured from. Pass it as location (a place name, geocoded server-side) or as lat_lng ([lat, lng], which skips geocoding), then add a distance and a unit such as km or mi.
• Either field path — use location.raw or location; both target the same geo point.
• Geocoded on ingest — each posting’s location text is turned into real coordinates when Crustdata adds the posting to the database, so the filter compares coordinates rather than matching location strings, and postings in towns you never thought to list still come back.
• Pricing — no new credit cost. A radius query bills the same as any other /job/search call, and the endpoint’s rate limit is unchanged.

​

Teams: one workspace with shared credits, API keys, and roles

• Every account became a team - your existing account is now a team named Personal with you as the owner. Nothing changes until you invite someone.
• Invite by role - Owner (the creator; bypasses every permission check and cannot be reassigned), Admin (invites members, buys credits, manages payment methods, and creates and manages API keys, watchers, and integrations), and Member (runs playground searches and enrichments against team credits and views usage, keys, watchers, exports, and billing, but cannot purchase, manage keys, or change the team).
• Shared credits and API keys - everyone on a team draws from one credit pool and one set of cd_ keys, gated by role. Rate limits are shared across the team.
• Team switcher - one person can belong to and create several teams and switch between them from the sidebar. Credits never move between teams: each team buys and holds its own, which is a clean way to cap spend for a project, client, or department.
• Per-team billing - each team has its own wallet, subscription, invoices, and saved cards. A new team starts at 0 credits and buys its own.
• Default limits - up to 2 teams per user and 10 members per team. Reach out to sales to raise either limit.

​

Per-API-key limits: cap credits and restrict endpoints on one key

• Monthly credit cap — cap how many account credits one key can spend per month; it resets on the 1st (UTC). Use it for a key you hand to a teammate, a customer, or an unattended job. When the cap is reached, that key returns 402 with error.type insufficient_credits. Setting the cap to 0 stops the key until an admin raises it. See Per-key monthly limit.
• Endpoint access — restrict a key to a subset of the endpoints the account has enabled. A call to an endpoint outside that subset returns 403 with error.type permission_error. See Per-key endpoint access.

​

Usage and logs: see and filter activity by API key

• Per-key attribution — every request is tagged with the key that made it, including requests from keys you have since deleted, so past activity stays attributed after a key is rotated out.
• Filter by key — narrow the Usage and Logs views to one or more keys to see exactly what each key spends and calls. Together with per-key credit caps and endpoint access, you can set a key’s limits and then confirm what it actually did.

​

Technographics: filter by and enrich a company’s technology stack

• technographics field group on Enrich — request it explicitly via fields (it is never included by default) to get total_technologies, top_technologies, the full technologies list (each entry with name, detection sources, posting_count, catalog categories, a description, and evidence), and updated_at. See the field reference.
• Search filters — filter on technographics.total_technologies (also sortable), technographics.top_technologies, technographics.technologies.name, technographics.technologies.category, and technographics.technologies.super_category. Technographics values are not returned in search responses — filter, then enrich. See searchable fields.
• Autocomplete — two new company-scope fields: technology (technology names) and technology_category (category slugs) for discovering valid filter values.
• Access and pricing — technographics requires field-level permission on your account. It is a billed add-on: +2 credits per company that returns technographics data, on top of the base enrich cost; companies with no technographics data are not charged the add-on. The same add-on applies to Batch Company Enrich.

​

Company lookup: more accurate domain matching for large organizations

• Better matches for large organizations - a domain maps to the parent company rather than a subsidiary, an acquired company, or a showcase page. For example, amazon.com resolves to Amazon, paypal.com to PayPal, and schwab.com to Charles Schwab.
• Nothing to change - same endpoints, same request shape, and same response shape. No new fields and no confidence score to handle; matches just get better automatically.
• Biggest gains on high-volume domains - in testing across Fortune 500 US companies, top-1 accuracy by domain rose from 88% to 94%.

​

Person Search: natural-language search.query (beta)

• search.query - describe who you want in plain language; results are ranked by profile context (title, skills, company history, education, location, summary).
• search.mode - hybrid (default, blends keyword and concept matching) and semantic (concepts). For exact keyword matching, see the keyword search changelog below.
• mode - two recall modes: managed (default; the query may add constraints) and exact (your filters are hard constraints and the query only ranks within them).
• fit - each profile returns a relevance tier (strong / possible / weak) alongside total_count_relation, so you can keep only high-confidence matches.
• Not included - sorts; semantic results come back already rank-ordered by relevance.
• Pricing - Person Search parity at 0.03 credits per result, no premium for semantic ranking, and the same 30 requests/minute rate limit.

​

Person Search: keyword search with Boolean operators

• search.mode: "lexical" - keyword matching across the whole profile, for when you want exact terms to be found rather than concept ranking.
• search.query_syntax: "boolean" - read the query as a Boolean expression instead of plain text: a space means AND (every term required), | means OR, and you can combine terms for precise keyword search. Honored only with search.mode: "lexical" and top-level mode: "exact".

​

Multiple API keys on one account

• Create and name keys - add as many keys as you need at app.crustdata.com/api-keys, rename them anytime, and copy the generated cd_ key into any API or MCP request. See Authentication.
• Per-key status - ACTIVE (usable across the API and MCP), INACTIVE (blocked instantly and reversible), and DELETED (permanently retired; the account’s other keys keep working).
• Shared credits and rate limit - all keys on an account draw from one credit pool and one rate-limit bucket today, so keys separate and organize work rather than cap spend or speed per key.
• Coming next - credit balance and limits set at the individual API-key level.

​

Person Contact Enrich: business emails, personal emails, and phone numbers

• Identifiers — pass exactly one of professional_network_profile_urls (a profile URL) or business_emails to reverse-look-up a person, up to 25 values per request.
• fields — select which contact data to return: contact.business_emails, contact.personal_emails, contact.phone_numbers, and contact.websites (or contact for all). Each email entry includes its deliverability status. See the contact fields reference.
• Response — the same record shape as /person/enrich, restricted to the person_data.contact object. For higher fill rate on bulk lists, use the async Batch Contact Enrich job instead.

​

Person Search: geo_exclude filter operator

• geo_exclude takes the same value object as geo_distance: a centre given as location (geocoded server-side) or lat_lng ([lat, lng], skips geocoding), a required distance, and an optional unit (km, mi, miles, m, meters, ft, feet; defaults to km). When both location and lat_lng are supplied, lat_lng wins. See the operator reference and a worked example.

​

Professional-network name and normalized title on Person profiles

• basic_profile.professional_network_name — the display name on the person’s professional-network profile, returned by both /person/search and /person/enrich. On search it is also a filterable field (not sortable). See the search field reference and the enrich response reference.
• basic_profile.normalized_title — the normalized job-title object (matched_title, department, sub_department, similarity, confident) is now also returned by /person/enrich, matching the field already available on /person/search.

​

Normalized titles, education details, and logos on Person Search

• basic_profile.normalized_title — an object with matched_title, department, sub_department, similarity, and confident. Filter on basic_profile.normalized_title.matched_title, .department, or .sub_department (filterable, not sortable). See the field reference.
• Education location and description — each education.schools[] entry now returns a location object (raw, city, state, country, continent) and a description. The location sub-fields are filterable via education.schools.location.*. See the education fields.
• education.schools[].institute_logo_permalink — a stable Crustdata-hosted school logo URL, returned for display.
• experience.employment_details[].company_profile_picture_permalink — a stable Crustdata-hosted employer logo URL, so you can render company logos without resolving image URLs yourself. See the profile-card example.

​

Follower count on Person Search profiles

• professional_network.followers — integer follower count from the profile. Filterable and sortable: pass it in filters.conditions[].field or sorts[].field. See the filter and sort field reference.

​

Person Search: new filter operators

• (!) — fuzzy negation. Excludes profiles whose value contains the given substring (case-insensitive). Multi-word values are matched as a literal phrase, so (!) "New York" excludes profiles literally containing "New York" but not "New Yorker". To exclude on each word independently, send separate (!) conditions inside an and group. See the operator reference and a worked example.
• geo_distance accepts lat_lng. Supply explicit coordinates as [lat, lng] to skip geocoding. When both location and lat_lng are provided, lat_lng wins. See the geo_distance reference and the lat_lng example.

​

🚀 New API version: 2025-11-01

​

What’s new

• Versioned endpoints. Every call requires the x-api-version: 2025-11-01 header, so future changes ship without breaking existing integrations.
• Bearer authentication. Authorization: Bearer <key> replaces the legacy Token scheme across every endpoint.
• Structured error envelope. A consistent { error: { type, message, metadata } } shape across every endpoint.
• Cursor-based pagination. Opaque next_cursor replaces numeric offset on search endpoints.
• Match-result envelope for enrich. Enrich responses now return matches[] with a confidence_score per match.
• Nested, neutral response sections. Flat top-level keys are grouped under sections like basic_info, employee_reviews, and funding.

​

Migrating from the legacy API