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 theRELEASE 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
- Always qualify table names with the schema:
RELEASE.PER_LATEST, not justPER_LATEST. - Use
LEFT JOINas the default.INNER JOINsilently drops contacts that have no matching organization — this is usually not what users want. Note this distinction when it matters. - 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. - Use
EMAIL_LAST_VERIFIED_ATfor freshness. This is the correct field to filter on for high-confidence outbound targeting. - Use
LATERAL FLATTENfor Historical Experience. Thejobscolumn is an array. Direct column access won’t work — you must flatten it. - 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. - Never add
_ORGor_PERsuffixes to column names inPER_LATESTorORG_LATEST. These base tables always use unsuffixed column names (e.g.,HEADQUARTERS_CITY, notHEADQUARTERS_CITY_ORG) — verify against the Data Dictionary before writing a query. The_ORGsuffix appears inINSIGHTS_LATEST(org-level, all fields suffixed) and both_ORG/_PERappear in the pre-joinedVELOCITY_*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-keyheader with the API key. NotAuthorization. Notx-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’sexact 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 onPOST /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_atfield). - At least 97% of emails are re-verified every 60 days (
email_last_verified_atfield). - Records not verified for one year are deprecated and removed.
email_last_verified_atis the single strongest freshness signal. Prioritize it overupdated_atfor 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
/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_LATESTor “the Person Table (RELEASE.PER_LATEST)”. - Always include the schema prefix in SQL.
RELEASE.PER_LATEST, notPER_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.
