{"openapi":"3.1.0","info":{"title":"1Lookup API","version":"1.0.0","summary":"Phone, email, IP, business, social and SEO data in one API.","description":"One API key and one shared credit balance across every product. Most phone, email and IP lookups cost 1 credit.\n\nEvery response uses the same envelope: `{ \"success\": true, \"data\": { ... } }` on success and\n`{ \"success\": false, \"error\": { \"message\", \"code\", \"type\" } }` on failure. Check `success` before reading `data`.\n\nEvery response carries an `X-Request-Id` header; quote it when contacting support. Lookups also return\n`X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. A 429 or 503 carries `Retry-After`:\nwait that many seconds before retrying. Nothing is charged for a request that fails.\n\nResults are cached for 7 days, and repeating a lookup you ran yourself within that window is normally free.\nSend `bypass_cache: true` to force a fresh lookup.\n\nAPI access needs a paid plan: a free-plan key gets 403 `UPGRADE_REQUIRED`.\n\nAgents can also reach the phone, email and IP lookups over the hosted MCP server at https://app.1lookup.io/api/mcp\ninstead of REST; connection details are in the MCP server card at https://www.1lookup.io/.well-known/mcp/server-card.json.","termsOfService":"https://www.1lookup.io/terms","contact":{"name":"1Lookup Support","url":"https://www.1lookup.io/contact"},"license":{"name":"Proprietary","url":"https://www.1lookup.io/terms"}},"servers":[{"url":"https://app.1lookup.io/api/v1","description":"Production"}],"externalDocs":{"description":"Full API documentation","url":"https://app.1lookup.io/api"},"tags":[{"name":"Phone","description":"Validate, classify and scrub phone numbers."},{"name":"Email","description":"Verify deliverability of email addresses."},{"name":"IP","description":"Geolocate IP addresses and flag proxies and VPNs."},{"name":"Business","description":"Verify and enrich business and property records."},{"name":"Enrichment","description":"Turn one identifier into a fuller contact or company record."},{"name":"Social","description":"Live public social-media data."},{"name":"SEO","description":"Search, keyword and backlink intelligence."},{"name":"Web","description":"Read and extract data from web pages."},{"name":"Content","description":"Transcribe audio and video."},{"name":"Bulk","description":"Run one product over a list of inputs in the background."},{"name":"Monitoring","description":"Recheck phone numbers or contacts on a schedule and record what changes."},{"name":"Account","description":"Plan, credit balance and usage."}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key as a bearer token: `Authorization: Bearer sk_live_...`. Create keys at https://app.1lookup.io/api-keys."}},"headers":{"RequestId":{"description":"Id of this request. Quote it when contacting support.","schema":{"type":"string","format":"uuid"}},"RateLimitLimit":{"description":"Requests allowed in the current window.","schema":{"type":"integer"}},"RateLimitRemaining":{"description":"Requests left in the current window.","schema":{"type":"integer"}},"RateLimitReset":{"description":"Unix time, in seconds, when the window resets.","schema":{"type":"integer"}},"RetryAfter":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"schemas":{"ErrorResponse":{"type":"object","required":["success","error"],"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","required":["message","code","type"],"properties":{"message":{"type":"string","description":"Human-readable description of what went wrong."},"code":{"type":"string","description":"Stable machine-readable error code. Each response lists the codes it can carry; branch on the code, not the message."},"type":{"type":"string","enum":["api_error"]}}}}},"LookupRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Id of this lookup."},"type":{"type":"string","description":"Lookup type, such as `phone`, `email` or `hlr_lookup`."},"input":{"type":"string","description":"The input as it was looked up, after normalization."},"timestamp":{"type":"string","format":"date-time","description":"When the lookup ran."},"processing_time_ms":{"type":"integer","description":"Server-side processing time, in milliseconds."}},"required":["id","type","input","timestamp","processing_time_ms"]},"RiskAssessment":{"type":"object","properties":{"fraud_score":{"type":"number","minimum":0,"maximum":100,"description":"0 to 100, higher is riskier. Not returned by every product (phone validation has none)."},"risk_level":{"type":"string","enum":["LOW","MEDIUM","HIGH","CRITICAL"]},"risk_factors":{"type":"array","items":{"type":"string"},"description":"Codes for what raised the risk, such as `NOT_REACHABLE`, `DISPOSABLE_EMAIL` or `NO_MATCH_FOUND`."},"confidence_level":{"type":"number","minimum":0,"maximum":100,"description":"0 to 100."}},"required":["risk_level","risk_factors","confidence_level"]},"Recommendations":{"type":"object","properties":{"primary_action":{"type":"string","enum":["APPROVE","VERIFY","REVIEW","BLOCK"]},"secondary_actions":{"type":"array","items":{"type":"string"}},"user_message":{"type":"string","description":"One plain sentence describing the result."},"business_rules":{"type":"object","additionalProperties":true,"description":"Product-specific yes/no rules, such as `sms_allowed` and `voice_allowed` for a phone number."}},"required":["primary_action","secondary_actions","user_message","business_rules"]},"LookupMetadata":{"type":"object","properties":{"api_version":{"type":"string"},"schema_version":{"type":"string"},"credits_used":{"type":"integer","description":"Credits this call cost. 0 for a no-match on success-billed products, and for a cached result you ran yourself."},"credits_remaining":{"type":"integer","description":"Credits left on the account after this call."},"cache_hit":{"type":"boolean","description":"True when the result came from the 7-day cache."},"cached_at":{"type":"string","format":"date-time","description":"When the cached result was first looked up. Only on cache hits."},"data_sources":{"type":"array","items":{"type":"string"},"description":"Generic labels for the kinds of data consulted."},"fallback_used":{"type":"boolean","description":"Email verification only: a second verification ran."},"lookup_source":{"type":"string","enum":["standard","premium"],"description":"Reverse phone lookup only: which record was read."}},"required":["api_version","schema_version","cache_hit","data_sources"]},"LookupResult":{"type":"object","description":"A lookup result. `classification` and `insights` hold product-specific fields.","required":["request","classification","insights","recommendations","metadata"],"properties":{"request":{"$ref":"#/components/schemas/LookupRequest"},"risk_assessment":{"$ref":"#/components/schemas/RiskAssessment"},"classification":{"type":"object","additionalProperties":true,"description":"Product-specific headline fields."},"insights":{"type":"object","additionalProperties":true,"description":"Product-specific detail."},"recommendations":{"$ref":"#/components/schemas/Recommendations"},"metadata":{"$ref":"#/components/schemas/LookupMetadata"}}},"PhoneResult":{"type":"object","description":"Phone validation result. US and Canada numbers are checked against carrier records; numbers in other countries against their numbering plan, which leaves the US-only fields null.","required":["request","classification","insights","recommendations","metadata"],"properties":{"request":{"$ref":"#/components/schemas/LookupRequest"},"risk_assessment":{"$ref":"#/components/schemas/RiskAssessment"},"classification":{"type":"object","properties":{"line_type":{"type":"string","enum":["MOBILE","LANDLINE","VOIP","TOLL_FREE","PREMIUM","UNKNOWN"]},"carrier_type":{"type":"string","enum":["MAJOR_CARRIER","REGIONAL_CARRIER","VOIP_PROVIDER","INTERNATIONAL_CARRIER","UNKNOWN"]},"number_status":{"type":"string","enum":["ACTIVE","INACTIVE","INVALID","VALID","UNKNOWN"],"description":"US and Canada: ACTIVE, INACTIVE or INVALID from the carrier record, UNKNOWN for a toll-free number the record does not cover. Other countries: VALID or INVALID."},"portability_status":{"type":"string","enum":["PORTED","NOT_PORTED","POSSIBLY_PORTED"]},"service_type":{"type":"string","enum":["POSTPAID","LANDLINE","TOLL_FREE","UNKNOWN"]},"connection_quality":{"type":"string","enum":["EXCELLENT","GOOD","POOR","UNKNOWN"]},"coverage":{"type":"string","enum":["international"],"description":"Only on numbers outside the US and Canada."},"country_code":{"type":["string","null"],"description":"ISO country code. Only on numbers outside the US and Canada."}},"required":["line_type","carrier_type","number_status","portability_status","service_type","connection_quality"]},"insights":{"type":"object","properties":{"location":{"type":"object","properties":{"timezone":{"type":["string","null"],"description":"Time zone of the number's area, or UNKNOWN."},"country":{"type":["string","null"],"description":"Country name. Only on numbers outside the US and Canada."},"country_code":{"type":["string","null"],"description":"ISO country code. Only on numbers outside the US and Canada."},"regions":{"type":"array","items":{"type":"string"},"description":"Regions the number range belongs to. Only on numbers outside the US and Canada."}}},"carrier":{"type":"object","properties":{"name":{"type":["string","null"],"description":"Network name."},"mcc":{"type":["string","null"],"description":"Mobile country code."},"mnc":{"type":["string","null"],"description":"Mobile network code."}},"description":"Only on numbers outside the US and Canada. For US and Canada numbers the carrier name is `raw_api_fields.network`."},"routing":{"type":"object","properties":{"lrn":{"type":"string","description":"Location routing number, or N/A."},"original_number":{"type":"string"},"is_ported":{"type":["boolean","null"],"description":"null when porting is possible but unconfirmed."},"port_type":{"type":["integer","string"]}}},"reachability":{"type":"object","properties":{"is_reachable":{"type":["boolean","null"],"description":"null when reachability was not checked: toll-free numbers, and numbers outside the US and Canada."},"reachable_status":{"type":["integer","string","boolean","null"],"description":"Raw reachability flag from the record."},"verification_method":{"type":"string"},"reason":{"type":"string"}}},"compliance":{"type":"object","properties":{"dnc_listed":{"type":["boolean","null"],"description":"On the US Do Not Call list. null outside the US and Canada."},"dnc_status":{"type":"string","enum":["LISTED","NOT_LISTED","NOT_APPLICABLE"]},"dno_flag":{"type":["boolean","null"],"description":"Do Not Originate flag. null outside the US and Canada."},"number_quality":{"type":"string","enum":["GOOD","POOR"]},"good_number":{"type":"boolean"}}},"risk_indicators":{"type":"object","properties":{"voip_detected":{"type":"boolean"},"burner_probability":{"type":"number","minimum":0,"maximum":1,"description":"0 to 1."}}},"raw_api_fields":{"type":"object","additionalProperties":true,"description":"The underlying carrier record: `number`, `lrn`, `network` (carrier name), `class` (line class: W mobile, L landline, V VoIP), `country` and related routing fields."}},"required":["routing","reachability","compliance","risk_indicators"]},"recommendations":{"$ref":"#/components/schemas/Recommendations"},"metadata":{"$ref":"#/components/schemas/LookupMetadata"}}},"PhoneSpamResult":{"type":"object","description":"Spam and fraud check for a phone number. `risk_assessment.fraud_score` is the headline number.","required":["request","classification","insights","recommendations","metadata"],"properties":{"request":{"$ref":"#/components/schemas/LookupRequest"},"risk_assessment":{"$ref":"#/components/schemas/RiskAssessment"},"classification":{"type":"object","properties":{"caller_type":{"type":"string","description":"For example LEGITIMATE_PERSONAL, LEGITIMATE_AUTOMATED, SPAM_HUMAN or SPAM_ROBOCALL for US and Canada numbers; LEGITIMATE, SUSPICIOUS_CALLER or HIGH_RISK_CALLER elsewhere."},"threat_category":{"type":"string","description":"For example LEGITIMATE, SPAM_CALLER or AUTOMATED_SCAM; SUSPICIOUS_ACTIVITY or FRAUD_RISK outside the US and Canada."},"industry_category":{"type":"string"},"persistence_level":{"type":"string"},"sophistication_level":{"type":"string"},"line_status":{"type":"string","enum":["ACTIVE","DISCONNECTED","UNKNOWN"],"description":"Only on numbers outside the US and Canada."}}},"insights":{"type":"object","properties":{"reputation":{"type":"object","properties":{"report_count":{"type":"integer","description":"Estimated spam reports."}}},"behavior":{"type":"object","properties":{"callback_probability":{"type":"number","description":"0 to 1."}}},"threat_intelligence":{"type":"object","properties":{"scam_types":{"type":"array","items":{"type":"string"}},"financial_loss_risk":{"type":"string","description":"HIGH, MEDIUM, LOW or UNKNOWN."}}},"network_analysis":{"type":"object","properties":{"origin_country":{"type":"string"}}}}},"recommendations":{"$ref":"#/components/schemas/Recommendations"},"metadata":{"$ref":"#/components/schemas/LookupMetadata"}}},"PhoneScrubResult":{"type":"object","description":"Do Not Call and litigator scrub. `matched` is false when the number is unknown, and then nothing is charged.","required":["request","classification","insights","recommendations","metadata"],"properties":{"request":{"$ref":"#/components/schemas/LookupRequest"},"risk_assessment":{"$ref":"#/components/schemas/RiskAssessment"},"classification":{"type":"object","properties":{"matched":{"type":"boolean"},"phone":{"type":["string","null"]},"formattedPhone":{"type":["string","null"]},"phoneTypeCode":{"type":["string","null"],"description":"One-letter line code from the record."},"phoneTypeLabel":{"type":["string","null"],"description":"MOBILE, LANDLINE, VOIP, LITIGATOR or UNKNOWN."},"doNotCall":{"type":"boolean","description":"On a Do Not Call list."},"litigator":{"type":"boolean","description":"Belongs to a known litigator, serial complainer or attorney. Never contact."}},"required":["matched","doNotCall","litigator"]},"insights":{"type":"object","properties":{"phone_scrub_result":{"type":"object","properties":{"matched":{"type":"boolean"},"phone":{"type":["string","null"]},"formattedPhone":{"type":["string","null"]},"phoneTypeCode":{"type":["string","null"]},"phoneTypeLabel":{"type":["string","null"]},"doNotCall":{"type":"boolean"},"litigator":{"type":"boolean"},"processedTime":{"type":["string","null"]}}}}},"recommendations":{"$ref":"#/components/schemas/Recommendations"},"metadata":{"$ref":"#/components/schemas/LookupMetadata"}}},"HlrResult":{"type":"object","description":"Live network status of a mobile number.","required":["request","classification","insights","recommendations","metadata"],"properties":{"request":{"$ref":"#/components/schemas/LookupRequest"},"risk_assessment":{"$ref":"#/components/schemas/RiskAssessment"},"classification":{"type":"object","properties":{"lookup_type":{"type":"string","enum":["HLR"]},"connectivity_status":{"type":"string","description":"Status as the network reported it, such as CONNECTED, ABSENT, ABSENT_SUBSCRIBER, INVALID_MSISDN or UNDETERMINED. `is_valid` and the risk fields come from a normalized reading of it."},"is_valid":{"type":"boolean","description":"False when the network reports the number invalid or unallocated. Such a lookup is not charged."},"is_ported":{"type":"boolean"},"is_roaming":{"type":"boolean"},"mccmnc":{"type":"string"},"mcc":{"type":"string"},"mnc":{"type":"string"}},"required":["lookup_type","connectivity_status","is_valid","is_ported","is_roaming"]},"insights":{"type":"object","properties":{"hlr_result":{"type":"object","properties":{"id":{"type":"string"},"msisdn":{"type":"string","description":"The number, in international format without +."},"connectivity_status":{"type":"string"},"current_carrier":{"type":"string","description":"Carrier the number is on now: the ported carrier when ported, otherwise the original."},"current_mccmnc":{"type":"string"},"original_carrier":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"country_prefix":{"type":"string"},"is_ported":{"type":"boolean"},"ported_carrier":{"type":["string","null"]},"ported_country":{"type":["string","null"]},"is_roaming":{"type":"boolean"},"roaming_carrier":{"type":["string","null"]},"roaming_country":{"type":["string","null"]},"imsi":{"type":["string","null"]},"data_source":{"type":"string","description":"Where the answer came from. LIVE_HLR is a live network query; MNP_DB is the portability database (most US and Canada numbers), which shows the number is assigned, not that the handset is on."},"timestamp":{"type":"string"}}}},"required":["hlr_result"]},"recommendations":{"$ref":"#/components/schemas/Recommendations"},"metadata":{"$ref":"#/components/schemas/LookupMetadata"}}},"MnpResult":{"type":"object","description":"Mobile number portability result.","required":["request","classification","insights","recommendations","metadata"],"properties":{"request":{"$ref":"#/components/schemas/LookupRequest"},"risk_assessment":{"$ref":"#/components/schemas/RiskAssessment"},"classification":{"type":"object","properties":{"lookup_type":{"type":"string","enum":["MNP"]},"query_status":{"type":"string","enum":["OK","ERROR"]},"number_type":{"type":"string","description":"Number type from the portability record, or UNKNOWN."},"is_ported":{"type":"boolean"},"mccmnc":{"type":"string"},"mcc":{"type":"string"},"mnc":{"type":"string"}},"required":["lookup_type","query_status","is_ported"]},"insights":{"type":"object","properties":{"mnp_result":{"type":"object","properties":{"id":{"type":"string"},"msisdn":{"type":"string"},"query_status":{"type":"string","enum":["OK","ERROR"]},"current_carrier":{"type":"string"},"current_mccmnc":{"type":"string"},"original_carrier":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"country_prefix":{"type":"string"},"is_ported":{"type":"boolean"},"ported_carrier":{"type":["string","null"]},"ported_country":{"type":["string","null"]},"number_type":{"type":"string"},"timestamp":{"type":"string"}}}},"required":["mnp_result"]},"recommendations":{"$ref":"#/components/schemas/Recommendations"},"metadata":{"$ref":"#/components/schemas/LookupMetadata"}}},"NtResult":{"type":"object","description":"Number type result.","required":["request","classification","insights","recommendations","metadata"],"properties":{"request":{"$ref":"#/components/schemas/LookupRequest"},"risk_assessment":{"$ref":"#/components/schemas/RiskAssessment"},"classification":{"type":"object","properties":{"lookup_type":{"type":"string","enum":["NT"]},"query_status":{"type":"string","enum":["OK","ERROR"]},"number_type":{"type":"string","enum":["MOBILE","LANDLINE","VOIP","TOLL_FREE","PREMIUM","UNKNOWN"]},"is_valid":{"type":"boolean","description":"False for an invalid number, which is not charged."},"is_possibly_ported":{"type":"boolean"},"is_vanity_number":{"type":"boolean"},"qualifies_for_hlr_lookup":{"type":"boolean","description":"True when an HLR lookup can give live status for this number."},"mccmnc":{"type":"string"},"mcc":{"type":"string"},"mnc":{"type":"string"}},"required":["lookup_type","query_status","number_type","is_valid"]},"insights":{"type":"object","properties":{"nt_result":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"number_type":{"type":"string","enum":["MOBILE","LANDLINE","VOIP","TOLL_FREE","PREMIUM","UNKNOWN"]},"query_status":{"type":"string","enum":["OK","ERROR"]},"is_valid":{"type":"boolean"},"invalid_reason":{"type":["string","null"]},"is_possibly_ported":{"type":"boolean"},"is_vanity_number":{"type":"boolean"},"qualifies_for_hlr_lookup":{"type":"boolean"},"carrier":{"type":"string","description":"Original network name."},"mccmnc":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"regions":{"type":"array","items":{"type":"string"}},"timezones":{"type":"array","items":{"type":"string"}},"info_text":{"type":"string"},"timestamp":{"type":"string"}}}},"required":["nt_result"]},"recommendations":{"$ref":"#/components/schemas/Recommendations"},"metadata":{"$ref":"#/components/schemas/LookupMetadata"}}},"ReversePhoneResult":{"type":"object","description":"Reverse phone lookup. `matched` is false when no record was found, and then nothing is charged.","required":["request","classification","insights","recommendations","metadata"],"properties":{"request":{"$ref":"#/components/schemas/LookupRequest"},"risk_assessment":{"$ref":"#/components/schemas/RiskAssessment"},"classification":{"type":"object","properties":{"matched":{"type":"boolean"},"primary_name":{"type":["string","null"]},"secondary_name":{"type":["string","null"]},"company_name":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"phone_type":{"type":["string","null"]},"lookup_type":{"type":"string","enum":["reverse_phone"]},"coverage_supported":{"type":"boolean","description":"False for a number outside the covered region (US numbers only)."},"coverage_region":{"type":"string"}},"required":["matched","coverage_supported"]},"insights":{"type":"object","properties":{"reverse_lookup_result":{"type":"object","properties":{"matched":{"type":"boolean"},"primary_name":{"type":["string","null"]},"secondary_name":{"type":["string","null"]},"company_name":{"type":["string","null"]},"email":{"type":["string","null"]},"address":{"type":"object","properties":{"line1":{"type":["string","null"]},"line2":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"zip":{"type":["string","null"]},"zip4":{"type":["string","null"]}}},"phone":{"type":["string","null"]},"phone_type":{"type":["string","null"]},"processed_time":{"type":"string"},"coverage_supported":{"type":"boolean"},"coverage_region":{"type":"string"}}}}},"recommendations":{"$ref":"#/components/schemas/Recommendations"},"metadata":{"$ref":"#/components/schemas/LookupMetadata"}}},"ReverseEmailResult":{"type":"object","description":"Reverse email append. `matched` is false when no record was found, and then nothing is charged.","required":["request","classification","insights","recommendations","metadata"],"properties":{"request":{"$ref":"#/components/schemas/LookupRequest"},"risk_assessment":{"$ref":"#/components/schemas/RiskAssessment"},"classification":{"type":"object","properties":{"matched":{"type":"boolean"},"email":{"type":["string","null"]},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"address":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"zip_code":{"type":["string","null"]},"country":{"type":["string","null"]},"phone":{"type":["string","null"]},"phone_dnc":{"type":"boolean","description":"The phone is on a Do Not Call list."},"cell":{"type":["string","null"]},"cell_dnc":{"type":"boolean","description":"The cell is on a Do Not Call list."},"lookup_type":{"type":"string","enum":["reverse_email"]}},"required":["matched"]},"insights":{"type":"object","properties":{"reverse_email_result":{"type":"object","properties":{"matched":{"type":"boolean"},"contact":{"type":"object","properties":{"fullName":{"type":["string","null"]},"firstName":{"type":["string","null"]},"lastName":{"type":["string","null"]}}},"email":{"type":["string","null"]},"phones":{"type":"object","properties":{"phoneNumber":{"type":["string","null"]},"phoneDnc":{"type":"boolean"},"cellNumber":{"type":["string","null"]},"cellDnc":{"type":"boolean"}}},"address":{"type":"object","properties":{"line1":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"country":{"type":["string","null"]},"zipCode":{"type":["string","null"]}}},"company":{"type":"object","properties":{"name":{"type":["string","null"]},"jobTitle":{"type":["string","null"]},"industry":{"type":["string","null"]},"linkedInUrl":{"type":["string","null"]},"website":{"type":["string","null"]},"country":{"type":["string","null"]}}}}}}},"recommendations":{"$ref":"#/components/schemas/Recommendations"},"metadata":{"$ref":"#/components/schemas/LookupMetadata"}}},"EmailResult":{"type":"object","description":"Email verification result.","required":["request","classification","insights","recommendations","metadata"],"properties":{"request":{"$ref":"#/components/schemas/LookupRequest"},"risk_assessment":{"$ref":"#/components/schemas/RiskAssessment"},"classification":{"type":"object","properties":{"email_type":{"type":"string","enum":["BUSINESS_PERSONAL","FREE_PROVIDER","ROLE_BASED","UNKNOWN"]},"provider_type":{"type":"string","enum":["CORPORATE","FREE","DISPOSABLE"]},"provider_tier":{"type":"string","enum":["ENTERPRISE","TIER_1_FREE","TIER_2_FREE","DISPOSABLE"]},"deliverability_status":{"type":"string","enum":["DELIVERABLE","RISKY","UNDELIVERABLE","TEMPORARY","UNKNOWN"]},"mailbox_verification_state":{"type":"string","enum":["CONFIRMED","UNCONFIRMED"],"description":"UNCONFIRMED when the mail server would not say whether the mailbox exists."},"inbox_placement":{"type":"string","enum":["PRIMARY","PROMOTIONS","SPAM","UNCERTAIN"]},"engagement_potential":{"type":"string","enum":["HIGH","MEDIUM","LOW","NONE"]}},"required":["email_type","deliverability_status","mailbox_verification_state"]},"insights":{"type":"object","properties":{"deliverability":{"type":"object","properties":{"score":{"type":"number"},"factors":{"type":"object","properties":{"mx_records":{"type":["boolean","null"],"description":"The domain publishes mail servers. null when unknown."},"smtp_valid":{"type":["boolean","null"],"description":"null when the mailbox could not be confirmed."},"mailbox_exists":{"type":["boolean","null"],"description":"null when the mailbox could not be confirmed."},"catch_all":{"type":"boolean","description":"The domain accepts mail for any address."},"greylisted":{"type":"boolean"}}},"upstream_verification_detail":{"type":"string","description":"Extra detail when the mailbox could not be confirmed."}}},"quality":{"type":"object","properties":{"score":{"type":"number"},"syntax_valid":{"type":"boolean"},"typo_detected":{"type":"boolean"},"professional_format":{"type":"boolean"},"name_pattern":{"type":"string","enum":["FIRSTNAME_DOT_LASTNAME","INITIAL_DOT_LASTNAME","SINGLE_NAME","NAME_WITH_NUMBERS","OTHER","UNKNOWN"]}}},"reputation":{"type":"object","properties":{"domain_age_days":{"type":["integer","null"],"description":"Age of the domain in days. null when the registry gave no date."},"domain_reputation":{"type":"string","description":"EXCELLENT, GOOD, FAIR, POOR, LOW or UNKNOWN."},"spam_trap_risk":{"type":"string","enum":["HIGH","NONE"]},"honeypot_risk":{"type":"string","enum":["MEDIUM","NONE"]}}},"intelligence":{"type":"object","properties":{"lead_score":{"type":"number"},"b2b_indicator":{"type":"boolean","description":"Not a free provider and not a role address."},"seniority_indicator":{"type":"string"},"department_hint":{"type":"string","enum":["GENERIC","PERSONAL"]}}},"domain_intelligence":{"type":"object","additionalProperties":true,"description":"Present when domain data was available: `registration`, `infrastructure`, `technologies` and `trust_indicators`."},"business_profile":{"type":"object","additionalProperties":true,"description":"Present with `domain_intelligence`: a legitimacy score and business, trust and risk signals for the domain."}},"required":["deliverability","quality","reputation"]},"recommendations":{"$ref":"#/components/schemas/Recommendations"},"metadata":{"$ref":"#/components/schemas/LookupMetadata"}}},"IpResult":{"type":"object","description":"IP address lookup result. `risk_assessment.fraud_score` is the headline number.","required":["request","classification","insights","recommendations","metadata"],"properties":{"request":{"$ref":"#/components/schemas/LookupRequest"},"risk_assessment":{"$ref":"#/components/schemas/RiskAssessment"},"classification":{"type":"object","properties":{"connection_type":{"type":"string","enum":["RESIDENTIAL_ISP","MOBILE_NETWORK","DATACENTER","CDN_NETWORK","PUBLIC_DNS","PROXY_SERVER","UNKNOWN"]},"service_type":{"type":"string","enum":["STANDARD_ISP","HOSTING_SERVICE","VPN_SERVICE","PUBLIC_DNS"]},"anonymity_level":{"type":"string","enum":["NONE","MEDIUM","HIGH"]},"organization_type":{"type":"string","enum":["ISP","HOSTING_PROVIDER","TECH_GIANT"]},"residential_probability":{"type":"number","minimum":0,"maximum":1,"description":"0 to 1."}},"required":["connection_type","anonymity_level"]},"insights":{"type":"object","properties":{"network":{"type":"object","properties":{"isp":{"type":"string"},"org":{"type":"string"},"asn":{"type":"string","description":"Autonomous system, or Unknown."},"asn_reputation":{"type":"string","enum":["EXCELLENT","GOOD","POOR"]}}},"geographic":{"type":"object","properties":{"datacenter_location":{"type":"boolean"},"vpn_exit_probability":{"type":"number","description":"0 to 1."},"tor_exit_node":{"type":"boolean"},"hosting_facility":{"type":"string"}}},"location":{"type":"object","properties":{"city":{"type":"string"},"region":{"type":"string"},"country":{"type":"string"},"country_code":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"timezone":{"type":"string"},"continent":{"type":"string"},"continent_code":{"type":"string"},"zip":{"type":"string"},"district":{"type":"string"}}},"security":{"type":"object","properties":{"reputation_score":{"type":"number"},"tor_exit_node":{"type":"boolean"}}},"network_intelligence":{"type":"object","properties":{"is_datacenter":{"type":"boolean"},"cloud_provider":{"type":["string","null"],"description":"Cloud operator that owns the address, when it is a published cloud range."},"cloud_region":{"type":["string","null"]},"cloud_service":{"type":["string","null"]},"is_tor_exit":{"type":"boolean"},"verified_crawler":{"type":["object","null"],"properties":{"operator":{"type":"string"},"bot":{"type":"string"}},"description":"Set when a self-declared crawler really came from that operator's published ranges."},"is_bogon":{"type":"boolean","description":"A reserved or unroutable address."},"coverage":{"type":"string","enum":["complete","partial","unavailable"],"description":"How many of the network feeds were checked."},"checked_feeds":{"type":"array","items":{"type":"string"}},"missing_feeds":{"type":"array","items":{"type":"string"}},"data_as_of":{"type":["string","null"]}}},"usage_patterns":{"type":"object","properties":{"likely_automation":{"type":"boolean"},"api_usage":{"type":"boolean"},"human_probability":{"type":"number","description":"0 to 1."},"business_usage":{"type":"boolean"}}}},"required":["network","location","security"]},"recommendations":{"$ref":"#/components/schemas/Recommendations"},"metadata":{"$ref":"#/components/schemas/LookupMetadata"}}},"LinkedinEmailFinderResult":{"type":"object","description":"Work email found from a LinkedIn profile. `matched` is false when no verified email was found, and then nothing is charged.","required":["request","classification","insights","recommendations","metadata"],"properties":{"request":{"$ref":"#/components/schemas/LookupRequest"},"risk_assessment":{"$ref":"#/components/schemas/RiskAssessment"},"classification":{"type":"object","properties":{"matched":{"type":"boolean"},"work_email":{"type":["string","null"]},"full_name":{"type":["string","null"]},"job_title":{"type":["string","null"]},"company":{"type":["string","null"]},"company_domain":{"type":["string","null"]},"city":{"type":["string","null"]},"region":{"type":["string","null"]},"country":{"type":["string","null"]},"profile_url":{"type":["string","null"]},"query":{"type":["string","null"],"description":"The profile looked up. Only on a no-match."}},"required":["matched","work_email"]},"insights":{"type":"object","properties":{"linkedin_email_finder":{"type":["object","null"],"properties":{"work_email":{"type":"string"},"full_name":{"type":["string","null"]},"first_name":{"type":["string","null"]},"job_title":{"type":["string","null"]},"profile_url":{"type":["string","null"]},"company":{"type":["string","null"]},"company_domain":{"type":["string","null"]},"company_city":{"type":["string","null"]},"company_region":{"type":["string","null"]},"company_country":{"type":["string","null"]},"city":{"type":["string","null"]},"region":{"type":["string","null"]},"country":{"type":["string","null"]}},"description":"null on a no-match."}}},"recommendations":{"$ref":"#/components/schemas/Recommendations"},"metadata":{"$ref":"#/components/schemas/LookupMetadata"}}},"Account":{"type":"object","properties":{"user":{"type":"object","properties":{"email":{"type":["string","null"],"description":"Email of the user who created the API key, or of the account owner."}}},"organization":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"subscription":{"type":["object","null"],"properties":{"status":{"type":"string","description":"Subscription status, such as active or trialing."},"is_trial":{"type":"boolean"},"trial_end":{"type":["string","null"]},"current_period_start":{"type":"string","format":"date-time"},"current_period_end":{"type":"string","format":"date-time"},"plan":{"type":"object","properties":{"name":{"type":"string"},"tokens_per_month":{"type":"integer","description":"Credits the plan adds each month."}}}},"description":"null when the account has no subscription."},"tokens":{"type":"object","properties":{"subscription":{"type":"object","properties":{"total":{"type":"integer"},"used":{"type":"integer"},"available":{"type":"integer"}},"description":"This billing period's plan credits."},"rollover":{"type":"integer","description":"Credits carried over from earlier periods."},"purchased":{"type":"integer","description":"Credits bought separately."},"total_available":{"type":"integer","description":"Every credit the account can spend now."}},"description":"Credit balance. `tokens` is the API's name for credits."},"usage":{"type":"object","properties":{"current_period":{"type":"object","properties":{"lookups":{"type":"integer"},"tokens_consumed":{"type":"integer"}}},"all_time":{"type":"object","properties":{"lookups":{"type":["integer","null"],"description":"null when the total could not be read."},"tokens_consumed":{"type":["integer","null"]}}}}},"api_key":{"type":"object","properties":{"id":{"type":"string","description":"Id of the calling API key. Empty when the call was not made with an API key."},"total_lookups":{"type":["integer","null"]},"total_tokens_consumed":{"type":["integer","null"]}}}},"required":["user","organization","subscription","tokens","usage","api_key"],"description":"Account status for the calling API key."},"BulkJobCreated":{"type":"object","properties":{"job_id":{"type":"string"},"status":{"type":"string","description":"processing for a new job; the job's current status on an idempotent replay."},"accepted":{"type":"integer","description":"Rows accepted."},"webhook_url":{"type":"string","description":"The completion webhook, when one was registered."},"webhook_secret":{"type":"string","description":"Returned once, at creation, when a webhook was registered. Use it to verify the `X-1Lookup-Signature` header on the completion webhook."}},"required":["job_id","status","accepted"]},"BulkJobStatus":{"type":"object","properties":{"job_id":{"type":"string"},"status":{"type":"string","description":"pending, processing, completed, failed or paused_insufficient_credits."},"total":{"type":"integer"},"processed":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"skipped":{"type":"integer"},"duplicates":{"type":"integer"},"results_url":{"type":["string","null"],"description":"Signed CSV download URL, valid for 1 hour. null until results exist."},"webhook_url":{"type":"string","description":"Present while a completion webhook is registered."}},"required":["job_id","status","total","processed","succeeded","failed","skipped","duplicates","results_url"]},"BulkJobResults":{"type":"object","properties":{"job_id":{"type":"string"},"status":{"type":"string","description":"pending, processing, completed, failed or paused_insufficient_credits."},"results_url":{"type":["string","null"],"description":"Signed CSV download URL, valid for 1 hour."},"full_results_url":{"type":["string","null"],"description":"Signed CSV with every field, valid for 1 hour."},"csv_note":{"type":"string"},"lookups":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"input":{"type":"string"},"status":{"type":"string","description":"completed or failed."},"tokens_consumed":{"type":"integer","description":"Credits this row cost."},"response_data":{"type":"object","additionalProperties":true,"description":"The lookup result, in the same shape as the single-lookup endpoint's `data`."},"error_message":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"]}},"required":["id","input","status","tokens_consumed","created_at"]}},"pagination":{"type":"object","properties":{"limit":{"type":"integer"},"next_cursor":{"type":["string","null"],"description":"Pass as `cursor` to read the next page. null on the last page."},"has_more":{"type":"boolean"}},"required":["limit","next_cursor","has_more"]}},"required":["job_id","status","lookups","pagination"]},"BulkInsufficientCredits":{"type":"object","properties":{"code":{"type":"string","enum":["UPGRADE_REQUIRED"]},"error":{"type":"string"},"required":{"type":"integer","description":"Credits the job needs."},"available":{"type":"integer","description":"Credits the account has."},"shortfall":{"type":"integer"},"rowCount":{"type":"integer"},"tokenCostPerRow":{"type":"integer"},"suggestedPlan":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"tier":{"type":"string"},"tokens":{"type":"integer"},"monthlyPrice":{"type":"number"},"monthlyPriceId":{"type":"string"}}},"maxPlanTokens":{"type":"integer"},"planFullyCovers":{"type":"boolean"}},"required":["code","error","required","available","shortfall"],"description":"Returned with 402 when the account lacks the credits for every row. Unlike other errors, this body is not wrapped in `success` and `error`."},"NumberMonitor":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"frequency":{"type":"string","enum":["daily","weekly"]},"include_spam_check":{"type":"boolean"},"alert_email":{"type":"boolean"},"webhook_url":{"type":["string","null"]},"active":{"type":"boolean"},"number_count":{"type":"integer","description":"Only in the list response."},"last_run_at":{"type":["string","null"],"description":"Only in the list response."},"created_at":{"type":"string","format":"date-time"}},"required":["id","name","frequency","include_spam_check","alert_email","webhook_url","active","created_at"]},"NumberMonitorEvent":{"type":"object","properties":{"id":{"type":"string"},"phone_number":{"type":"string"},"label":{"type":["string","null"]},"changes":{"type":"object","description":"What changed, keyed by field (status, lineType, carrier, ported, dncListed, spamRiskLevel).","additionalProperties":{"type":"object","properties":{"from":{"type":["string","boolean"]},"to":{"type":["string","boolean"]}}}},"previous_snapshot":{"type":["object","null"],"additionalProperties":true},"current_snapshot":{"type":["object","null"],"additionalProperties":true},"detected_at":{"type":"string","format":"date-time"}},"required":["id","phone_number","changes","detected_at"]},"JobChangeMonitor":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"frequency":{"type":"string","enum":["weekly"]},"alert_email":{"type":"boolean"},"webhook_url":{"type":["string","null"]},"active":{"type":"boolean"},"contact_count":{"type":"integer","description":"Only in the list response."},"last_run_at":{"type":["string","null"],"description":"Only in the list response."},"created_at":{"type":"string","format":"date-time"}},"required":["id","name","frequency","alert_email","webhook_url","active","created_at"]},"JobChangeEvent":{"type":"object","properties":{"id":{"type":"string"},"profile_url":{"type":"string"},"label":{"type":["string","null"]},"type":{"type":"string","enum":["job_change","title_change","profile_unreachable","baseline"]},"before":{"type":["object","null"],"properties":{"title":{"type":["string","null"]},"company":{"type":["string","null"]},"location":{"type":["string","null"]}}},"after":{"type":["object","null"],"properties":{"title":{"type":["string","null"]},"company":{"type":["string","null"]},"location":{"type":["string","null"]}}},"detected_at":{"type":"string","format":"date-time"}},"required":["id","profile_url","type","detected_at"]}}},"paths":{"/phone":{"post":{"operationId":"lookupPhone","summary":"Validate a phone number","description":"Confirms a phone number is real and returns line type, carrier type, porting and, for US and Canada numbers, reachability and DNC/DNO flags. Numbers in other countries are checked against the numbering plan of their country. Costs 1 credit; an invalid number outside the US and Canada costs nothing.","tags":["Phone"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone_number"],"properties":{"phone_number":{"type":"string","description":"Phone number to validate. E.164 format recommended.","examples":["+14155552671"]},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"phone_number":"+14155552671"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/PhoneResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_FIELD`: The request field is missing; `INVALID_INPUT`: The input is not a string, or does not match the expected format; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/phone-spam":{"post":{"operationId":"lookupPhoneSpam","summary":"Check a phone number for spam or fraud history","description":"Reports whether a number is associated with spam, robocalls or fraud. Costs 1 credit for US and Canada numbers.","tags":["Phone"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone_number"],"properties":{"phone_number":{"type":"string","description":"Phone number to check.","examples":["+14155552671"]},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"phone_number":"+14155552671"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/PhoneSpamResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_FIELD`: The request field is missing; `INVALID_INPUT`: The input is not a string, or does not match the expected format; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/phone-scrub":{"post":{"operationId":"lookupPhoneScrub","summary":"Scrub a phone number against DNC and litigator lists","description":"Checks a number against Do Not Call and known-litigator lists before you dial or text it. Costs 10 credits, and nothing when there is no match.","tags":["Phone"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone_number"],"properties":{"phone_number":{"type":"string","description":"Phone number to scrub.","examples":["+14155552671"]},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"phone_number":"+14155552671"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/PhoneScrubResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_FIELD`: The request field is missing; `INVALID_INPUT`: The input is not a string, or does not match the expected format; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/hlr-lookup":{"post":{"operationId":"lookupHlr","summary":"HLR lookup for a mobile number","description":"Queries the mobile network for live subscriber status, roaming state and current carrier. Costs 5 credits; a number the network reports as invalid costs nothing.","tags":["Phone"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone_number"],"properties":{"phone_number":{"type":"string","description":"Mobile number in E.164 format.","examples":["+447700900123"]},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"phone_number":"+447700900123"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/HlrResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_FIELD`: The request field is missing; `INVALID_INPUT`: The input is not a string, or does not match the expected format; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/mnp-lookup":{"post":{"operationId":"lookupMnp","summary":"Mobile number portability lookup","description":"Returns the network a number has been ported to, rather than the network its prefix implies. Costs 3 credits; a lookup that errors costs nothing.","tags":["Phone"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone_number"],"properties":{"phone_number":{"type":"string","description":"Mobile number in E.164 format.","examples":["+447700900123"]},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"phone_number":"+447700900123"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/MnpResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_FIELD`: The request field is missing; `INVALID_INPUT`: The input is not a string, or does not match the expected format; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/nt-lookup":{"post":{"operationId":"lookupNumberType","summary":"Number type lookup","description":"Classifies a number as mobile, landline, VoIP, toll-free or premium, and says whether it qualifies for an HLR lookup. Costs 1 credit; an invalid number costs nothing.","tags":["Phone"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone_number"],"properties":{"phone_number":{"type":"string","description":"Phone number in E.164 format.","examples":["+447700900123"]},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"phone_number":"+447700900123"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/NtResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_FIELD`: The request field is missing; `INVALID_INPUT`: The input is not a string, or does not match the expected format; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/reverse-phone-lookup":{"post":{"operationId":"reversePhoneLookup","summary":"Reverse phone lookup","description":"Returns the person or business behind a US phone number. `lookup_source` picks the record: `standard` reads caller ID records (10 credits), `premium` searches full owner records (25 credits). Nothing is charged when there is no match.","tags":["Enrichment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone_number"],"properties":{"phone_number":{"type":"string","description":"US phone number to look up.","examples":["+14155552671"]},"lookup_source":{"type":"string","enum":["standard","premium"],"default":"standard","description":"`standard`: caller ID records, 10 credits. `premium`: full owner records, 25 credits. Any other value is refused with 400 `INVALID_INPUT`."},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"phone_number":"+14155552671"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/ReversePhoneResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_FIELD`: The request field is missing; `INVALID_INPUT`: The input is not a string, or does not match the expected format; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/mobile-finder":{"post":{"operationId":"findMobile","summary":"Find a person's mobile number","description":"Finds a mobile number for a person from a professional profile URL, a work email or a personal email. Send at least one. Costs 40 credits, and nothing when no mobile number is found.","tags":["Enrichment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"profile_url":{"type":"string","description":"Public professional profile URL, such as a LinkedIn profile. Also accepted as `profileUrl`."},"work_email":{"type":"string","description":"Work email address. Also accepted as `workEmail`."},"personal_email":{"type":"string","description":"Personal email address. Also accepted as `personalEmail`."},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}},"anyOf":[{"required":["profile_url"]},{"required":["work_email"]},{"required":["personal_email"]}]},"examples":{"default":{"value":{"profile_url":"https://www.linkedin.com/in/example/"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not a JSON object; `MISSING_FIELD`: None of profile_url, work_email or personal_email was sent; `INVALID_INPUT`: A field is malformed; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/phone-append":{"post":{"operationId":"skipTrace","summary":"Skip trace: append a phone number from name and address","description":"Matches a person's name and postal address to a phone number. Costs 10 credits.","tags":["Enrichment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["input"],"properties":{"input":{"type":"object","properties":{"firstName":{"type":"string","description":"First name."},"lastName":{"type":"string","description":"Last name."},"address":{"type":"string","description":"Street address."},"city":{"type":"string","description":"City."},"zip":{"type":"string","description":"ZIP code."}},"required":["firstName","lastName","address","city","zip"],"description":"The contact's name and postal address. All five fields are required and must be non-empty. PascalCase keys (`FirstName`, `LastName`, `Address`, `City`, `Zip`) are accepted too."},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"input":{"firstName":"Ada","lastName":"Lovelace","address":"1 Main St","city":"Springfield","zip":"62704"}}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_FIELD`: `input` is missing or is not an object; `INVALID_INPUT`: `input` lacks one of the five fields, or one is empty; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/email":{"post":{"operationId":"verifyEmail","summary":"Verify an email address","description":"Checks that a mailbox exists and is deliverable, and flags disposable, role-based, free-provider and catch-all addresses. Costs 1 credit.","tags":["Email"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","description":"Email address to verify.","examples":["ada@example.com"]},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"email":"ada@example.com"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/EmailResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_FIELD`: The request field is missing; `INVALID_INPUT`: The input is not a string, or does not match the expected format; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/email-append":{"post":{"operationId":"appendEmail","summary":"Append an email address from name and address","description":"Returns an email address for a person from their name and postal address. Costs 10 credits.","tags":["Enrichment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["input"],"properties":{"input":{"type":"object","properties":{"firstName":{"type":"string","description":"First name."},"lastName":{"type":"string","description":"Last name."},"address":{"type":"string","description":"Street address."},"city":{"type":"string","description":"City."},"zip":{"type":"string","description":"ZIP code."}},"required":["firstName","lastName","address","city","zip"],"description":"The contact's name and postal address. All five fields are required and must be non-empty. PascalCase keys (`FirstName`, `LastName`, `Address`, `City`, `Zip`) are accepted too."},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"input":{"firstName":"Ada","lastName":"Lovelace","address":"1 Main St","city":"Springfield","zip":"62704"}}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_FIELD`: `input` is missing or is not an object; `INVALID_INPUT`: `input` lacks one of the five fields, or one is empty; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/reverse-email-append":{"post":{"operationId":"reverseEmailAppend","summary":"Reverse email append","description":"Returns the person, postal address, phone numbers and company behind an email address. Costs 10 credits, and nothing when there is no match.","tags":["Enrichment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","description":"Email address to resolve.","examples":["ada@example.com"]},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"email":"ada@example.com"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/ReverseEmailResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_FIELD`: The request field is missing; `INVALID_INPUT`: The input is not a string, or does not match the expected format; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/email-enrichment":{"post":{"operationId":"enrichEmail","summary":"Find a work email from name and company domain","description":"Finds a person's work email from their first name, last name and company domain. Costs 5 credits, and nothing when there is no match.","tags":["Enrichment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"firstName":{"type":"string","description":"First name. Also accepted as `first_name`."},"lastName":{"type":"string","description":"Last name. Also accepted as `last_name`."},"fullName":{"type":"string","description":"Full name, split into first and last when either is missing. Also accepted as `full_name` or `name`."},"domain":{"type":"string","description":"Company domain, such as example.com. Also accepted as `company_domain` or `companyDomain`."},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}},"anyOf":[{"required":["firstName","lastName"]},{"required":["fullName"]}]},"examples":{"default":{"value":{"firstName":"Ada","lastName":"Lovelace","domain":"example.com"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not a JSON object; `MISSING_FIELD`: A company domain, first name or last name is missing; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/linkedin-email-finder":{"post":{"operationId":"findLinkedinEmail","summary":"Find a work email from a LinkedIn profile","description":"Takes a public LinkedIn profile URL and returns that person's verified work email, with name, job title, company, company domain and location. Costs 30 credits, and nothing when no verified email is found.","tags":["Enrichment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profile_url"],"properties":{"profile_url":{"type":"string","description":"Public LinkedIn profile URL (https://www.linkedin.com/in/...) or its bare username. Also accepted as `profileUrl`, `linkedin_url`, `linkedinUrl`, `url`, `username` or `vanity`."},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"profile_url":"https://www.linkedin.com/in/example/"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LinkedinEmailFinderResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_PROFILE_URL`: No profile URL was sent; `INVALID_PROFILE_URL`: The value is not a public LinkedIn profile URL; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/b2b-contact-append":{"post":{"operationId":"appendB2bContact","summary":"Append B2B contact details","description":"Returns business contact details for a person. Send a work email, a LinkedIn profile URL, a `person_id` from prospect search, or a name plus a company domain. Costs 75 credits, and nothing when there is no match.","tags":["Enrichment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Work email address."},"linkedin_url":{"type":"string","description":"LinkedIn profile URL. Also accepted as `linkedinUrl` or `profile_url`."},"person_id":{"type":"string","description":"The `reveal_key` of a person returned by prospect search."},"name":{"type":"string","description":"Full name."},"first_name":{"type":"string","description":"First name. Also accepted as `firstname`."},"last_name":{"type":"string","description":"Last name. Also accepted as `lastname`."},"domain":{"type":"string","description":"Company domain. Also accepted as `company`, `company_domain` or `organization_name`."},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}},"anyOf":[{"required":["email"]},{"required":["linkedin_url"]},{"required":["person_id"]},{"required":["name","domain"]},{"required":["first_name","last_name","domain"]}]},"examples":{"default":{"value":{"email":"ada@example.com"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_IDENTIFIER`: No identifier was sent; `INSUFFICIENT_IDENTIFIERS`: A name was sent without a company; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/ip":{"post":{"operationId":"lookupIp","summary":"Look up an IP address","description":"Returns geolocation, connection type and proxy, VPN, Tor and datacenter flags with a fraud score. Costs 1 credit.","tags":["IP"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ip"],"properties":{"ip":{"type":"string","description":"IPv4 or IPv6 address.","examples":["8.8.8.8"]},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"ip":"8.8.8.8"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/IpResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_FIELD`: The request field is missing; `INVALID_INPUT`: The input is not a string, or does not match the expected format; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/reverse-ip-append":{"post":{"operationId":"reverseIpAppend","summary":"Reverse IP append","description":"Returns the identity and network details associated with an IP address. Costs 10 credits.","tags":["Enrichment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ip"],"properties":{"ip":{"type":"string","description":"IPv4 or IPv6 address.","examples":["8.8.8.8"]},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"ip":"8.8.8.8"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_FIELD`: The request field is missing; `INVALID_INPUT`: The input is not a string, or does not match the expected format; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/business-verify":{"post":{"operationId":"verifyBusiness","summary":"Verify a business exists","description":"Confirms a business is real and open from its name and city, and cross-checks any phone, email or website you send into a 0 to 100 verification score. Costs 30 credits, and nothing when there is no match.","tags":["Business"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["business_name","city"],"properties":{"business_name":{"type":"string","description":"Business name. Also accepted as `businessName` or `name`."},"city":{"type":"string","description":"City the business is in."},"country":{"type":"string","default":"US","description":"Country code. Also accepted as `country_code`."},"phone":{"type":"string","description":"Phone number to check against the listing. Also accepted as `phone_number`."},"email":{"type":"string","description":"Email address to check."},"website":{"type":"string","description":"Website to check. Also accepted as `url`."},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"business_name":"Lakeside Dental","city":"Springfield"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_BUSINESS_IDENTITY`: business_name or city is missing; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/business-lookup":{"post":{"operationId":"lookupBusiness","summary":"Look up a business listing","description":"Returns the address, phone, website, category, rating, reviews, hours and open status of a business, from its name and city or the URL of its map listing. Costs 10 credits, and nothing when there is no match.","tags":["Business"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"business_name":{"type":"string","description":"Business name. Also accepted as `businessName` or `name`."},"city":{"type":"string","description":"City the business is in."},"country":{"type":"string","description":"Country code."},"place_url":{"type":"string","description":"URL of the business's map listing, to fetch that exact listing instead of searching. Also accepted as `placeUrl` or `url`."},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}},"anyOf":[{"required":["place_url"]},{"required":["business_name","city"]}]},"examples":{"default":{"value":{"business_name":"Lakeside Dental","city":"Springfield"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `INVALID_PLACE_URL`: place_url is not an http(s) URL; `MISSING_BUSINESS_NAME`: No place_url and no business_name; `MISSING_CITY`: business_name was sent without city; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/company-profile-lookup":{"post":{"operationId":"lookupCompanyProfile","summary":"Look up a company profile","description":"Returns the company profile behind a domain or a LinkedIn company page. Costs 25 credits, and nothing when there is no match.","tags":["Business"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","description":"Company domain, without scheme. Also accepted as `website` or `company_domain`."},"profile_url":{"type":"string","description":"LinkedIn company page URL (https://www.linkedin.com/company/...). Used instead of domain when sent. Also accepted as `profileUrl`, `linkedin_url`, `linkedinUrl` or `url`."},"include_funding":{"type":"boolean","default":true,"description":"Include funding data. Also accepted as `includeFunding`."},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}},"anyOf":[{"required":["domain"]},{"required":["profile_url"]}]},"examples":{"default":{"value":{"domain":"example.com"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `INVALID_PROFILE_URL`: profile_url is not a LinkedIn company page URL; `MISSING_DOMAIN`: Neither domain nor profile_url was sent; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/company-firmographics":{"post":{"operationId":"lookupCompanyFirmographics","summary":"Look up company firmographics","description":"Returns size, industry, revenue band and location for a company domain. Costs 75 credits, and nothing when there is no match.","tags":["Business"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","description":"Company domain, without scheme.","examples":["example.com"]},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"domain":"example.com"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_FIELD`: The request field is missing; `INVALID_INPUT`: The input is not a string, or does not match the expected format; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/property-lookup":{"post":{"operationId":"lookupProperty","summary":"Look up a property record","description":"Returns beds, baths, square footage, home type, year built, listing status, price and sale history for a US address or listing URL. Costs 15 credits, and nothing when there is no match.","tags":["Business"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","description":"Full US street address of the property."},"listing_url":{"type":"string","description":"URL of the property's real-estate listing, to fetch that exact listing. Used instead of address when sent. Also accepted as `listingUrl` or `url`."},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}},"anyOf":[{"required":["address"]},{"required":["listing_url"]}]},"examples":{"default":{"value":{"address":"1 Main St, Springfield, IL 62704"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `INVALID_LISTING_URL`: listing_url is not an http(s) URL; `MISSING_ADDRESS`: Neither address nor listing_url was sent; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/social-profile-check":{"post":{"operationId":"checkSocialProfile","summary":"Check a social profile","description":"Reports whether a profile exists on a social network and returns its public profile. Send a profile URL, or a platform and a handle. Costs 10 credits, and nothing when there is no match.","tags":["Social"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"Profile URL. Used instead of platform and handle when sent. Also accepted as `profile_url` or `profileUrl`."},"platform":{"type":"string","enum":["instagram","tiktok","youtube","twitter","facebook","threads","twitch","snapchat","bluesky","truthsocial"],"description":"Network to check. Short forms are accepted too: `x` for twitter, `ig` for instagram, `yt` for youtube, `fb` for facebook."},"handle":{"type":"string","description":"Handle, with or without the leading @. Also accepted as `username` or `user_name`."},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}},"anyOf":[{"required":["url"]},{"required":["platform","handle"]}]},"examples":{"default":{"value":{"platform":"instagram","handle":"1lookup"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `INVALID_PROFILE_URL`: url is not a profile URL on a supported network; `INVALID_PLATFORM`: platform is missing or not supported; `MISSING_HANDLE`: handle is missing; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/social-post-lookup":{"post":{"operationId":"lookupSocialPost","summary":"Look up a social post","description":"Returns the public content and engagement figures for a post on Instagram, TikTok, YouTube, X, Facebook, Threads, Bluesky, Truth Social, Pinterest or LinkedIn. Costs 5 credits, and nothing when there is no match.","tags":["Social"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"Post URL. Also accepted as `post_url` or `postUrl`."},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"url":"https://www.instagram.com/p/EXAMPLE/"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `INVALID_POST_URL`: url is missing, or is not a post on a supported network; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/social-search":{"post":{"operationId":"searchSocial","summary":"Search public social content","description":"Searches public posts and profiles on one platform for a query. Costs 5 credits, and nothing when there is no match.","tags":["Social"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["platform","query"],"properties":{"platform":{"type":"string","enum":["instagram","tiktok","youtube","threads","pinterest","reddit"],"description":"Platform to search."},"query":{"type":"string","description":"Search query. Also accepted as `q` or `keyword`."},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"platform":"tiktok","query":"data validation"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `INVALID_PLATFORM`: platform is missing or not supported; `MISSING_QUERY`: query is missing; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/audience-demographics":{"post":{"operationId":"lookupAudienceDemographics","summary":"Audience demographics for a TikTok account","description":"Returns the audience breakdown for a public TikTok account. Costs 40 credits, and nothing when there is no match.","tags":["Social"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["handle"],"properties":{"handle":{"type":"string","description":"TikTok handle, with or without the leading @, or a tiktok.com profile URL. Also accepted as `username`, `user_name` or `url`."},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"handle":"1lookup"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_HANDLE`: handle is missing; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/link-in-bio-lookup":{"post":{"operationId":"lookupLinkInBio","summary":"Expand a link-in-bio page","description":"Returns the destinations behind a link-in-bio page on linktr.ee, komi.io, pillar.io, lnk.bio or linkme.bio. Costs 3 credits, and nothing when there is no match.","tags":["Social"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"Link-in-bio page URL. Also accepted as `page_url` or `pageUrl`."},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"url":"https://linktr.ee/example"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `INVALID_PAGE_URL`: url is missing, or is not on a supported link-in-bio host; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/ad-library-lookup":{"post":{"operationId":"lookupAdLibrary","summary":"Look up a company's public ads","description":"Returns ads a company is running, from the public ad library of one platform. Send a company name or a search query. Costs 10 credits, and nothing when there is no match.","tags":["Social"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company":{"type":"string","description":"Company or advertiser name. Also accepted as `company_name` or `advertiser`."},"query":{"type":"string","description":"Search query, used when no company is sent. Also accepted as `q` or `keyword`."},"platform":{"type":"string","enum":["facebook","tiktok","linkedin","google"],"default":"facebook","description":"Ad library to search. `meta` is accepted as facebook."},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}},"anyOf":[{"required":["company"]},{"required":["query"]}]},"examples":{"default":{"value":{"company":"Analytical Engines Ltd"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `INVALID_PLATFORM`: platform is not supported; `MISSING_COMPANY_OR_QUERY`: Neither company nor query was sent; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/video-transcript":{"post":{"operationId":"getVideoTranscript","summary":"Transcript for a public video","description":"Returns the transcript of a public video on Instagram, TikTok, YouTube, X, Facebook, LinkedIn or Reddit. Costs 5 credits, and nothing when there is no match.","tags":["Content"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"Video URL. Also accepted as `video_url`, `videoUrl` or `post_url`."},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"url":"https://www.youtube.com/watch?v=EXAMPLE"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `INVALID_VIDEO_URL`: url is missing, or is not a video on a supported network; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/audio-transcription":{"post":{"operationId":"transcribeAudio","summary":"Transcribe an audio file","description":"Transcribes an audio or video file at an https URL, up to 240 minutes, with speaker labels. Costs 6 credits per minute of audio.","tags":["Content"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["audio_url"],"properties":{"audio_url":{"type":"string","description":"https URL of the file. Also accepted as `audioUrl` or `url`."},"expected_duration_minutes":{"type":"number","maximum":240,"description":"Length of the file in minutes, used when it cannot be measured. At most 240. Also accepted as `expectedDurationMinutes`."},"diarize":{"type":"boolean","default":true,"description":"Label speakers in the transcript."},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"audio_url":"https://example.com/call.mp3"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_AUDIO_URL`: audio_url is missing; `INVALID_AUDIO_URL`: audio_url is not an https URL; `AUDIO_TOO_LONG`: The file, or its declared length, is over 240 minutes; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/website-scraper":{"post":{"operationId":"scrapeWebsite","summary":"Scrape a web page","description":"Returns the readable content of a page. Costs 10 credits.","tags":["Web"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"Page URL to scrape.","examples":["https://example.com/pricing"]},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"url":"https://example.com/pricing"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_FIELD`: The request field is missing; `INVALID_INPUT`: The input is not a string, or does not match the expected format; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/website-contacts-scraper":{"post":{"operationId":"scrapeWebsiteContacts","summary":"Find contact details on a website","description":"Returns the email addresses and phone numbers published on a domain. Costs 10 credits.","tags":["Web"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","description":"Domain to scan, without scheme.","examples":["example.com"]},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"domain":"example.com"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_FIELD`: The request field is missing; `INVALID_INPUT`: The input is not a string, or does not match the expected format; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/domain-age":{"post":{"operationId":"lookupDomainAge","summary":"Domain age","description":"Returns registration date and age for a domain. Costs 2 credits, and nothing for an unregistered domain.","tags":["Web"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","description":"Domain, without scheme.","examples":["example.com"]},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"domain":"example.com"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_FIELD`: The request field is missing; `INVALID_INPUT`: The input is not a string, or does not match the expected format; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/domain-authority":{"post":{"operationId":"lookupDomainAuthority","summary":"Domain authority","description":"Returns authority and trust metrics for a domain. Costs 10 credits.","tags":["SEO"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","description":"Domain, without scheme.","examples":["example.com"]},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"domain":"example.com"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_FIELD`: The request field is missing; `INVALID_INPUT`: The input is not a string, or does not match the expected format; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/backlink-overview":{"post":{"operationId":"lookupBacklinkOverview","summary":"Backlink overview for a domain","description":"Returns referring domains and backlink counts. Costs 13 credits.","tags":["SEO"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","description":"Domain, without scheme.","examples":["example.com"]},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"domain":"example.com"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_FIELD`: The request field is missing; `INVALID_INPUT`: The input is not a string, or does not match the expected format; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/keyword-metrics":{"post":{"operationId":"lookupKeywordMetrics","summary":"Keyword metrics","description":"Returns volume, difficulty and cost-per-click for a keyword. Costs 6 credits.","tags":["SEO"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["keyword"],"properties":{"keyword":{"type":"string","description":"Keyword to look up.","examples":["phone validation api"]},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"keyword":"phone validation api"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_FIELD`: The request field is missing; `INVALID_INPUT`: The input is not a string, or does not match the expected format; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/search-intent-lookup":{"post":{"operationId":"lookupSearchIntent","summary":"Search intent for a query","description":"Classifies the intent behind a search query. Costs 1 credit.","tags":["SEO"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["q"],"properties":{"q":{"type":"string","description":"Search query to classify.","examples":["buy phone validation api"]},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"q":"buy phone validation api"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_FIELD`: The request field is missing; `INVALID_INPUT`: The input is not a string, or does not match the expected format; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/audience-intelligence":{"post":{"operationId":"lookupAudienceIntelligence","summary":"Audience intelligence for a domain","description":"Returns one audience report for a website: summary, geography, age and sex, income, traffic sources or destinations. Costs 86 credits.","tags":["SEO"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","description":"Website domain. Scheme, www. and path are stripped. Also accepted as `target` or `website`."},"report":{"type":"string","enum":["summary","geo","age_sex","income","sources","destinations"],"default":"summary","description":"Which report to return."},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"domain":"example.com","report":"summary"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_DOMAIN`: domain is missing; `INVALID_DOMAIN`: domain is not a valid domain; `INVALID_REPORT`: report is not one of the listed values; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/prospect-search":{"post":{"operationId":"searchProspects","summary":"Search for B2B prospects","description":"Returns people matching your filters. Send at least one filter. Each person carries a `reveal_key` that /b2b-contact-append accepts as `person_id`. Costs 2 credits.","tags":["Enrichment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"keywords":{"type":"string","description":"Free-text keywords."},"titles":{"type":"array","items":{"type":"string"},"description":"Job titles. A single string is accepted too."},"seniorities":{"type":"array","items":{"type":"string"},"description":"Seniority levels. A single string is accepted too."},"locations":{"type":"array","items":{"type":"string"},"description":"Person locations. A single string is accepted too."},"company_domains":{"type":"array","items":{"type":"string"},"description":"Company domains. A single string is accepted too."},"company_locations":{"type":"array","items":{"type":"string"},"description":"Company locations. A single string is accepted too."},"employee_ranges":{"type":"array","items":{"type":"string"},"description":"Company headcount ranges. A single string is accepted too."},"email_statuses":{"type":"array","items":{"type":"string"},"description":"Email statuses. A single string is accepted too."},"page":{"type":"integer","description":"Results page."},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}},"anyOf":[{"required":["keywords"]},{"required":["titles"]},{"required":["seniorities"]},{"required":["locations"]},{"required":["company_domains"]},{"required":["company_locations"]},{"required":["employee_ranges"]},{"required":["email_statuses"]}]},"examples":{"default":{"value":{"titles":["head of engineering"],"locations":["London"]}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_FILTERS`: No filter was sent; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/account-search":{"post":{"operationId":"searchAccounts","summary":"Search for B2B accounts","description":"Returns companies matching your filters. Send at least one filter. Costs 75 credits per search, which returns up to 100 companies.","tags":["Enrichment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"keywords":{"type":"string","description":"Free-text keywords."},"locations":{"type":"array","items":{"type":"string"},"description":"Company locations. A single string is accepted too."},"employee_ranges":{"type":"array","items":{"type":"string"},"description":"Company headcount ranges. A single string is accepted too."},"technologies":{"type":"array","items":{"type":"string"},"description":"Technologies the company uses. A single string is accepted too."},"domains":{"type":"array","items":{"type":"string"},"description":"Company domains. A single string is accepted too."},"revenue_min":{"type":"number","description":"Minimum annual revenue, ignored unless above 0."},"revenue_max":{"type":"number","description":"Maximum annual revenue, ignored unless above 0."},"page":{"type":"integer","description":"Results page."},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}},"anyOf":[{"required":["keywords"]},{"required":["locations"]},{"required":["employee_ranges"]},{"required":["technologies"]},{"required":["domains"]},{"required":["revenue_min"]},{"required":["revenue_max"]}]},"examples":{"default":{"value":{"keywords":"fintech","locations":["London"]}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_FILTERS`: No filter was sent; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/linkedin-profile-lookup":{"post":{"operationId":"lookupLinkedinProfile","summary":"Look up a LinkedIn profile","description":"Returns the public profile behind a LinkedIn profile URL. Costs 10 credits, and nothing when there is no match.","tags":["Enrichment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["profile_url"],"properties":{"profile_url":{"type":"string","description":"Public LinkedIn profile URL (https://www.linkedin.com/in/...) or its bare username. Also accepted as `profileUrl`, `linkedin_url`, `linkedinUrl`, `url`, `username` or `vanity`."},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}}},"examples":{"default":{"value":{"profile_url":"https://www.linkedin.com/in/example/"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_PROFILE_URL`: No profile URL was sent; `INVALID_PROFILE_URL`: The value is not a public LinkedIn profile URL; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/linkedin-company-lookup":{"post":{"operationId":"lookupLinkedinCompany","summary":"Look up a LinkedIn company page","description":"Returns the public company page behind a LinkedIn company URL or a company name: website, industry, headcount, size band, followers, founded year, headquarters and locations. Costs 10 credits, charged only on a match.","tags":["Enrichment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"company_url":{"type":"string","description":"Public LinkedIn company page URL or its slug. Also accepted as `companyUrl`, `linkedin_url`, `linkedinUrl`, `url`, `universal_name`, `universalName` or `slug`."},"company_name":{"type":"string","description":"Company name, 2 to 120 characters, for a best-match search. Used only when no company_url is sent. Also accepted as `companyName` or `name`."},"bypass_cache":{"type":"boolean","default":false,"description":"Skip the 7-day result cache and run a fresh lookup. Also accepted as `bypassCache` or `forceFresh`, in the body or the query string. A cached result you ran yourself is free; a fresh lookup is charged as usual."}},"anyOf":[{"required":["company_url"]},{"required":["company_name"]}]},"examples":{"default":{"value":{"company_url":"https://www.linkedin.com/company/microsoft"}}}}}},"responses":{"200":{"description":"Lookup completed. `metadata.credits_used` says what it cost.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/LookupResult"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `MISSING_COMPANY_URL`: Neither company_url nor company_name was sent; `INVALID_COMPANY_URL`: company_url is not a LinkedIn company page URL or slug; `INVALID_COMPANY_NAME`: company_name is not 2 to 120 characters; `VALIDATION_FAILED`: The lookup could not be completed for this input. Nothing was charged; `UPSTREAM_ERROR`: The source could not answer for this input. Nothing was charged","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"`INSUFFICIENT_CREDITS`: Not enough credits for the request","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds; `SERVICE_BUSY`: The service is busy. Nothing was reserved or charged; retry after `Retry-After` seconds; `UPSTREAM_QUOTA_EXHAUSTED`: The lookup is temporarily unavailable on our side. Nothing was charged; retry after `Retry-After` seconds; `UPSTREAM_TIMEOUT`: The source took too long to answer. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/account":{"get":{"operationId":"getAccount","summary":"Account status and credit balance","description":"Returns the organization, subscription, credit balance and usage for the calling API key. Free: this call spends no credits.","tags":["Account"],"responses":{"200":{"description":"Account status.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/Account"}}}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`NOT_FOUND`: Resource not found","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/bulk/jobs":{"post":{"operationId":"createBulkJob","summary":"Start a bulk job","description":"Runs one product over up to 100,000 inputs in the background. Each row costs what a single lookup costs; the account must hold enough credits for every row up front. Poll the status, read the results page by page, or pass `webhook_url` to be called when the job completes.","tags":["Bulk"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Send the same key on a retry to get the original job back instead of a second, charged job."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["hlr_lookup","nt_lookup","mnp_lookup","email_validation","reverse_email_append","domain_authority","domain_age","backlink_overview","keyword_metrics","company_firmographics","b2b_contact_append","business_verify","business_lookup","company_profile_lookup","linkedin_profile_lookup","linkedin_company_lookup","linkedin_email_finder","social_profile_check","property_lookup","social_post_lookup","video_transcript","audience_demographics","link_in_bio_lookup"],"description":"Product to run. `email_validation` is email verification."},"inputs":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":100000,"description":"One input per row, in the form the product's single-lookup endpoint takes: a phone number, an email address, a domain, a URL and so on."},"webhook_url":{"type":"string","description":"https URL to call when the job completes. Optional."}},"required":["type","inputs"]},"examples":{"default":{"value":{"type":"hlr_lookup","inputs":["+447700900123","+447700900456"]}}}}}},"responses":{"200":{"description":"Idempotent replay: a job with this `Idempotency-Key` already exists, and it is returned instead of a new one.","headers":{"Idempotent-Replay":{"schema":{"type":"string","enum":["true"]}},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/BulkJobCreated"}}}}}},"202":{"description":"Job accepted and processing.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/BulkJobCreated"}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `INVALID_TYPE`: `type` is not one of the bulk job types; `INVALID_INPUT`: The input does not match the expected format; `INPUT_LIMIT_EXCEEDED`: `inputs` has more than 100,000 rows; `INVALID_WEBHOOK_URL`: `webhook_url` is not an https URL that can receive webhooks","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"The account does not hold enough credits for every row. The body says how many are needed and suggests a plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkInsufficientCredits"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key; `UNSUPPORTED_AUTH_CONTEXT`: Bulk jobs need a direct API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`IDEMPOTENCY_CONFLICT`: A request with this `Idempotency-Key` is still being processed. Retry shortly; `ACCOUNT_CONFIGURATION_ERROR`: The organization has no active user to own the job","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/bulk/jobs/{id}":{"get":{"operationId":"getBulkJob","summary":"Bulk job status","description":"Progress counts for a bulk job, and its CSV once results exist. Free.","tags":["Bulk"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job status.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/BulkJobStatus"}}}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key; `UNSUPPORTED_AUTH_CONTEXT`: Bulk jobs need a direct API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`NOT_FOUND`: Resource not found","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/bulk/jobs/{id}/results":{"get":{"operationId":"getBulkJobResults","summary":"Bulk job results","description":"Row-by-row results of a bulk job, oldest first, one page at a time. The CSV links carry every row, including skipped and duplicate ones. Free.","tags":["Bulk"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"`pagination.next_cursor` from the previous page."}],"responses":{"200":{"description":"A page of results.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/BulkJobResults"}}}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key; `UNSUPPORTED_AUTH_CONTEXT`: Bulk jobs need a direct API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`NOT_FOUND`: Resource not found","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/monitors":{"post":{"operationId":"createMonitor","summary":"Create a number monitor","description":"Number Monitoring (beta): rechecks a list of phone numbers daily or weekly and records an event when status, line type, carrier, porting, DNC listing or spam risk changes. Creating and managing monitors is free; each recheck is charged like a phone validation, plus a spam check when `include_spam_check` is on. Up to 3 active monitors per account.","tags":["Monitoring"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":255,"description":"Monitor name, up to 255 characters."},"frequency":{"type":"string","enum":["daily","weekly"],"default":"daily"},"include_spam_check":{"type":"boolean","default":false,"description":"Also recheck spam risk."},"alert_email":{"type":"boolean","default":true,"description":"Email the account when a number changes."},"webhook_url":{"type":"string","description":"https URL to call on each change. The response carries a `webhook_secret` to verify the `X-1Lookup-Signature` header."}},"required":["name"]},"examples":{"default":{"value":{"name":"Sales line numbers","frequency":"daily"}}}}}},"responses":{"201":{"description":"Monitor created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"monitor":{"$ref":"#/components/schemas/NumberMonitor"},"webhook_secret":{"type":["string","null"],"description":"Returned once, at creation, when a webhook was set."}},"required":["monitor","webhook_secret"]}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `INVALID_INPUT`: The input does not match the expected format; `INVALID_WEBHOOK_URL`: `webhook_url` is not an https URL that can receive webhooks","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`LIMIT_REACHED`: An account or monitor limit was reached (active monitors, or numbers or contacts per monitor); `NO_LIST_OWNER`: The organization has no active owner or admin to own the monitor","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"operationId":"listMonitors","summary":"List number monitors","description":"Every number monitor on the account, newest first, with the account limits. Free.","tags":["Monitoring"],"responses":{"200":{"description":"Monitors.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"monitors":{"type":"array","items":{"$ref":"#/components/schemas/NumberMonitor"}},"limits":{"type":"object","properties":{"max_active_monitors":{"type":"integer"},"max_numbers_per_monitor":{"type":"integer"}}}},"required":["monitors","limits"]}}}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/monitors/{id}/numbers":{"post":{"operationId":"addMonitorNumbers","summary":"Add numbers to a monitor","description":"Adds phone numbers to a monitor, normalized to E.164. Duplicates and invalid entries are reported, not added. Up to 5,000 numbers per request and per monitor. Free.","tags":["Monitoring"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"numbers":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"object","properties":{"phone_number":{"type":"string"},"label":{"type":"string"}},"required":["phone_number"]}]},"minItems":1,"maxItems":5000,"description":"Phone numbers, as strings or as objects with an optional label."}},"required":["numbers"]},"examples":{"default":{"value":{"numbers":["+14155552671",{"phone_number":"+14155550123","label":"Front desk"}]}}}}}},"responses":{"200":{"description":"Numbers added.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"added":{"type":"integer"},"duplicates":{"type":"integer"},"invalid":{"type":"array","items":{"type":"object","properties":{"input":{"type":"string"},"error":{"type":"string"}}},"description":"Entries that were refused, with the reason."},"total":{"type":"integer","description":"Entries on the monitor now."}},"required":["added","duplicates","invalid","total"]}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `INVALID_INPUT`: The input does not match the expected format","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`NOT_FOUND`: Resource not found","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`LIMIT_REACHED`: An account or monitor limit was reached (active monitors, or numbers or contacts per monitor)","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"operationId":"removeMonitorNumbers","summary":"Remove numbers from a monitor","description":"Removes numbers by id or by phone number. Free.","tags":["Monitoring"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"number_ids":{"type":"array","items":{"type":"string"},"description":"Ids of monitored numbers."},"numbers":{"type":"array","items":{"type":"string"},"description":"Phone numbers. Also accepted as `phone_numbers`."}}},"examples":{"default":{"value":{"numbers":["+14155552671"]}}}}}},"responses":{"200":{"description":"Numbers removed.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"removed":{"type":"integer"}},"required":["removed"]}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `INVALID_INPUT`: The input does not match the expected format","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`NOT_FOUND`: Resource not found","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/monitors/{id}/events":{"get":{"operationId":"listMonitorEvents","summary":"Number monitor change feed","description":"Changes detected on a monitor's numbers, newest first. Free.","tags":["Monitoring"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"A page of events.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/NumberMonitorEvent"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"}},"required":["page","limit","total","total_pages"]}},"required":["events","pagination"]}}}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`NOT_FOUND`: Resource not found","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/job-change-monitors":{"post":{"operationId":"createJobChangeMonitor","summary":"Create a job change monitor","description":"Job Change Monitoring (beta): rechecks a list of public professional profiles weekly and records an event when someone changes company or title. Creating and managing monitors is free; each weekly recheck costs 5 credits per contact, and nothing for a profile that cannot be reached. Up to 3 active monitors per account.","tags":["Monitoring"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Monitor name."},"alert_email":{"type":"boolean","default":true,"description":"Email the account when a contact changes."},"webhook_url":{"type":"string","description":"https URL to call on each change. The response carries a `webhook_secret` to verify the `X-1Lookup-Signature` header."}},"required":["name"]},"examples":{"default":{"value":{"name":"Key champions"}}}}}},"responses":{"201":{"description":"Monitor created.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"monitor":{"$ref":"#/components/schemas/JobChangeMonitor"},"webhook_secret":{"type":["string","null"],"description":"Returned once, at creation, when a webhook was set."}},"required":["monitor","webhook_secret"]}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `INVALID_INPUT`: The input does not match the expected format; `INVALID_WEBHOOK_URL`: `webhook_url` is not an https URL that can receive webhooks","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`LIMIT_REACHED`: An account or monitor limit was reached (active monitors, or numbers or contacts per monitor); `NO_MONITOR_OWNER`: The organization has no active owner or admin to own the monitor","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"operationId":"listJobChangeMonitors","summary":"List job change monitors","description":"Every job change monitor on the account, newest first, with the account limits. Free.","tags":["Monitoring"],"responses":{"200":{"description":"Monitors.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"monitors":{"type":"array","items":{"$ref":"#/components/schemas/JobChangeMonitor"}},"limits":{"type":"object","properties":{"max_active_monitors":{"type":"integer"},"max_contacts_per_monitor":{"type":"integer"}}}},"required":["monitors","limits"]}}}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/job-change-monitors/{id}/contacts":{"post":{"operationId":"addJobChangeContacts","summary":"Add contacts to a job change monitor","description":"Adds public professional profile URLs to a monitor. Duplicates and invalid entries are reported, not added. Up to 500 contacts per monitor. Free.","tags":["Monitoring"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contacts":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"object","properties":{"profile_url":{"type":"string"},"label":{"type":"string"}},"required":["profile_url"]}]},"minItems":1,"description":"Profile URLs, as strings or as objects with an optional label."}},"required":["contacts"]},"examples":{"default":{"value":{"contacts":[{"profile_url":"https://www.linkedin.com/in/example/","label":"Example - Acme"}]}}}}}},"responses":{"200":{"description":"Contacts added.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"added":{"type":"integer"},"duplicates":{"type":"integer"},"invalid":{"type":"array","items":{"type":"object","properties":{"input":{"type":"string"},"error":{"type":"string"}}},"description":"Entries that were refused, with the reason."},"total":{"type":"integer","description":"Entries on the monitor now."}},"required":["added","duplicates","invalid","total"]}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `INVALID_INPUT`: The input does not match the expected format","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`NOT_FOUND`: Resource not found","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`LIMIT_REACHED`: An account or monitor limit was reached (active monitors, or numbers or contacts per monitor)","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"operationId":"removeJobChangeContacts","summary":"Remove contacts from a job change monitor","description":"Removes contacts by id or by profile URL. Free.","tags":["Monitoring"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_ids":{"type":"array","items":{"type":"string"},"description":"Ids of monitored contacts."},"contacts":{"type":"array","items":{"type":"string"},"description":"Profile URLs. Also accepted as `profile_urls`."}}},"examples":{"default":{"value":{"contacts":["https://www.linkedin.com/in/example/"]}}}}}},"responses":{"200":{"description":"Contacts removed.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"removed":{"type":"integer"}},"required":["removed"]}}}}}},"400":{"description":"`INVALID_REQUEST`: The body is not valid JSON; `INVALID_INPUT`: The input does not match the expected format","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`NOT_FOUND`: Resource not found","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/job-change-monitors/{id}/events":{"get":{"operationId":"listJobChangeEvents","summary":"Job change feed","description":"Job and title changes detected on a monitor's contacts, newest first. The first successful check of a contact records a `baseline` event, which is billed and never alerts. Free to read.","tags":["Monitoring"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"A page of events.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/JobChangeEvent"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"}},"required":["page","limit","total","total_pages"]}},"required":["events","pagination"]}}}}}},"401":{"description":"`UNAUTHORIZED`: Invalid or missing API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`UPGRADE_REQUIRED`: The account has no paid plan, and API access needs one. Upgrade at https://app.1lookup.io/billing?tab=plan; `INSUFFICIENT_SCOPE`: The call was signed with an AI connector (MCP) sign-in, which can only reach /phone, /email, /ip and /account. Use an API key","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`NOT_FOUND`: Resource not found","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`RATE_LIMIT_EXCEEDED`: Too many requests","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"`INTERNAL_ERROR`: Internal server error","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"`SERVICE_UNAVAILABLE`: The lookup service, or the API key check, is temporarily unavailable. Nothing was charged; retry after `Retry-After` seconds","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}