{"openapi":"3.1.0","info":{"title":"Nose for Leads API","description":"Verified local-business leads for humans and agents. 1 credit = 1 validated lead; every returned email carries a verification receipt (verified_by/verified_at). Authenticate with X-API-Key or Bearer.","version":"1.0"},"paths":{"/v1/campaigns":{"post":{"summary":"Submit a campaign (1 credit per validated lead; supports idempotency_key)","operationId":"submit_campaign_v1_campaigns_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitCampaignBody"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"200":{"description":"Idempotent replay: an identical idempotency_key was already submitted — returns the original job_id."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"summary":"List your campaigns, with pagination/search/status filters","operationId":"list_campaigns_v1_campaigns_get","parameters":[{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Q"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["queued","running","done","done_partial","failed"],"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"order","in":"query","required":false,"schema":{"enum":["asc","desc"],"type":"string","default":"desc","title":"Order"}},{"name":"created_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created After"}},{"name":"created_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created Before"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/campaigns/{job_id}":{"get":{"summary":"Get one campaign's status and credit spend","operationId":"campaign_status_v1_campaigns__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/campaigns/{job_id}/results":{"get":{"summary":"Get validated leads for a campaign, each with a verification receipt (JSON or CSV)","operationId":"campaign_results_v1_campaigns__job_id__results_get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"format","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Format"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":100,"title":"Limit"}},{"name":"kept_only","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Kept Only"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/campaigns/{job_id}/results/{result_id}":{"patch":{"summary":"Mark one lead as kept/discarded/unreviewed","operationId":"patch_review_status_v1_campaigns__job_id__results__result_id__patch","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"result_id","in":"path","required":true,"schema":{"type":"integer","title":"Result Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewBody"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/suppressions":{"post":{"summary":"Suppress an email/domain from future results (never contact again)","operationId":"add_suppression_v1_suppressions_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuppressionBody"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/packs":{"get":{"summary":"List purchasable credit packs and prices","operationId":"get_packs_v1_packs_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/usage":{"get":{"summary":"Get today's usage against your daily quota","operationId":"usage_today_v1_usage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/translate":{"post":{"summary":"Translate a free-text ICP description into a structured query","operationId":"translate_icp_v1_translate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslateBody"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/credits":{"get":{"summary":"Get credit balance and ledger history","operationId":"get_credits_v1_credits_get","parameters":[{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/credits/checkout":{"post":{"summary":"Create a Stripe Checkout session to buy a credit pack","operationId":"create_checkout_v1_credits_checkout_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutBody"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/billing/setup-intent":{"post":{"summary":"Create a Stripe SetupIntent to attach a card","operationId":"billing_setup_intent_v1_billing_setup_intent_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/billing/card":{"get":{"summary":"Check whether a card is attached to your account","operationId":"billing_card_status_v1_billing_card_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"summary":"Attach a confirmed card (via setup_intent_id) to your account","operationId":"billing_attach_card_v1_billing_card_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AttachCardBody"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/keys":{"get":{"summary":"List your API keys (JWT-authenticated dashboard callers only)","operationId":"list_keys_v1_keys_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"post":{"summary":"Mint a new API key, optionally with spend budgets/expiry (JWT-authenticated only)","operationId":"mint_key_route_v1_keys_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MintKeyBody"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/keys/{key_prefix}":{"delete":{"summary":"Revoke an API key by its prefix (JWT-authenticated only)","operationId":"revoke_key_route_v1_keys__key_prefix__delete","parameters":[{"name":"key_prefix","in":"path","required":true,"schema":{"type":"string","title":"Key Prefix"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/oauth/authorize":{"post":{"summary":"Grant an OAuth client access to your account (JWT-authenticated only): creates a one-time authorization code","operationId":"oauth_authorize_route_v1_oauth_authorize_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthAuthorizeBody"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/oauth/client/{client_id}":{"get":{"summary":"Look up an OAuth client's display name (JWT-authenticated only) — the consent page's lookup","operationId":"oauth_client_route_v1_oauth_client__client_id__get","parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","title":"Client Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/stripe/webhook":{"post":{"summary":"Stripe webhook receiver (auth-exempt: verified by signature)","operationId":"stripe_webhook_v1_stripe_webhook_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/email/prefs":{"get":{"summary":"Get your marketing/digest email preferences","operationId":"get_email_prefs_v1_email_prefs_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"put":{"summary":"Update your marketing/digest email preferences","operationId":"put_email_prefs_v1_email_prefs_put","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailPrefsBody"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/email/unsubscribe":{"post":{"summary":"Unsubscribe from marketing email via a signed link token (auth-exempt)","operationId":"email_unsubscribe_v1_email_unsubscribe_post","parameters":[{"name":"token","in":"query","required":false,"schema":{"type":"string","default":"","title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/privacy/removal":{"post":{"summary":"Request removal of your email/domain from our data (auth-exempt, rate-limited)","operationId":"privacy_removal_v1_privacy_removal_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrivacyRemovalBody"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/email/resend-webhook":{"post":{"summary":"Resend webhook receiver: bounces/complaints suppress marketing (auth-exempt: svix-signed)","operationId":"resend_webhook_v1_email_resend_webhook_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/oauth-protected-resource":{"get":{"summary":"Protected Resource Metadata","operationId":"protected_resource_metadata__well_known_oauth_protected_resource_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/oauth-authorization-server":{"get":{"summary":"Authorization Server Metadata","operationId":"authorization_server_metadata__well_known_oauth_authorization_server_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/oauth/register":{"post":{"summary":"Register Client","operationId":"register_client_oauth_register_post","responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/oauth/token":{"post":{"summary":"Token","operationId":"token_oauth_token_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"AttachCardBody":{"properties":{"setup_intent_id":{"type":"string","title":"Setup Intent Id"}},"type":"object","required":["setup_intent_id"],"title":"AttachCardBody"},"CheckoutBody":{"properties":{"pack_id":{"type":"string","title":"Pack Id"}},"type":"object","required":["pack_id"],"title":"CheckoutBody"},"EmailPrefsBody":{"properties":{"marketing_opt_out":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Marketing Opt Out"},"digest_opt_out":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Digest Opt Out"}},"type":"object","title":"EmailPrefsBody"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"MintKeyBody":{"properties":{"label":{"type":"string","title":"Label"},"budget_total_credits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Budget Total Credits"},"budget_daily_credits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Budget Daily Credits"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"}},"type":"object","required":["label"],"title":"MintKeyBody"},"OAuthAuthorizeBody":{"properties":{"client_id":{"type":"string","title":"Client Id"},"redirect_uri":{"type":"string","title":"Redirect Uri"},"state":{"type":"string","title":"State"},"code_challenge":{"type":"string","title":"Code Challenge"},"resource":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource"},"budget_total_credits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Budget Total Credits"},"budget_daily_credits":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Budget Daily Credits"}},"type":"object","required":["client_id","redirect_uri","state","code_challenge"],"title":"OAuthAuthorizeBody"},"PrivacyRemovalBody":{"properties":{"email":{"type":"string","title":"Email"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"action":{"type":"string","enum":["opt_out","delete"],"title":"Action"}},"type":"object","required":["email","action"],"title":"PrivacyRemovalBody"},"ReviewBody":{"properties":{"review_status":{"type":"string","enum":["kept","discarded","unreviewed"],"title":"Review Status"}},"type":"object","required":["review_status"],"title":"ReviewBody"},"SubmitCampaignBody":{"properties":{"vertical":{"type":"string","title":"Vertical"},"geo":{"type":"string","title":"Geo"},"query":{"additionalProperties":true,"type":"object","title":"Query"},"idempotency_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency Key"}},"type":"object","required":["vertical","geo","query"],"title":"SubmitCampaignBody"},"SuppressionBody":{"properties":{"scope":{"type":"string","title":"Scope"},"value":{"type":"string","title":"Value"},"reason":{"type":"string","title":"Reason","default":""}},"type":"object","required":["scope","value"],"title":"SuppressionBody"},"TranslateBody":{"properties":{"text":{"type":"string","title":"Text"}},"type":"object","required":["text"],"title":"TranslateBody"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}