{"openapi":"3.1.0","info":{"title":"veridock.io API","version":"1.0.0","description":"Email verification: syntax, MX and disposable-domain checks with explicit uncertainty."},"servers":[{"url":"https://app.veridock.io"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from the dashboard (vd_live_…)."}},"schemas":{"VerificationResult":{"type":"object","properties":{"email":{"type":"string"},"normalized":{"type":["string","null"]},"domain":{"type":["string","null"]},"status":{"type":"string","enum":["valid","invalid","disposable","risky","unknown"]},"reason":{"type":"string","enum":["deliverable_domain","invalid_syntax","no_mx_records","disposable_domain","role_account","dns_timeout","dns_error"]},"checks":{"type":"object","properties":{"syntax":{"type":"string","enum":["valid","invalid"]},"mx":{"type":"string","enum":["present","absent","unknown"]},"disposable":{"type":"boolean"},"role":{"type":"boolean"},"free_provider":{"type":"boolean"},"mailbox":{"type":"string","enum":["not_probed"]}}},"mx_hosts":{"type":"array","items":{"type":"string"}},"suggestion":{"type":["string","null"]},"disposable_dataset_version":{"type":["string","null"]},"took_ms":{"type":"integer"},"credits_used":{"type":"integer"},"credits_remaining":{"type":"integer"},"request_id":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"BulkJob":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["queued","processing","completed","failed"]},"total":{"type":"integer"},"processed":{"type":"integer"},"counts":{"type":"object","additionalProperties":{"type":"integer"}},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"}}},"FindResult":{"type":"object","properties":{"mode":{"type":"string","enum":["person","company"]},"name":{"type":"string"},"domain_info":{"type":"object","properties":{"domain":{"type":"string"},"mx":{"type":"string","enum":["present","absent","unknown"]},"mx_hosts":{"type":"array","items":{"type":"string"}},"provider":{"type":["string","null"]},"disposable":{"type":"boolean"},"free_provider":{"type":"boolean"},"mailbox":{"type":"string","enum":["not_probed"]}}},"best":{"type":["object","null"]},"candidates":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"pattern":{"type":"string"},"score":{"type":"number"},"confidence":{"type":"string","enum":["high","medium","low"]},"verified":{"type":"boolean"}}}},"evidence":{"type":"object","properties":{"known_addresses":{"type":"integer"},"inferred_pattern":{"type":["string","null"]}}},"pattern":{"type":"object"},"known_addresses":{"type":"array","items":{"type":"object"}},"role_addresses":{"type":"array","items":{"type":"string"}},"took_ms":{"type":"integer"},"credits_used":{"type":"integer"},"credits_remaining":{"type":"integer"},"request_id":{"type":"string"}}}}},"paths":{"/v1/verify":{"post":{"summary":"Verify a single email address","description":"Costs 1 credit. Send an `Idempotency-Key` header to make retries free.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"}}}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationResult"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing / invalid API key"},"402":{"description":"Insufficient credits"},"429":{"description":"Rate limited (see retry_after_ms)"}}}},"/v1/find":{"post":{"summary":"Find a person's email pattern or a company's mail setup","description":"Costs 5 credits. With `name`, returns ranked candidate addresses for that person at `domain`; without, returns the domain's mail provider and inferred address pattern. Candidates are pattern-based and never SMTP-probed; `confidence` is `high` only for addresses you previously verified in a list.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"name":{"type":"string"},"domain":{"type":"string"}}}}}},"responses":{"200":{"description":"Result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindResult"}}}},"400":{"description":"Invalid name or domain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing / invalid API key"},"402":{"description":"Insufficient credits"}}}},"/v1/account":{"get":{"summary":"Account and plan details","responses":{"200":{"description":"Account"}}}},"/v1/account/usage":{"get":{"summary":"Remaining credits and usage this cycle","responses":{"200":{"description":"Usage"}}}},"/v1/bulk/verify":{"post":{"summary":"Submit a list for verification","description":"Reserves one credit per unique address atomically, then processes asynchronously.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["emails"],"properties":{"emails":{"type":"array","items":{"type":"string"},"maxItems":50000},"name":{"type":"string"}}}}}},"responses":{"202":{"description":"Job accepted","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/BulkJob"}}}}}},"402":{"description":"Insufficient credits"}}}},"/v1/bulk/jobs/{id}":{"get":{"summary":"Bulk job status (and results with ?results=1)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"results","in":"query","schema":{"type":"string","enum":["1"]}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":1000}},{"name":"offset","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Job"},"404":{"description":"Not found"}}}}}}