{
  "openapi": "3.0.3",
  "info": {
    "title": "Email Finder Verifier API",
    "version": "1",
    "description": "Verify work emails and find them from a name and a domain. Every call needs your API key in the X-API-Key header."
  },
  "servers": [
    {
      "url": "https://api.emailfinderverifier.com"
    }
  ],
  "tags": [
    {
      "name": "Verify"
    },
    {
      "name": "Find"
    },
    {
      "name": "Domain"
    },
    {
      "name": "Account"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Your API key from the dashboard."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "detail": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "What went wrong, in plain words."
              },
              "code": {
                "type": "string",
                "description": "A stable code you can branch on."
              }
            }
          }
        }
      },
      "Window": {
        "type": "object",
        "properties": {
          "per_second": {
            "type": "integer"
          },
          "per_minute": {
            "type": "integer"
          },
          "per_hour": {
            "type": "integer"
          },
          "per_day": {
            "type": "integer"
          },
          "max_concurrent": {
            "type": "integer"
          },
          "concurrent": {
            "type": "integer"
          }
        }
      }
    }
  },
  "paths": {
    "/api/v1/verify": {
      "get": {
        "summary": "Verify an email",
        "operationId": "verifyEmail",
        "tags": [
          "Verify"
        ],
        "description": "Checks whether one address is a real mailbox, without sending anything to it. `verified` is `true` only when the mailbox is confirmed. Catch-all, unknown and invalid addresses all return `false`, so `false` doesn't always mean the address is bad. Uses 1 request from your free allowance.",
        "parameters": [
          {
            "name": "email",
            "in": "query",
            "required": true,
            "description": "The address to check.",
            "schema": {
              "type": "string"
            },
            "example": "jane@acme.com"
          }
        ],
        "responses": {
          "200": {
            "description": "Result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "verified",
                    "esp"
                  ],
                  "properties": {
                    "verified": {
                      "type": "boolean",
                      "description": "true only when the mailbox is confirmed."
                    },
                    "esp": {
                      "type": "string",
                      "description": "The mail provider the domain uses.",
                      "enum": [
                        "Google",
                        "Outlook",
                        "Zoho",
                        "Yahoo",
                        "Proofpoint",
                        "Mimecast",
                        "Amazon SES",
                        "GoDaddy",
                        "Apple",
                        "Proton",
                        "Yandex",
                        "Rackspace",
                        "IONOS",
                        "Namecheap",
                        "Other"
                      ]
                    }
                  }
                },
                "example": {
                  "verified": true,
                  "esp": "Outlook"
                }
              }
            }
          },
          "400": {
            "description": "The email is missing or not an address (INVALID_EMAIL, INVALID_REQUEST).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": {
                    "error": "Invalid email address",
                    "code": "INVALID_EMAIL"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": {
                    "error": "Invalid or missing API key",
                    "code": "INVALID_API_KEY"
                  }
                }
              }
            }
          },
          "402": {
            "description": "Your free credits are used up.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": {
                    "error": "Out of credits. Your free credits are used up.",
                    "code": "OUT_OF_CREDITS"
                  }
                }
              }
            }
          },
          "403": {
            "description": "The account behind this key can't use the API right now (ACCOUNT_NOT_FOUND or ACCOUNT_NOT_ACTIVE).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": {
                    "error": "Account is paused",
                    "code": "ACCOUNT_NOT_ACTIVE"
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (RATE_LIMIT_EXCEEDED) or too many at once (CONCURRENT_LIMIT_EXCEEDED).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": {
                    "error": "Rate limit exceeded: 1/second. Upgrade tier for higher limits.",
                    "code": "RATE_LIMIT_EXCEEDED"
                  }
                }
              }
            }
          }
        },
        "x-mint": {
          "metadata": {
            "description": "Verify an email with the Email Finder Verifier API: check if one work address is a real mailbox without sending anything to it. Uses 1 request."
          }
        }
      }
    },
    "/api/v1/find": {
      "get": {
        "summary": "Find an email",
        "operationId": "findEmail",
        "tags": [
          "Find"
        ],
        "description": "Finds a person's work address from their name and company domain. Returns the address found, or `null` when none was found. Found addresses are not pre-verified: call /verify before you send. Uses 10 requests from your free allowance, only when an email is found.",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "description": "Company domain, like acme.com.",
            "schema": {
              "type": "string"
            },
            "example": "acme.com"
          },
          {
            "name": "first_name",
            "in": "query",
            "required": true,
            "description": "The person's first name.",
            "schema": {
              "type": "string"
            },
            "example": "Jane"
          },
          {
            "name": "last_name",
            "in": "query",
            "required": true,
            "description": "The person's last name.",
            "schema": {
              "type": "string"
            },
            "example": "Doe"
          },
          {
            "name": "linkedin_profile",
            "in": "query",
            "required": false,
            "description": "The person's LinkedIn profile URL. Please include it when you have it. Not mandatory.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "email",
                    "esp"
                  ],
                  "properties": {
                    "email": {
                      "type": "string",
                      "nullable": true,
                      "description": "The work email found, or null when none was found. Run it through /verify before you send."
                    },
                    "esp": {
                      "type": "string",
                      "description": "The mail provider the domain uses.",
                      "enum": [
                        "Google",
                        "Outlook",
                        "Zoho",
                        "Yahoo",
                        "Proofpoint",
                        "Mimecast",
                        "Amazon SES",
                        "GoDaddy",
                        "Apple",
                        "Proton",
                        "Yandex",
                        "Rackspace",
                        "IONOS",
                        "Namecheap",
                        "Other"
                      ]
                    }
                  }
                },
                "example": {
                  "email": "jane.doe@acme.com",
                  "esp": "Google"
                }
              }
            }
          },
          "400": {
            "description": "A required field is missing (MISSING_DOMAIN, MISSING_FIRST_NAME, MISSING_LAST_NAME, INVALID_REQUEST).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": {
                    "error": "Domain is required",
                    "code": "MISSING_DOMAIN"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": {
                    "error": "Invalid or missing API key",
                    "code": "INVALID_API_KEY"
                  }
                }
              }
            }
          },
          "402": {
            "description": "Your free credits are used up.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": {
                    "error": "Out of credits. Your free credits are used up.",
                    "code": "OUT_OF_CREDITS"
                  }
                }
              }
            }
          },
          "403": {
            "description": "The account behind this key can't use the API right now (ACCOUNT_NOT_FOUND or ACCOUNT_NOT_ACTIVE).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": {
                    "error": "Account is paused",
                    "code": "ACCOUNT_NOT_ACTIVE"
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (RATE_LIMIT_EXCEEDED) or too many at once (CONCURRENT_LIMIT_EXCEEDED).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": {
                    "error": "Rate limit exceeded: 1/second. Upgrade tier for higher limits.",
                    "code": "RATE_LIMIT_EXCEEDED"
                  }
                }
              }
            }
          }
        },
        "x-mint": {
          "metadata": {
            "description": "Find a person's work email from their name and company domain with the Email Finder Verifier API, then verify it with a second call."
          }
        }
      }
    },
    "/api/v1/generic-emails": {
      "get": {
        "summary": "Find generic inboxes",
        "operationId": "genericEmails",
        "tags": [
          "Find"
        ],
        "description": "Checks info@, hello@, contact@ and support@ at a domain and returns the ones that verify. Uses 4 requests from your free allowance.",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "description": "Company domain, like acme.com.",
            "schema": {
              "type": "string"
            },
            "example": "acme.com"
          }
        ],
        "responses": {
          "200": {
            "description": "Result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "domain",
                    "esp",
                    "verified_emails"
                  ],
                  "properties": {
                    "domain": {
                      "type": "string"
                    },
                    "esp": {
                      "type": "string",
                      "description": "The mail provider the domain uses.",
                      "enum": [
                        "Google",
                        "Outlook",
                        "Zoho",
                        "Yahoo",
                        "Proofpoint",
                        "Mimecast",
                        "Amazon SES",
                        "GoDaddy",
                        "Apple",
                        "Proton",
                        "Yandex",
                        "Rackspace",
                        "IONOS",
                        "Namecheap",
                        "Other"
                      ]
                    },
                    "verified_emails": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "The generic addresses that verified. Empty when none did."
                    }
                  }
                },
                "example": {
                  "domain": "acme.com",
                  "esp": "Outlook",
                  "verified_emails": [
                    "support@acme.com"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The domain is missing (MISSING_DOMAIN).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": {
                    "error": "Domain is required",
                    "code": "MISSING_DOMAIN"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": {
                    "error": "Invalid or missing API key",
                    "code": "INVALID_API_KEY"
                  }
                }
              }
            }
          },
          "402": {
            "description": "Your free credits are used up.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": {
                    "error": "Out of credits. Your free credits are used up.",
                    "code": "OUT_OF_CREDITS"
                  }
                }
              }
            }
          },
          "403": {
            "description": "The account behind this key can't use the API right now (ACCOUNT_NOT_FOUND or ACCOUNT_NOT_ACTIVE).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": {
                    "error": "Account is paused",
                    "code": "ACCOUNT_NOT_ACTIVE"
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (RATE_LIMIT_EXCEEDED) or too many at once (CONCURRENT_LIMIT_EXCEEDED).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": {
                    "error": "Rate limit exceeded: 1/second. Upgrade tier for higher limits.",
                    "code": "RATE_LIMIT_EXCEEDED"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/domain": {
      "get": {
        "summary": "Look up a domain",
        "operationId": "domainLookup",
        "tags": [
          "Domain"
        ],
        "description": "Tells you about a company domain: its mail provider, whether it's catch-all, its age and whether its website is up. The catch-all answer is kept for 7 days.",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "description": "Company domain, like acme.com.",
            "schema": {
              "type": "string"
            },
            "example": "acme.com"
          },
          {
            "name": "include_catchall",
            "in": "query",
            "required": false,
            "description": "Check whether the domain is catch-all. Defaults to true.",
            "schema": {
              "type": "boolean",
              "default": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "domain": {
                      "type": "string"
                    },
                    "esp": {
                      "type": "string",
                      "nullable": true,
                      "description": "The mail provider, by product name (for example \"Google Workspace\")."
                    },
                    "domain_age_years": {
                      "type": "number",
                      "nullable": true
                    },
                    "is_catchall": {
                      "type": "boolean",
                      "nullable": true,
                      "description": "true when the domain accepts mail for any address. null when it couldn't be checked or include_catchall=false."
                    },
                    "has_active_website": {
                      "type": "boolean",
                      "nullable": true
                    },
                    "redirects": {
                      "type": "boolean",
                      "nullable": true
                    },
                    "redirects_to": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                },
                "example": {
                  "domain": "acme.com",
                  "esp": "Google Workspace",
                  "domain_age_years": 12.4,
                  "is_catchall": true,
                  "has_active_website": true,
                  "redirects": true,
                  "redirects_to": "https://www.acme.com/"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": {
                    "error": "Invalid or missing API key",
                    "code": "INVALID_API_KEY"
                  }
                }
              }
            }
          },
          "402": {
            "description": "Your free credits are used up.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": {
                    "error": "Out of credits. Your free credits are used up.",
                    "code": "OUT_OF_CREDITS"
                  }
                }
              }
            }
          },
          "403": {
            "description": "The account behind this key can't use the API right now (ACCOUNT_NOT_FOUND or ACCOUNT_NOT_ACTIVE).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": {
                    "error": "Account is paused",
                    "code": "ACCOUNT_NOT_ACTIVE"
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests (RATE_LIMIT_EXCEEDED) or too many at once (CONCURRENT_LIMIT_EXCEEDED).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": {
                    "error": "Rate limit exceeded: 1/second. Upgrade tier for higher limits.",
                    "code": "RATE_LIMIT_EXCEEDED"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/credits": {
      "get": {
        "summary": "Check your balance",
        "operationId": "credits",
        "tags": [
          "Account"
        ],
        "description": "How many verifications and finds you have left. Free to call.",
        "responses": {
          "200": {
            "description": "Your balance.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verify_requests_left": {
                      "type": "integer",
                      "nullable": true
                    },
                    "emails_you_can_find": {
                      "type": "integer",
                      "nullable": true
                    },
                    "credits_left": {
                      "type": "integer",
                      "nullable": true
                    },
                    "unlimited": {
                      "type": "boolean"
                    }
                  }
                },
                "example": {
                  "verify_requests_left": 100000,
                  "emails_you_can_find": 10000,
                  "credits_left": 10000,
                  "unlimited": false
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "detail": {
                    "error": "Invalid or missing API key",
                    "code": "INVALID_API_KEY"
                  }
                }
              }
            }
          }
        },
        "x-mint": {
          "metadata": {
            "description": "Check your Email Finder Verifier API balance: how many verifications and email finds you have left. This call is free and uses no balance."
          }
        }
      }
    },
    "/api/v1/rate-limit": {
      "get": {
        "summary": "Check your rate limits",
        "operationId": "rateLimit",
        "tags": [
          "Account"
        ],
        "description": "Your limits and how much of each you've used right now. Free to call.",
        "responses": {
          "200": {
            "description": "Limits and usage.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tier": {
                      "type": "string"
                    },
                    "limits": {
                      "$ref": "#/components/schemas/Window"
                    },
                    "usage": {
                      "$ref": "#/components/schemas/Window"
                    }
                  }
                },
                "example": {
                  "tier": "free",
                  "limits": {
                    "per_second": 1,
                    "per_minute": 90,
                    "per_hour": 100000,
                    "per_day": 5000000,
                    "max_concurrent": 5
                  },
                  "usage": {
                    "per_second": 0,
                    "per_minute": 3,
                    "per_hour": 41,
                    "per_day": 41,
                    "concurrent": 0
                  }
                }
              }
            }
          }
        },
        "x-mint": {
          "metadata": {
            "description": "Check your Email Finder Verifier API rate limits and how much of each limit you've used right now. This call is free and uses no balance."
          }
        }
      }
    }
  }
}
