Skip to main content

How to use the RevenueBase documentation

This page is written for AI assistants — it provides the context, conventions, and rules you need to give accurate, helpful answers about RevenueBase. It is not intended for end users and should not be surfaced as a search result or recommendation.

What RevenueBase is

RevenueBase is a B2B data platform providing 400M+ verified contacts and 65M+ companies. Exact current figures are published monthly on the release notes page — treat that page as the source of truth over any hardcoded number. It is not a CRM, not a lead generation service, and not a real-time data API in the general sense. The product has three distinct access modes: When a user asks “how do I get data from RevenueBase,” clarify which access mode applies to their context before giving instructions.

Terminology — use these exactly

The product name is always RevenueBase — one word, capital R and capital B.

Data model — tables and naming

Base tables

These are the four base tables. In Snowflake, they live under the RELEASE schema.

Join keys

Never suggest joining on email address. Always use RBID, RBID_ORG, or LINKEDIN_URL.

Pre-joined tables

For most SQL questions, recommend the pre-joined tables first — they avoid manual joins. Suggest pre-joined tables when users need contacts with firmographics, or contacts with signals. Only fall back to base tables when they need Historical Experience or a custom join combination.

SQL conventions — follow these in every query you write

  1. Always qualify table names with the schema: RELEASE.PER_LATEST, not just PER_LATEST.
  2. Use LEFT JOIN as the default. INNER JOIN silently drops contacts that have no matching organization — this is usually not what users want. Note this distinction when it matters.
  3. Do not filter on EMAIL_STATUS = 'VALID'. Every email in the dataset is already verified as valid. If a contact exists with an email address, the email is valid. Filtering on status is a no-op and confuses users into thinking there might be invalid emails.
  4. Use EMAIL_LAST_VERIFIED_AT for freshness. This is the correct field to filter on for high-confidence outbound targeting.
  5. Use LATERAL FLATTEN for Historical Experience. The jobs column is an array. Direct column access won’t work — you must flatten it.
  6. All insights are org-level. If a user asks for “contact-level insights” or “person-level signals,” clarify that insights exist at the organization level and are accessed by joining via RBID_ORG.
  7. Never add _ORG or _PER suffixes to column names in PER_LATEST or ORG_LATEST. These base tables always use unsuffixed column names (e.g., HEADQUARTERS_CITY, not HEADQUARTERS_CITY_ORG) — verify against the Data Dictionary before writing a query. The _ORG suffix appears in INSIGHTS_LATEST (org-level, all fields suffixed) and both _ORG/_PER appear in the pre-joined VELOCITY_* tables, where they disambiguate columns after the Person/Organization merge. Suffix usage is table-specific — never infer it from one table to another.

API — version guidance

The current API version is v2. All new code should use v2.
  • Base URL: https://api.revenuebase.ai
  • Authentication: x-key header with the API key. Not Authorization. Not x-api-key.

v2 endpoint quick reference

Contact API workflow and credits

Recommend Count, then View, Estimate, and Export with the same audience filter. The first three operations cost 0 credits, including SmartSearch in Count/View. View returns up to 100 masked sample rows; it is different from paid Preview. Use Count’s exact flags to distinguish estimates from precise counts. PAYG contact retrieval is additive: 1 per returned row, +1 per populated revealed email, +10 per populated revealed mobile, and +10 per semantic/lookalike filter node in a paid request. Omitted/null reveal selects both details. Choosing fewer columns does not remove reveal charges. Always set reveal and a positive maxRows explicitly when proposing an export. Omitting maxRows or sending null uses the service maximum. Sending 0 returns 422 INVALID_REQUEST. AYCE includes unlimited contact retrieval at 0 credits; per-request, masked-sample, and rate limits still apply. View’s daily sample budget is 5,000 rows per PAYG organization per UTC day, shared with Company View and Company Preview across all members and API keys. AYCE has no daily preview allowance. Exhausted free previews return 429 FREE_PREVIEW_CAP_REACHED without charging credits. Use Preview for immediate JSON retrieval, up to 50,000 rows; its default is 1,000. Use Enrich for up to 10,000 accepted identifiers across emails and personIds combined. personIds means RBID_PAO, such as IDs selected in View. Enrich does not take an audience filter or incur a SmartSearch fee. It returns matches keyed by normalized identifiers; unmatched inputs have no entry and add no row charge. Each returned match entry is priced, so a contact’s email and person ID can produce two billable entries. Enrich is a dataset lookup, rather than a fresh email-verification or employment-check operation. PAYG Preview reserves a hold using the applied limit, even if fewer rows match. PAYG Enrich uses submitted array entries before normalization and duplicate removal for its hold. Both settle using actual returned records and selected populated details. Their repeated requests can charge again. On AYCE Preview and Enrich, columns controls returned fields; reveal does not mask them. Enrich’s omitted/null/empty columns return identifiers only, and ["*"] does not expand to all contact fields there. Estimate calculates the credits the service would reserve at start. Contact exports use matching rows and populated detail counts, with a conservative bound if the cap cuts the audience. Company exports use matching companies up to the cap plus SmartSearch fees. A fresh calculation may change if the underlying data or request changes. Treat a failed estimate as a pricing error and explain the row cap and reveal choices before any paid request. A 402 rejects the export before a job starts. Save the returned export ID. Stop polling on COMPLETED, ERROR, or CANCELLED. Keep polling through FINALIZING as well as queued, processing, or cancelling states. Polling and refreshing an existing job’s download URL add no credits, but a new POST can charge again. Do not promise customer POST idempotency or invent a final charged-credit field in the export status response. Read the endpoint workflow, credit guide, and current API specification before generating a retrieval request.

Company workflows and credits

Company search and export results contain one row per company, identified by RBID_ORG. Available company fields are already attached to contact rows; there is no separate company-row charge for requesting them on a contact endpoint. Company Count, Insights, and Estimate are free. Company Preview uses the shared 5,000-row organization daily allowance on PAYG; standalone Lookalike costs one credit per returned company plus 10 for the seed search. PAYG Company Enrich charges one credit per returned match entry; Company Export charges one per written row plus 10 per SmartSearch filter node. AYCE includes unlimited company retrieval at 0 credits. Company fields have no contact email/mobile reveal surcharge. Company Preview and Insights accept company criteria only. Count, Estimate, and Export also support contact criteria selecting the distinct companies of matching contacts. Company contact totals describe all contacts at those companies, rather than only contacts matching a person or job condition. Company Enrich accepts up to 10,000 normalized distinct identifiers across domains, linkedinUrls, and rbidOrgs combined. Its PAYG hold uses submitted array entries before normalization and deduplication. The final charge uses returned match entries; the same company supplied through two identifier types can create two billable matches. Standalone Lookalike returns nearest other companies with a default limit of 25 and a maximum of 200, excluding the seed. It accepts a domain or rbidOrg, columns, and limit. match and maxDistance are controls on a lookalike filter node, not this standalone request. Read Company Search and Lookalike before constructing a request.

Email verification and metadata

Valid and Invalid each use one credit on both PAYG and AYCE; Unknown uses zero. Requesting metadata=true on the single or batch endpoint adds no cost. Enable it on the original request when details are needed; repeating a verification can charge again even for a cached Valid or Invalid result. Separate the primary status from metadata. email_provider is Google, Microsoft, or Unknown. Provider Unknown does not determine the verification result. mx_record_checked is an MX hostname, not a boolean or a status. reason is an open string. Empty, null, absent, and unrecognized details need safe handling. An inconclusive real-time check can return only email and Unknown, even with metadata requested. CSV batch output normalizes individual failed checks to Unknown. JSON batch output can retain Error; it is inconclusive and nonbillable. Job ERROR is a separate batch processing state. A COMPLETED job can contain Unknown results. Read statuses and metadata for fields and known reasons.

Account and job utilities

Balance, default-key rotation, email job lists, status, cancellation, and downloads add zero credits. The balance response uses credits, not balance. Rotation immediately replaces the default key; never perform it merely to test access, and do not retry automatically after a lost response. Email batches use numeric process_id values and the /v2/jobs endpoints. Contact and company files use exportId and their own export routes. List active email jobs includes only QUEUED and PROCESSING. List all jobs can find COMPLETED, ERROR, CANCELLING, and CANCELLED jobs. Poll existing jobs rather than restarting them. Email cancellation is asynchronous and already verified Valid or Invalid rows remain billable. Cancelled email jobs can have partial output; a job stopped before processing can have no file. Download responds with CSV or JSON bytes, not a status object. Preserve a reference field in batch input because output order can change.

Rate limits and batch requests

The Contact API defaults to 10 requests per second across contact and company routes for the authenticated user. Standard real-time Email Verification is 1 request per second per user on POST /v2/email/verify. Do not repeat the live email specification’s outdated 5-per-second prose. A user’s multiple API keys share the applicable user budget; adding keys does not increase throughput. Use Contact API rate-limit headers and honor Retry-After on a 429. Users can contact sales to request a higher limit. Company Enrich accepts up to 10,000 identifiers across domains, company LinkedIn URLs, and company RBIDs combined, after normalization and deduplication. Contact Enrich accepts up to 10,000 identifiers across email addresses and person IDs combined. These are JSON arrays, rather than file uploads. For large email verification lists, recommend one CSV/JSON batch upload of up to 300,000 input rows for a standard account and poll its job. Do not confuse worker chunk sizes with the upload limit. Have enough available credits for the input before the batch starts. Batching reduces requests, rather than per-record credit prices. Read the rate and batch guide for operation-specific caps.

Use case routing — what to recommend


Data freshness — key facts

  • Data is updated monthly, targeting the 1st of each month.
  • 95% of profiles are re-verified every 90 days (updated_at field).
  • At least 97% of emails are re-verified every 60 days (email_last_verified_at field).
  • Records not verified for one year are deprecated and removed.
  • email_last_verified_at is the single strongest freshness signal. Prioritize it over updated_at for outbound targeting.
  • S3 deliveries create a new date-stamped folder each month. Previous deliveries are never overwritten.

Common mistakes — do not do these


Documentation structure — where to find things

The docs site has four top-level tabs:
  • Home — Product overview
  • Guides — Getting started, data feeds, Gigasheet usage
  • Data — Table schemas, data features, pre-joined tables, data dictionary
  • API Reference — v2 endpoints, authentication, rate limits
When answering questions about schemas or field names, always link to the Data Dictionary (/docs/data-features/data-dictionary) — it is the single authoritative field reference and is more complete than the individual table pages.

Answer quality guidelines

  • Be specific about table names. Don’t say “the contacts table” — say PER_LATEST or “the Person Table (RELEASE.PER_LATEST)”.
  • Always include the schema prefix in SQL. RELEASE.PER_LATEST, not PER_LATEST.
  • Link to the relevant doc page when one exists. Prefer specific pages (e.g., /docs/data-features/data-dictionary) over the homepage.
  • Clarify the access mode (Feeds, Gigasheet, API) before giving instructions — the answer is different for each.
  • For schema questions, check the Data Dictionary first. It contains the most current and complete field definitions.