{"openapi":"3.0.3","info":{"title":"Relentless Identity API","version":"1.0.0","description":"Public client API for Finder and Probe workflows. This spec is generated from the FastAPI app, then narrowed to the supported bearer-authenticated routes used by SDKs and the API reference.\n\n[Back to Relentless Identity](https://relentlessidentity.com)"},"servers":[{"url":"https://api.relentlessidentity.com","description":"Production"}],"tags":[{"name":"Account","description":"Inspect token status, usage balance, request history, and job history."},{"name":"Finder","description":"Resolve the most likely work email for a person at a known domain."},{"name":"Probe","description":"Verify one or many known email addresses."},{"name":"Jobs","description":"Queue asynchronous Finder and Probe Batch work, then inspect job status and results."}],"paths":{"/client/token":{"get":{"summary":"Inspect the current bearer token","operationId":"getTokenStatus","parameters":[],"responses":{"200":{"description":"Bearer token status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientTokenStatusResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient prepaid credits or usage balance for that request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The bearer token does not include the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Request rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected backend failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Account"],"description":"Validate the current bearer token and return its active claims.","security":[{"bearerAuth":[]}]}},"/client/usage":{"get":{"summary":"Get current usage and limits","operationId":"getUsage","parameters":[],"responses":{"200":{"description":"Usage summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientUsageResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient prepaid credits or usage balance for that request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The bearer token does not include the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Request rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected backend failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Account"],"description":"Return the current account usage, free-tier limits, and paid capacity details for the authenticated user.","security":[{"bearerAuth":[]}]}},"/client/history":{"get":{"summary":"Get paginated request history","operationId":"getRequestHistory","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number starting at 1.","default":1,"title":"Page"},"description":"Page number starting at 1."},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":25,"minimum":1,"description":"Number of history rows per page. Maximum 25.","default":25,"title":"Page Size"},"description":"Number of history rows per page. Maximum 25."},{"name":"request_type","in":"query","required":false,"schema":{"anyOf":[{"enum":["finder","probe"],"type":"string"},{"type":"null"}],"description":"Optional request-type filter.","title":"Request Type"},"description":"Optional request-type filter."},{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"enum":["deliverable","undeliverable"],"type":"string"},{"type":"null"}],"description":"Optional deliverability-state filter.","title":"State"},"description":"Optional deliverability-state filter."}],"responses":{"200":{"description":"Paginated request history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientRequestHistoryPageResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient prepaid credits or usage balance for that request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The bearer token does not include the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Request rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected backend failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Account"],"description":"Return the authenticated user's latest request history with pagination and optional filters.","security":[{"bearerAuth":[]}]}},"/client/jobs":{"get":{"summary":"List background jobs","operationId":"listJobs","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Page Size"}},{"name":"job_type","in":"query","required":false,"schema":{"anyOf":[{"enum":["finder_batch","probe_batch"],"type":"string"},{"type":"null"}],"title":"Job Type"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["queued","processing","completed","failed","canceled"],"type":"string"},{"type":"null"}],"title":"Status"}}],"responses":{"200":{"description":"Paginated background jobs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientBackgroundJobPageResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient prepaid credits or usage balance for that request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The bearer token does not include the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Request rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected backend failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Jobs"],"description":"Return the authenticated user's paginated background job history.","security":[{"bearerAuth":[]}]}},"/client/jobs/{job_id}":{"get":{"summary":"Get background job","operationId":"getJob","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Page Size"}}],"responses":{"200":{"description":"Background job detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientBackgroundJobDetailResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient prepaid credits or usage balance for that request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The bearer token does not include the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Request rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected backend failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Jobs"],"description":"Return the current status and paginated results for one background job.","security":[{"bearerAuth":[]}]}},"/client/jobs/{job_id}/inputs.txt":{"get":{"summary":"Download job inputs","operationId":"getJobInputsText","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"if-none-match","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"If-None-Match"}},{"name":"if-modified-since","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"If-Modified-Since"}}],"responses":{"200":{"description":"Background job inputs","content":{"text/plain":{"schema":{"type":"string"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient prepaid credits or usage balance for that request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The bearer token does not include the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Request rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected backend failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Jobs"],"description":"Return the original background job inputs as plain text when the payload is still retained.","security":[{"bearerAuth":[]}]}},"/client/jobs/{job_id}/results.txt":{"get":{"summary":"Download job results as text","operationId":"getJobResultsText","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"if-none-match","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"If-None-Match"}},{"name":"if-modified-since","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"If-Modified-Since"}}],"responses":{"200":{"description":"Background job results text","content":{"text/plain":{"schema":{"type":"string"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient prepaid credits or usage balance for that request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The bearer token does not include the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Request rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected backend failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Jobs"],"description":"Return the canonical background job results in a readable plain-text format.","security":[{"bearerAuth":[]}]}},"/client/jobs/{job_id}/results.json":{"get":{"summary":"Download job results as JSON","operationId":"getJobResultsJson","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"if-none-match","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"If-None-Match"}},{"name":"if-modified-since","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"If-Modified-Since"}}],"responses":{"200":{"description":"Background job results artifact","content":{"application/json":{"schema":{}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient prepaid credits or usage balance for that request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The bearer token does not include the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Request rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected backend failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Jobs"],"description":"Return the canonical immutable background job results artifact as JSON.","security":[{"bearerAuth":[]}]}},"/client/jobs/finder":{"post":{"summary":"Schedule a finder batch","operationId":"scheduleFinderBatch","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinderBatchJobRequest"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientBackgroundJobResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient prepaid credits or usage balance for that request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The bearer token does not include the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Request rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected backend failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Jobs"],"description":"Queue a background finder batch job with an optional deadline and callback URL. Use this when synchronous Finder work would be too slow or when you want callback-based completion.","security":[{"bearerAuth":[]}]}},"/client/jobs/probe-batch":{"post":{"summary":"Schedule a probe batch","operationId":"scheduleProbeBatch","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProbeBatchJobBackgroundRequest"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientBackgroundJobResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient prepaid credits or usage balance for that request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The bearer token does not include the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Request rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected backend failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Jobs"],"description":"Queue a background probe batch job with an optional deadline and callback URL. Use this when synchronous Probe work would be too slow or when you want callback-based completion.","security":[{"bearerAuth":[]}]}},"/client/attempt":{"post":{"summary":"Find a work email","operationId":"finderAttempt","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinderRequest"}}}},"responses":{"200":{"description":"Finder response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientFinderResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient prepaid credits or usage balance for that request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The bearer token does not include the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Synchronous verification is temporarily at capacity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected backend failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Finder"],"description":"Send a full name and company domain to resolve the most likely verified work email. Budget up to about 60 seconds for a direct response; typical calls are closer to 20 seconds.","security":[{"bearerAuth":[]}]}},"/client/probe":{"post":{"summary":"Verify an email address","operationId":"probeEmail","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProbeRequest"}}}},"responses":{"200":{"description":"Probe response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientIdentityResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient prepaid credits or usage balance for that request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The bearer token does not include the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Synchronous verification is temporarily at capacity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected backend failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Probe"],"description":"Send a single email address to verify it directly. Budget up to about 15 seconds for a direct response; typical calls are closer to 5 seconds.","security":[{"bearerAuth":[]}]}},"/client/probe/batch":{"post":{"summary":"Verify many email addresses","operationId":"probeBatch","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProbeBatchRequest"}}}},"responses":{"200":{"description":"Batch probe response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientBatchIdentityResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Insufficient prepaid credits or usage balance for that request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"The bearer token does not include the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Synchronous verification is temporarily at capacity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Unexpected backend failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["Probe"],"description":"Send many known email addresses and receive compact per-item identity results plus a batch summary. This is the higher-throughput sync path and it uses the same pay-as-you-go catalog pricing as signed-in PAYG purchases.","security":[{"bearerAuth":[]}]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"PAT","description":"Use a Personal Access Token generated in the dashboard. Send it as Authorization: Bearer relid_pat_..."}},"schemas":{"AliasInfo":{"properties":{"original":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Original"},"resolved":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolved"}},"type":"object","title":"AliasInfo","description":"Alias information when email is resolved to a different address."},"BatchSummary":{"type":"object","additionalProperties":false,"required":["total","found","not_found","errors","unique_domains"],"properties":{"total":{"type":"integer","minimum":0,"description":"Total number of requested items."},"found":{"type":"integer","minimum":0,"description":"Items that resolved to a positive deliverable result."},"not_found":{"type":"integer","minimum":0,"description":"Items that completed cleanly with a negative result."},"errors":{"type":"integer","minimum":0,"description":"Items that ended with an operational verification error rather than a mailbox verdict."},"unique_domains":{"type":"integer","minimum":0,"description":"Distinct mailbox domains represented in the batch."}}},"ClientBackgroundJobDetailResponse":{"properties":{"job":{"$ref":"#/components/schemas/ClientBackgroundJobResponse"},"items":{"items":{"$ref":"#/components/schemas/ClientBackgroundJobItemResponse"},"type":"array","title":"Items"},"total_items":{"type":"integer","title":"Total Items"},"page":{"type":"integer","title":"Page"},"page_size":{"type":"integer","title":"Page Size"},"total_pages":{"type":"integer","title":"Total Pages"},"results_expired":{"type":"boolean","description":"Whether the stored item payload rows have already expired and been pruned."}},"type":"object","required":["job","items","total_items","page","page_size","total_pages"],"title":"ClientBackgroundJobDetailResponse","description":"Background job detail plus paginated item results."},"ClientBackgroundJobItemResponse":{"properties":{"id":{"type":"string","title":"Id"},"item_index":{"type":"integer","title":"Item Index"},"status":{"type":"string","enum":["queued","processing","completed","error","canceled"],"title":"Status"},"request_type":{"type":"string","enum":["finder","probe"],"title":"Request Type"},"input":{"type":"object","additionalProperties":true,"description":"Original submitted input for this item."},"result":{"anyOf":[{"type":"object","additionalProperties":true},{"type":"null"}],"description":"Compact result payload for this item when available."},"result_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Result State"},"result_outcome":{"anyOf":[{"type":"string","enum":["found","not_found","error"]},{"type":"null"}],"description":"Per-item operational outcome."},"resolved_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolved Address"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider"},"charge_micros":{"type":"integer","title":"Charge Micros","default":0},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","item_index","status","request_type","input","created_at","updated_at"],"title":"ClientBackgroundJobItemResponse","description":"One item inside a background job payload."},"ClientBackgroundJobPageResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ClientBackgroundJobResponse"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"page":{"type":"integer","title":"Page"},"page_size":{"type":"integer","title":"Page Size"},"total_pages":{"type":"integer","title":"Total Pages"}},"type":"object","required":["items","total","page","page_size","total_pages"],"title":"ClientBackgroundJobPageResponse","description":"Paginated list of background jobs for the authenticated user."},"ClientBackgroundJobResponse":{"properties":{"billing_account_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Billing Account Id"},"id":{"type":"string","title":"Id"},"job_type":{"type":"string","enum":["finder_batch","probe_batch"],"title":"Job Type"},"status":{"type":"string","enum":["queued","processing","completed","failed","canceled"],"description":"Current high-level job lifecycle state."},"deadline_at":{"type":"string","format":"date-time","title":"Deadline At"},"estimated_runtime_seconds":{"type":"integer","title":"Estimated Runtime Seconds"},"scheduled_start_at":{"type":"string","format":"date-time","title":"Scheduled Start At"},"callback_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Callback Url"},"callback_status":{"type":"string","enum":["none","pending","delivered","failed"],"title":"Callback Status"},"callback_attempts":{"type":"integer","title":"Callback Attempts"},"callback_last_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Callback Last Error"},"requested_count":{"type":"integer","description":"Total number of submitted items for the job."},"completed_count":{"type":"integer","title":"Completed Count"},"success_count":{"type":"integer","title":"Success Count"},"not_found_count":{"type":"integer","title":"Not Found Count"},"error_count":{"type":"integer","title":"Error Count"},"reserved_amount_micros":{"type":"integer","title":"Reserved Amount Micros"},"actual_amount_micros":{"type":"integer","title":"Actual Amount Micros"},"progress_percent":{"type":"number","format":"float","description":"Approximate percent complete based on completed item count."},"summary":{"type":"object","additionalProperties":true,"description":"Aggregated counts and provider stats for the job."},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At"},"history_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"History Expires At"},"results_pruned_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Timestamp when heavy item payload rows were removed after retention expiry."},"artifact_available":{"type":"boolean","title":"Artifact Available","default":false},"artifact_json_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Artifact Json Url"},"artifact_size_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Artifact Size Bytes"},"artifact_uploaded_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Artifact Uploaded At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","job_type","status","deadline_at","estimated_runtime_seconds","scheduled_start_at","callback_status","callback_attempts","requested_count","completed_count","success_count","not_found_count","error_count","reserved_amount_micros","actual_amount_micros","created_at","updated_at"],"title":"ClientBackgroundJobResponse","description":"Background job status envelope returned by the public jobs API."},"ClientBatchIdentityResponse":{"properties":{"results":{"type":"array","description":"Per-email compact probe results in request order.","items":{"$ref":"#/components/schemas/ClientIdentityResponse"}},"summary":{"$ref":"#/components/schemas/BatchSummary"}},"type":"object","required":["results","summary"],"title":"ClientBatchIdentityResponse","description":"Synchronous batch Probe response with compact per-item results and a small summary block."},"ClientFinderResponse":{"properties":{"state":{"type":"string","enum":["deliverable","undeliverable"],"description":"Final public deliverability verdict."},"outcome":{"type":"string","enum":["found","not_found","error"],"description":"Operational outcome. `error` means the verification could not complete cleanly and should not be treated as a negative mailbox verdict."},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Resolved or verified email address when available."},"is_alias":{"type":"boolean","description":"Whether the resolved address is an alias rather than a primary mailbox."},"alias":{"anyOf":[{"$ref":"#/components/schemas/AliasInfo"},{"type":"object","additionalProperties":true}],"description":"Alias metadata when `is_alias=true`."},"is_catchall":{"type":"boolean","description":"Whether the mailbox domain behaved like a catch-all during verification."},"identity_providers":{"type":"array","items":{"$ref":"#/components/schemas/IdentityProvider"},"title":"Identity Providers","description":"Identity providers associated with the mailbox domain when available."},"mx_hosts":{"type":"array","items":{"type":"string"},"description":"Observed MX hosts for the mailbox domain."},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Request correlation identifier useful for support and debugging."},"alternatives":{"type":"array","items":{"type":"string"},"description":"Additional valid identities found during finder resolution."}},"type":"object","required":["state"],"title":"ClientFinderResponse","description":"Compact public result envelope used by Finder and Probe style responses."},"ClientIdentityResponse":{"properties":{"state":{"type":"string","enum":["deliverable","undeliverable"],"title":"State"},"outcome":{"type":"string","enum":["found","not_found","error"],"title":"Outcome","default":"found"},"address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address"},"is_alias":{"type":"boolean","title":"Is Alias","default":false},"alias":{"anyOf":[{"$ref":"#/components/schemas/AliasInfo"},{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Alias"},"is_catchall":{"type":"boolean","title":"Is Catchall","default":false},"identity_providers":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Identity Providers"},"mx_hosts":{"items":{"type":"string"},"type":"array","title":"Mx Hosts"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id"}},"type":"object","required":["state"],"title":"ClientIdentityResponse","description":"Client-facing response for combined identity + SMTP probes."},"ClientRequestHistoryItem":{"properties":{"id":{"type":"string","title":"Id"},"request_type":{"type":"string","enum":["finder","probe"],"title":"Request Type"},"input_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Input Name"},"input_domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Input Domain"},"input_email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Input Email"},"input_label":{"type":"string","description":"Compact human-readable identifier for the original request input."},"state":{"type":"string","enum":["deliverable","undeliverable"],"title":"State"},"outcome":{"type":"string","enum":["found","not_found","error"],"title":"Outcome"},"resolved_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolved Address"},"duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration Ms"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider"},"identity_providers":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Identity Providers"},"mx_hosts":{"items":{"type":"string"},"type":"array","title":"Mx Hosts"},"metadata":{"type":"object","additionalProperties":true,"description":"Small transport and outcome metadata associated with the request."},"is_alias":{"type":"boolean","title":"Is Alias","default":false},"is_catchall":{"type":"boolean","title":"Is Catchall","default":false},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id"},"created_at":{"type":"string","format":"date-time","title":"Created At"}},"type":"object","required":["id","request_type","input_label","state","outcome","created_at"],"title":"ClientRequestHistoryItem","description":"One completed direct request visible in the user's request history."},"ClientRequestHistoryPageResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ClientRequestHistoryItem"},"type":"array","title":"Items"},"total":{"type":"integer","title":"Total"},"page":{"type":"integer","title":"Page"},"page_size":{"type":"integer","title":"Page Size"},"total_pages":{"type":"integer","title":"Total Pages"}},"type":"object","required":["items","total","page","page_size","total_pages"],"title":"ClientRequestHistoryPageResponse","description":"Paginated request history result."},"ClientTokenStatusResponse":{"properties":{"valid":{"type":"boolean","description":"Whether the current bearer token is valid for this request."},"user_id":{"type":"string","description":"User id associated with the bearer token."},"billing_account_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Billing Account Id"},"token_type":{"type":"string","enum":["pat","oauth"],"description":"How the bearer token was issued."},"scopes":{"type":"array","items":{"type":"string"},"description":"Scopes currently attached to the bearer token."},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"},"expires_in_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expires In Seconds"}},"type":"object","required":["user_id","token_type"],"title":"ClientTokenStatusResponse","description":"Current bearer token claims as seen by the API."},"ClientUsageResponse":{"properties":{"plan_tier":{"type":"string","description":"Current plan family, such as free or paid."},"billing_account_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Billing Account Id"},"billing_mode":{"type":"string","title":"Billing Mode"},"billing_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Billing Status"},"free_window_limit":{"type":"integer","title":"Free Window Limit"},"free_window_hours":{"type":"integer","title":"Free Window Hours"},"free_weekly_limit":{"type":"integer","title":"Free Weekly Limit"},"window_requests_used":{"type":"integer","title":"Window Requests Used"},"weekly_requests_used":{"type":"integer","title":"Weekly Requests Used"},"window_requests_remaining":{"type":"integer","title":"Window Requests Remaining"},"weekly_requests_remaining":{"type":"integer","title":"Weekly Requests Remaining"},"billing_cycle_value_micros":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Billing Cycle Value Micros"},"billing_extra_value_micros":{"type":"integer","title":"Billing Extra Value Micros"},"billing_value_micros_used":{"type":"integer","title":"Billing Value Micros Used"},"billing_value_micros_reserved":{"type":"integer","description":"Paid usage value currently reserved by queued or running background jobs."},"billing_value_micros_remaining":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Paid usage value currently remaining after used and reserved amounts are accounted for."},"usage_percent_remaining":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Usage Percent Remaining"},"current_plan_finder_deliverable_cost_micros":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Current Plan Finder Deliverable Cost Micros"},"current_plan_finder_undeliverable_cost_micros":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Current Plan Finder Undeliverable Cost Micros"},"current_plan_probe_cost_micros":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Current Plan Probe Cost Micros"}},"type":"object","required":["plan_tier","billing_mode","free_window_limit","free_window_hours","free_weekly_limit","window_requests_used","weekly_requests_used","window_requests_remaining","weekly_requests_remaining","billing_extra_value_micros","billing_value_micros_used"],"title":"ClientUsageResponse","description":"Current authenticated account usage, free-tier windows, and paid balance snapshot."},"ErrorResponse":{"type":"object","additionalProperties":false,"properties":{"error":{"type":"string","description":"Stable machine-readable error key."},"message":{"type":"string","description":"Human-friendly error summary safe to show to an operator or end user."},"detail":{"type":"string","description":"Optional raw backend detail when available."},"retry_after_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Optional retry hint in seconds when the failure is temporary."}}},"FinderBatchJobRequest":{"type":"object","additionalProperties":false,"required":["inputs"],"description":"Queue a background Finder workload that can wait for capacity and complete asynchronously. Use this when you do not want to keep a direct request open.","properties":{"deadline":{"type":"string","format":"date-time","description":"Optional hard deadline for the job. Omit it to start as soon as capacity allows. If provided, the API returns 422 when the deadline is too tight even with immediate execution.","example":"2027-01-02T00:00:00Z"},"callback_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Optional callback URL that receives the final job payload.","example":"https://example.com/callbacks/relentless"},"inputs":{"type":"array","minItems":1,"maxItems":100,"description":"One or more Finder-style inputs that will be processed asynchronously.","items":{"type":"object","additionalProperties":false,"required":["full_name","email_domain"],"properties":{"full_name":{"type":"string","description":"The real person's full name.","example":"Jane Doe"},"email_domain":{"type":"string","description":"The company website or mailbox domain.","example":"acme.com"}}}}}},"FinderRequest":{"type":"object","additionalProperties":false,"required":["full_name","email_domain"],"description":"Resolve the most likely verified work email for one person at one company domain. Direct calls are the slower sync path and should be budgeted for up to about 60 seconds.","properties":{"full_name":{"type":"string","description":"The real person's full name. Include middle names or initials when known.","example":"Jane Doe"},"email_domain":{"type":"string","description":"The company's public website or mailbox domain.","example":"acme.com"}}},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"IdentityProvider":{"type":"object","additionalProperties":false,"properties":{"provider":{"type":"string","example":"okta"},"hostname":{"anyOf":[{"type":"string"},{"type":"null"}],"example":"company.okta.com"}}},"ProbeBatchJobBackgroundRequest":{"type":"object","additionalProperties":false,"required":["emails"],"description":"Queue a background Probe Batch workload that can wait for capacity and complete asynchronously. Use this when you do not want to keep a direct request open.","properties":{"deadline":{"type":"string","format":"date-time","description":"Optional hard deadline for the job. Omit it to start as soon as capacity allows. If provided, the API returns 422 when the deadline is too tight even with immediate execution.","example":"2027-01-02T00:00:00Z"},"callback_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"description":"Optional callback URL that receives the final job payload."},"emails":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","format":"email"},"description":"One or more exact mailbox addresses to verify asynchronously.","example":["jane.doe@acme.com","john.smith@acme.com"]}}},"ProbeBatchRequest":{"type":"object","additionalProperties":false,"required":["emails"],"description":"Verify many known email addresses synchronously and receive compact per-item results. This batch path is the best fit for higher-throughput sync work and uses pay-as-you-go pricing.","properties":{"emails":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","format":"email"},"description":"One or more exact mailbox addresses to verify.","example":["jane.doe@acme.com","john.smith@acme.com"]}}},"ProbeRequest":{"type":"object","additionalProperties":false,"required":["email"],"description":"Verify one known email address directly. Direct calls are usually quick and should be budgeted for up to about 15 seconds.","properties":{"email":{"type":"string","format":"email","description":"The email address you want to verify.","example":"jane.doe@acme.com"}}},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"security":[{"bearerAuth":[]}]}