{"openapi":"3.1.0","info":{"title":"Revenuebase Email Verification","description":"This API provides endpoints for validating email addresses individually or through file uploads.","version":"0.1.0"},"servers":[{"url":"https://api.revenuebase.ai"}],"paths":{"/v1/credits":{"get":{"tags":["User Operations"],"summary":"Get your remaining credit balance","description":"Returns the number of validation credits remaining on your account. Each `Valid` or `Invalid` result deducts 1 credit.","operationId":"credits_v1_credits_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsResponse"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/new-api-key":{"get":{"tags":["User Operations"],"summary":"Rotate your API key","description":"Generates a new API key and immediately invalidates the previous one. Update all integrations with the new key before making further requests.","operationId":"new_api_key_v1_new_api_key_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewKeyResponse"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/process-email":{"post":{"tags":["Email Processing"],"summary":"Validate a single email address","description":"Validates one email address synchronously. Returns `Valid`, `Invalid`, or `Unknown`. Set `metadata=true` to include MX record presence, email provider, security gateway, and failure reason in the response. Deducts 1 credit on `Valid` or `Invalid` results. Rate limited to 1 request per second.\n\n**Errors**\n- `402` — Insufficient credits. Recharge your account before retrying.","operationId":"real_time_email_v1_process_email_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"metadata","in":"query","required":false,"schema":{"type":"boolean","description":"Include detailed metadata in response","default":false,"title":"Metadata"},"description":"Include detailed metadata in response"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RealTimeEmailRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Real Time Email V1 Process Email Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/batch-upload":{"post":{"tags":["Email Processing"],"summary":"Upload a batch file for email validation","description":"Accepts a `.csv` or `.json` file and queues it for asynchronous processing. Returns a `process_id` — use it to poll status or download results when complete. Set `metadata=true` to include MX record, email provider, and failure reason fields in the output file.\n\n**Errors**\n- `400 invalid_extension` — File must be `.csv` or `.json`.\n- `400 upload_error` — File upload failed. Contact support.","operationId":"batch_upload_v1_batch_upload_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"metadata","in":"query","required":false,"schema":{"type":"boolean","description":"Include detailed metadata in response","default":false,"title":"Metadata"},"description":"Include detailed metadata in response"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_batch_upload_v1_batch_upload_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchEmailResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/batch-process-email":{"post":{"tags":["Email Processing"],"summary":"Queue a pre-uploaded batch file for processing","description":"⚠️ Deprecated — use `POST /v1/batch-upload` instead.\n\nQueues a file that has already been uploaded to your account. Returns a `process_id` to track status. Filename must be under 120 characters.\n\n**Errors**\n- `400` — File not found or upload error.","operationId":"batch_email_v1_batch_process_email_post","deprecated":true,"security":[{"APIKeyHeader":[]}],"parameters":[{"name":"metadata","in":"query","required":false,"schema":{"type":"boolean","description":"Include detailed metadata in response","default":false,"title":"Metadata"},"description":"Include detailed metadata in response"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchEmailRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchEmailResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/batch-process-email-status":{"post":{"tags":["Email Processing"],"summary":"Check the status of a batch job","description":"Returns the current processing status for a batch job. Only the user who submitted the job can query it.\n\nPossible statuses: `QUEUED`, `PROCESSING`, `COMPLETED`, `ERROR`, `CANCELLING`, `CANCELLED`.\n\n**Errors**\n- `400` — Invalid `process_id` or job does not belong to your account.","operationId":"batch_email_status_v1_batch_process_email_status_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchEmailStatusRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchEmailStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/queued-process":{"get":{"tags":["Email Processing"],"summary":"List active batch jobs","description":"Returns all batch jobs in `QUEUED` or `PROCESSING` status for your account. Use the `process_id` from each result to poll individual job status or cancel.","operationId":"process_queue_v1_queued_process_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueuedProcessesResponse"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/cancel-process":{"post":{"tags":["Email Processing"],"summary":"Cancel a queued or processing batch job","description":"Marks a batch job for cancellation. Jobs in `QUEUED` state will not be processed. Jobs in `PROCESSING` state may not stop immediately.\n\n**Errors**\n- `400 already_cancelled` — Job is already `CANCELLED` or `CANCELLING`.\n- `400 not_cancellable` — Job has status `COMPLETED` or `ERROR` and cannot be cancelled.\n- `400` — Invalid `process_id` or job does not belong to your account.","operationId":"cancel_process_v1_cancel_process_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchEmailStatusRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchEmailStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v1/batch-download":{"post":{"tags":["Email Processing"],"summary":"Download the results of a completed batch job","description":"Streams the processed output file for a completed or cancelled batch job. The response includes a `Content-Disposition` header with the original filename.\n\n**Errors**\n- `400 not_completed` — Job must have status `COMPLETED` or `CANCELLED` before downloading.\n- `400 process_error` — Job ended with an error. No output file is available.\n- `400` — Invalid `process_id` or job does not belong to your account.","operationId":"batch_download_v1_batch_download_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchEmailDownloadRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"title":"Response Batch Download V1 Batch Download Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v2/company-resolver/resolve":{"post":{"tags":["Company Resolver"],"summary":"Resolve Company","description":"Match a company name to a verified company record.\n\nUses semantic search to find the closest matching companies for a given name.\nOptionally filter by headquarters location. Returns up to 10 results ranked by\nsimilarity score (`similar_score`). Deducts 1 credit per request.\n\n`result_count` must be between 1 and 10 (inclusive).\n\n**Errors**\n- `400` — `result_count` is out of the allowed range.\n- `402` — Insufficient credits. Recharge your account before retrying.","operationId":"resolve_company_v2_company_resolver_resolve_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyResolverRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyResolverResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}},"/v2/company-resolver/discovery":{"post":{"tags":["Company Resolver"],"summary":"Discover Company","description":"Discover companies by keyword or description.\n\nUses semantic search to find companies matching a keyword or natural-language description.\nOptionally filter by headquarters location. Returns up to 2,000 results ranked by\nsimilarity score (`similar_score`). Deducts 1 credit per result count.\n\n`result_count` must be between 1 and 2000 (inclusive).\n\n**Errors**\n- `400` — `result_count` is out of the allowed range.\n- `402` — Insufficient credits. Recharge your account before retrying.","operationId":"discover_company_v2_company_resolver_discovery_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyDiscoverRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyResolverResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyHeader":[]}]}}},"components":{"schemas":{"BatchEmailDownloadRequest":{"properties":{"process_id":{"type":"integer","title":"Process Id"}},"type":"object","required":["process_id"],"title":"BatchEmailDownloadRequest"},"BatchEmailRequest":{"properties":{"filename":{"type":"string","title":"Filename"}},"type":"object","required":["filename"],"title":"BatchEmailRequest"},"BatchEmailResponse":{"properties":{"process_id":{"type":"integer","title":"Process Id"},"filename":{"type":"string","title":"Filename"},"status":{"type":"string","title":"Status"}},"type":"object","required":["process_id","filename","status"],"title":"BatchEmailResponse"},"BatchEmailStatusRequest":{"properties":{"process_id":{"type":"integer","title":"Process Id"}},"type":"object","required":["process_id"],"title":"BatchEmailStatusRequest"},"BatchEmailStatusResponse":{"properties":{"process_id":{"type":"integer","title":"Process Id"},"filename":{"type":"string","title":"Filename"},"current_status":{"type":"string","title":"Current Status"},"message":{"type":"string","title":"Message"}},"type":"object","required":["process_id","filename","current_status","message"],"title":"BatchEmailStatusResponse"},"Body_batch_upload_v1_batch_upload_post":{"properties":{"requested_file":{"type":"string","format":"binary","title":"Requested File"}},"type":"object","required":["requested_file"],"title":"Body_batch_upload_v1_batch_upload_post"},"Company":{"properties":{"rbid":{"type":"string","title":"Rbid"},"company_name":{"type":"string","title":"Company Name"},"similar_score":{"type":"number","title":"Similar Score"},"about_us":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"About Us"},"headquarters_street":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headquarters Street"},"headquarters_city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headquarters City"},"headquarters_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headquarters State"},"headquarters_zip":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headquarters Zip"},"headquarters_country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headquarters Country"}},"type":"object","required":["rbid","company_name","similar_score"],"title":"Company"},"CompanyDiscoverRequest":{"properties":{"result_count":{"type":"integer","title":"Result Count","default":1000},"keyword":{"type":"string","title":"Keyword"},"headquarters_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headquarters State"},"headquarters_country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headquarters Country"},"headquarters_city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headquarters City","description":"Case-sensitive. Must match the city name exactly as stored."},"headquarters_street":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headquarters Street"},"headquarters_zip":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headquarters Zip"}},"type":"object","required":["keyword"],"title":"CompanyDiscoverRequest"},"CompanyResolverRequest":{"properties":{"result_count":{"type":"integer","title":"Result Count","default":3},"company_name":{"type":"string","title":"Company Name"},"headquarters_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headquarters State"},"headquarters_country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headquarters Country"},"headquarters_city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headquarters City"},"headquarters_street":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headquarters Street"},"headquarters_zip":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Headquarters Zip"}},"type":"object","required":["company_name"],"title":"CompanyResolverRequest"},"CompanyResolverResponse":{"properties":{"companies":{"items":{"$ref":"#/components/schemas/Company"},"type":"array","title":"Companies"}},"type":"object","required":["companies"],"title":"CompanyResolverResponse"},"CreditsResponse":{"properties":{"credits":{"type":"integer","title":"Credits"}},"type":"object","required":["credits"],"title":"CreditsResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"NewKeyResponse":{"properties":{"api_key":{"type":"string","title":"Api Key"}},"type":"object","required":["api_key"],"title":"NewKeyResponse"},"Process":{"properties":{"process_id":{"type":"integer","title":"Process Id"},"filename":{"type":"string","title":"Filename"},"status":{"type":"string","title":"Status"},"message":{"type":"string","title":"Message"},"last_updated":{"type":"string","format":"date-time","title":"Last Updated"}},"type":"object","required":["process_id","filename","status","message","last_updated"],"title":"Process"},"QueuedProcessesResponse":{"properties":{"processes":{"items":{"$ref":"#/components/schemas/Process"},"type":"array","title":"Processes"}},"type":"object","required":["processes"],"title":"QueuedProcessesResponse"},"RealTimeEmailRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email"}},"type":"object","required":["email"],"title":"RealTimeEmailRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"x-key"}}}}