{ "openapi": "3.1.0", "info": { "title": "Encrata API", "version": "1.0.0", "summary": "Email intelligence API for AI agents, developers and humans.", "description": "Turns an email address into structured JSON: identity, work, company, socials, location, deliverability and breach exposure. Credit-based and pay-per-use. Canonical docs: https://encrata.com/ai/api.md\n\n## Versioning\nThe API is versioned. The current version is 1. Send an optional `Encrata-Version` request header (date or integer, e.g. `2026-08-01`) to pin behaviour; omit it to use the latest stable version. Breaking changes ship under a new version.\n\n## Deprecation policy\nDeprecated operations return a `Deprecation: true` header and a `Sunset` header (RFC 8594) with the removal date, at least 180 days in advance. Deprecations are also announced at https://docs.encrata.com/changelog.", "contact": { "name": "Encrata Support", "email": "support@encrata.com", "url": "https://docs.encrata.com" } }, "servers": [ { "url": "https://encrata.com/api", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/lookup": { "post": { "operationId": "lookup", "summary": "Full person profile from an email address (1,000 credits).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LookupRequest" } } } }, "responses": { "200": { "description": "Merged person profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonProfile" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "description": "Resolve an email address into a full person profile: identity, work, company, social profiles, location, deliverability and breach exposure. Costs 1,000 credits; identical requests within 24 hours are served free from cache.", "parameters": [ { "name": "Encrata-Version", "in": "header", "required": false, "schema": { "type": "string", "example": "2026-08-01" }, "description": "Optional API version pin (date or integer). Omit for latest stable." } ] } }, "/email/validity": { "post": { "operationId": "emailValidity", "summary": "Deliverability verdict (1 credit).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailRequest" } } } }, "responses": { "200": { "description": "Validity verdict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidityResult" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "description": "Return a deliverability verdict for an email address without sending mail. Costs 1 credit.", "parameters": [ { "name": "Encrata-Version", "in": "header", "required": false, "schema": { "type": "string", "example": "2026-08-01" }, "description": "Optional API version pin (date or integer). Omit for latest stable." } ] } }, "/email/smtp-verify": { "post": { "operationId": "smtpVerify", "summary": "Live mailbox existence check (1 credit).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailRequest" } } } }, "responses": { "200": { "description": "Mailbox verification result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SmtpVerifyResult" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "description": "Perform a live SMTP mailbox-existence probe without delivering a message. Costs 1 credit.", "parameters": [ { "name": "Encrata-Version", "in": "header", "required": false, "schema": { "type": "string", "example": "2026-08-01" }, "description": "Optional API version pin (date or integer). Omit for latest stable." } ] } }, "/email/breaches": { "post": { "operationId": "emailBreaches", "summary": "Known data-breach exposure for an address (1 credit).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailRequest" } } } }, "responses": { "200": { "description": "Breach record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BreachResult" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "description": "List the known data breaches an email address appears in, with dates and exposed data classes. Costs 1 credit.", "parameters": [ { "name": "Encrata-Version", "in": "header", "required": false, "schema": { "type": "string", "example": "2026-08-01" }, "description": "Optional API version pin (date or integer). Omit for latest stable." } ] } }, "/email/password-breaches": { "post": { "operationId": "passwordBreaches", "summary": "k-anonymity password leak check (1 credit). Send a hash fragment; the password never leaves your side.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "hash_prefix" ], "properties": { "hash_prefix": { "type": "string", "description": "First 5 characters of the SHA-1 hash of the password." } } } } } }, "responses": { "200": { "description": "Match count for the supplied hash prefix.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasswordBreachResult" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "description": "Check whether a password appears in known breach corpora using k-anonymity. Send only the first 5 characters of the SHA-1 hash; the password never leaves your side. Costs 1 credit.", "parameters": [ { "name": "Encrata-Version", "in": "header", "required": false, "schema": { "type": "string", "example": "2026-08-01" }, "description": "Optional API version pin (date or integer). Omit for latest stable." } ] } }, "/bulk-lookup": { "post": { "operationId": "bulkLookup", "summary": "Enrich up to 1M rows; billed per row. Poll the job or receive a webhook.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string", "format": "email" } } } } } } }, "responses": { "202": { "description": "Job accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkJob" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "description": "Enrich up to 1,000,000 email addresses in one job, billed per row. Poll the returned job or receive a webhook when it completes.", "parameters": [ { "name": "Encrata-Version", "in": "header", "required": false, "schema": { "type": "string", "example": "2026-08-01" }, "description": "Optional API version pin (date or integer). Omit for latest stable." } ] } }, "/credits": { "get": { "operationId": "getCredits", "summary": "Current credit balance. Costs nothing.", "responses": { "200": { "description": "Credit balance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "credits": { "type": "integer" }, "workspace_id": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Error" }, "400": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "500": { "$ref": "#/components/responses/Error" } }, "description": "Return the current credit balance for the authenticated workspace. This call costs nothing.", "parameters": [ { "name": "Encrata-Version", "in": "header", "required": false, "schema": { "type": "string", "example": "2026-08-01" }, "description": "Optional API version pin (date or integer). Omit for latest stable." } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key with prefix enc_live_. Get one at https://app.encrata.com/settings/api-keys Keys are workspace-scoped and can be restricted to named scopes: read:lookup, read:validity, read:breaches, write:bulk, read:credits. Machine-readable scope list: https://encrata.com/.well-known/oauth-protected-resource" } }, "responses": { "Error": { "description": "Error response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "LookupRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "fields": { "type": "array", "items": { "type": "string" }, "description": "Optional. Restrict the response to the named top-level sections." } } }, "EmailRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } }, "PersonProfile": { "type": "object", "required": [ "request_id", "email" ], "properties": { "request_id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "validity": { "$ref": "#/components/schemas/ValidityResult" }, "identity": { "type": "object" }, "work": { "type": "object" }, "company": { "type": "object" }, "social": { "type": "array", "items": { "type": "object" } }, "location": { "type": "object" }, "breaches": { "$ref": "#/components/schemas/BreachResult" } } }, "ValidityResult": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "valid", "invalid", "catch_all", "risky", "unknown" ] }, "confidence": { "type": "string" }, "disposable": { "type": "boolean" }, "free_provider": { "type": "boolean" }, "role_address": { "type": "boolean" }, "catch_all": { "type": "boolean" } } }, "BreachResult": { "type": "object", "properties": { "count": { "type": "integer" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "year": { "type": "integer" }, "exposed": { "type": "array", "items": { "type": "string" } } } } } } }, "BulkJob": { "type": "object", "properties": { "job_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "done", "failed" ] }, "rows": { "type": "integer" }, "completed": { "type": "integer" }, "result_url": { "type": "string" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "request_id": { "type": "string" }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "invalid_email", "invalid_input", "unauthorized", "insufficient_credits", "not_found", "rate_limited", "server_error" ] }, "message": { "type": "string" } } } } }, "SmtpVerifyResult": { "type": "object", "properties": { "deliverable": { "type": "boolean", "description": "Mailbox accepts mail." }, "smtp_code": { "type": "integer", "description": "SMTP response code from the mail server." }, "catch_all": { "type": "boolean" }, "disposable": { "type": "boolean" } } }, "PasswordBreachResult": { "type": "object", "properties": { "found": { "type": "boolean", "description": "Password appears in a known breach." }, "count": { "type": "integer", "description": "Number of times the password was seen across breaches." } } } } } }