{
  "openapi": "3.0.0",
  "info": {
    "title": "Enrichley API",
    "version": "1.0.0",
    "description": "API for verifying email addresses (including catch-all domains) and enriching LinkedIn profile URLs."
  },
  "servers": [
    {
      "url": "https://api.enrichley.io/api/v1",
      "description": "Production"
    }
  ],
  "paths": {
    "/me": {
      "get": {
        "summary": "Check Credits",
        "description": "Check available credits for the authenticated user.",
        "operationId": "checkCredits",
        "tags": [
          "Credits"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successful credits retrieval.",
            "headers": {
              "x-ratelimit-limit": {
                "description": "Maximum number of requests allowed in the current rate limit window.",
                "schema": {
                  "type": "integer",
                  "example": 100
                }
              },
              "x-ratelimit-remaining": {
                "description": "Number of requests remaining in the current rate limit window.",
                "schema": {
                  "type": "integer",
                  "example": 99
                }
              },
              "x-ratelimit-reset": {
                "description": "Unix timestamp in milliseconds when the current rate limit window resets.",
                "schema": {
                  "type": "integer",
                  "format": "int64",
                  "example": 1700000000000
                }
              },
              "x-credits-remaining": {
                "description": "Number of credits remaining on your account after this request.",
                "schema": {
                  "type": "integer",
                  "example": 999999
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "credits": {
                      "type": "integer",
                      "description": "Total remaining credits for the authenticated account."
                    }
                  },
                  "required": [
                    "credits"
                  ]
                },
                "example": {
                  "credits": 999999
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing API key."
          },
          "429": {
            "description": "Rate limit exceeded."
          },
          "500": {
            "description": "Server error."
          }
        }
      }
    },
    "/validate-single-email": {
      "post": {
        "summary": "Email Validation",
        "description": "Validate a single email address and return its validation and enrichment status. Response headers include rate limit and credits information: `x-ratelimit-limit`, `x-ratelimit-remaining`, `x-ratelimit-reset`, and `x-credits-remaining`.",
        "operationId": "emailValidation",
        "tags": [
          "People Enrichment"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "The email address to validate."
                  }
                },
                "required": [
                  "email"
                ]
              },
              "example": {
                "email": "jane.doe@example.com"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Email validation and enrichment result.",
            "headers": {
              "x-ratelimit-limit": {
                "description": "Maximum number of requests allowed in the current rate limit window.",
                "schema": {
                  "type": "integer",
                  "example": 100
                }
              },
              "x-ratelimit-remaining": {
                "description": "Number of requests remaining in the current rate limit window.",
                "schema": {
                  "type": "integer",
                  "example": 99
                }
              },
              "x-ratelimit-reset": {
                "description": "Unix timestamp in milliseconds when the current rate limit window resets.",
                "schema": {
                  "type": "integer",
                  "format": "int64",
                  "example": 1700000000000
                }
              },
              "x-credits-remaining": {
                "description": "Number of credits remaining on your account after this request.",
                "schema": {
                  "type": "integer",
                  "example": 999999
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "email": {
                      "type": "string",
                      "format": "email",
                      "description": "The email address that was validated."
                    },
                    "valid": {
                      "type": "boolean",
                      "description": "Whether the email is considered deliverable."
                    },
                    "result": {
                      "type": "string",
                      "enum": [
                        "ok",
                        "catch_all_validated",
                        "catch_all",
                        "invalid",
                        "unknown"
                      ],
                      "description": "High-level validation result.\n\nPossible values:\n- `ok` — the email is valid ✅\n- `catch_all_validated` — the email is a catch-all but was validated ✅\n- `catch_all` — the email is a catch-all ❌\n- `invalid` — the email is invalid and should not be used ❌\n- `unknown` — the validation status could not be retrieved ❌"
                    },
                    "mx_domain": {
                      "type": "string",
                      "description": "MX domain used by your recipient's email."
                    },
                    "email_type": {
                      "type": "string",
                      "description": "Email type classification (for example, `business` or `personal`)."
                    },
                    "mx_provider": {
                      "type": "string",
                      "description": "MX provider used by your recpipient's email."
                    },
                    "credits_consumed": {
                      "type": "boolean",
                      "description": "Whether this request consumed a credit."
                    },
                    "mx_secure_email_gateway": {
                      "type": "boolean",
                      "description": "Whether your recipient's email is behind a secure email gateway."
                    }
                  },
                  "required": [
                    "email"
                  ]
                },
                "example": {
                  "email": "jane.doe@example.com",
                  "valid": true,
                  "result": "catch_all_validated",
                  "mx_domain": "example.com",
                  "email_type": "business",
                  "mx_provider": "example",
                  "credits_consumed": true,
                  "mx_secure_email_gateway": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or missing parameters."
          },
          "401": {
            "description": "Invalid or missing API key."
          },
          "429": {
            "description": "Rate limit exceeded."
          },
          "500": {
            "description": "Server error."
          }
        }
      }
    },
    "/profile-enrichment": {
      "post": {
        "summary": "Obtain information about a LinkedIn Profile URL",
        "description": "Get more information about a person or organization's LinkedIn profile URL.",
        "operationId": "profileEnrichment",
        "tags": [
          "Enrichment"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "linkedin_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "The LinkedIn profile URL to enrich."
                  }
                },
                "required": [
                  "linkedin_url"
                ]
              },
              "example": {
                "linkedin_url": "https://www.linkedin.com/in/john-doe/"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Profile enrichment result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true,
                  "properties": {
                    "first_name": {
                      "type": "string",
                      "description": "First name of the person, if available."
                    },
                    "last_name": {
                      "type": "string",
                      "description": "Last name of the person, if available."
                    },
                    "headline": {
                      "type": "string",
                      "description": "Headline or title from the profile."
                    },
                    "company": {
                      "type": "string",
                      "description": "Primary company associated with the profile."
                    }
                  }
                },
                "example": {
                  "first_name": "John",
                  "last_name": "Doe",
                  "headline": "VP of Sales at Acme",
                  "company": "Acme Corp"
                }
              }
            }
          },
          "400": {
            "description": "Invalid LinkedIn URL."
          },
          "401": {
            "description": "Invalid or missing API key."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key"
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ]
}