openapi: 3.0.3
info:
  title: PeopleDB API
  description: API for retrieving contact information and validating email addresses.
  version: 1.0.0
  contact:
    name: PeopleDB Support

servers:
  - url: https://peopledb.co/api/v1
    description: Production API

security:
  - BearerAuth: []

paths:
  /people:
    get:
      summary: Get contact info
      description: Retrieve contact information for a person by their LinkedIn ID, LinkedIn public identifier, GitHub ID, or GitHub login.
      operationId: getContactInfo
      tags:
        - Contact Info
      parameters:
        - name: linkedin_id
          in: query
          description: LinkedIn ID to search by
          required: false
          schema:
            type: integer
          example: 123456789
        - name: linkedin_public_identifier
          in: query
          description: LinkedIn public identifier (username) to search by
          required: false
          schema:
            type: string
          example: "johndoe"
        - name: github_id
          in: query
          description: GitHub ID to search by
          required: false
          schema:
            type: integer
          example: 12345
        - name: github_login
          in: query
          description: GitHub login (username) to search by
          required: false
          schema:
            type: string
          example: "johndoe"
      x-codeSamples:
        - lang: Shell
          label: Curl
          source: |
            curl "https://peopledb.co/api/v1/people?linkedin_public_identifier=johndoe" \
              --header "Authorization: Bearer YOUR_SECRET_TOKEN"
      responses:
        "200":
          description: Profile found successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContactInfo"
        "400":
          description: Bad request - missing required parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "One of linkedin_id, linkedin_public_identifier, github_id, or github_login is required"
        "401":
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "Unauthorized"
        "402":
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "Insufficient credits"
        "404":
          description: No profile found for the given parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "No profile found for the given parameters"

  /email_verifications:
    get:
      summary: Validate email address
      description: |
        Validate an email address and return detailed verification results.

        Performs comprehensive validation including:
        - Email syntax validation
        - MX record verification (DNS lookup)
        - SMTP deliverability check
        - Disposable email detection
        - Common domain typo suggestions
        - Detection of servers that accept any email
      operationId: getEmailVerification
      tags:
        - Email Verification
      x-codeSamples:
        - lang: Shell
          label: Curl
          source: |
            curl "https://peopledb.co/api/v1/email_verifications?email_address=user@example.com" \
              --header "Authorization: Bearer YOUR_SECRET_TOKEN"
      parameters:
        - name: email_address
          in: query
          description: Email address to validate
          required: true
          schema:
            type: string
            format: email
          example: "user@example.com"
        - name: smtp_timeout
          in: query
          description: SMTP check timeout in seconds
          required: false
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 60
          example: 10
      responses:
        "200":
          description: Email validation completed successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailVerificationResult"
        "400":
          description: Bad request - missing email_address parameter
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "Email address parameter is required"
        "401":
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "Unauthorized"

    post:
      summary: Validate email address
      description: |
        Validate an email address and return detailed verification results.

        This endpoint performs the same validation as GET but accepts parameters
        via request body or form data.
      operationId: createEmailVerification
      tags:
        - Email Verification
      x-codeSamples:
        - lang: Shell
          label: Curl
          source: |
            curl --request POST \
              "https://peopledb.co/api/v1/email_verifications?email_address=user@example.com" \
              --header "Authorization: Bearer YOUR_SECRET_TOKEN"
      parameters:
        - name: email_address
          in: query
          description: Email address to validate
          required: true
          schema:
            type: string
            format: email
          example: "user@example.com"
        - name: smtp_timeout
          in: query
          description: SMTP check timeout in seconds
          required: false
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 60
          example: 10
      responses:
        "200":
          description: Email validation completed successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailVerificationResult"
        "400":
          description: Bad request - missing email_address parameter
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "Email address parameter is required"
        "401":
          description: Unauthorized - invalid or missing bearer token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "Unauthorized"

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication

  schemas:
    ContactInfo:
      type: object
      description: Aggregated contact information for a person
      properties:
        linkedin_id:
          type: integer
          nullable: true
          description: LinkedIn ID
          example: 123456789
        linkedin_public_identifier:
          type: string
          nullable: true
          description: LinkedIn public identifier (username)
          example: "johndoe"
        github_id:
          type: integer
          nullable: true
          description: GitHub ID
          example: 12345
        github_login:
          type: string
          nullable: true
          description: GitHub login (username)
          example: "johndoe"
        email_addresses:
          type: array
          description: List of known email addresses. Only present when at least one address was found — absence means no email data is available.
          items:
            type: string
            format: email
          example:
            - "john.doe@example.com"
            - "johndoe@company.com"
        personal_email_addresses:
          type: array
          description: The subset of email_addresses on personal mail providers (Gmail, Outlook, and similar). Only present when email_addresses is present.
          items:
            type: string
            format: email
          example:
            - "john.doe@gmail.com"
        work_email_addresses:
          type: array
          description: The subset of email_addresses on company domains. Only present when email_addresses is present.
          items:
            type: string
            format: email
          example:
            - "johndoe@company.com"
        phone_numbers:
          type: array
          description: List of known phone numbers. Only returned when email_addresses is also present.
          items:
            type: string
          example:
            - "+1-555-123-4567"
        github_username:
          type: string
          nullable: true
          description: GitHub username
          example: "johndoe"
        facebook_username:
          type: string
          nullable: true
          description: Facebook username
          example: "john.doe"
        twitter_username:
          type: string
          nullable: true
          description: Twitter/X username
          example: "johndoe"

    EmailVerificationResult:
      type: object
      description: Detailed email verification result
      required:
        - email
        - valid
        - classification
        - score
        - score_details
        - errors
        - warnings
        - checks
      properties:
        email:
          type: string
          format: email
          description: The email address that was validated
          example: "user@example.com"
        valid:
          type: boolean
          description: Whether the email is considered valid
          example: true
        classification:
          type: string
          enum:
            - valid
            - risky
            - invalid
          description: |
            Overall classification of the email:
            - `valid`: Email passed all checks cleanly
            - `risky`: Email is valid but has concerns (accepts any email, DNS/SMTP assumptions, disposable email, or warnings)
            - `invalid`: Email validation failed
          example: "valid"
        score:
          type: integer
          minimum: 0
          maximum: 100
          description: |
            Validation score from 0-100. Higher scores indicate higher confidence.

            Scoring breakdown:
            - Syntax valid: +20 points
            - MX verified: +40 points (or +15 if assumed)
            - SMTP verified: +35 points (or +15 if accepts any email, +10 if assumed)
            - No SMTP check: +20 points
            - Warning penalty: Up to -25 points
          example: 95
        score_details:
          $ref: "#/components/schemas/ScoreDetails"
        errors:
          type: array
          description: List of validation errors encountered
          items:
            type: string
          example: []
        warnings:
          type: array
          description: List of validation warnings
          items:
            type: string
          example:
            - "Domain appears to accept any email address"
        checks:
          $ref: "#/components/schemas/ValidationChecks"

    ScoreDetails:
      type: object
      description: Detailed breakdown of validation scoring factors
      properties:
        syntax_valid:
          type: boolean
          description: Whether email syntax is valid
          example: true
        mx_verified:
          type: boolean
          description: Whether MX records were verified via DNS
          example: true
        smtp_verified:
          type: boolean
          description: Whether SMTP deliverability was verified
          example: true
        smtp_failed_assumption:
          type: boolean
          description: Whether SMTP verification was assumed due to connection failure
          example: false
        dns_failed_assumption:
          type: boolean
          description: Whether DNS verification was assumed due to lookup failure
          example: false
        has_warnings:
          type: boolean
          description: Whether any warnings were generated
          example: false
        accepts_any_email:
          type: boolean
          description: Whether the server accepts any email (catch-all)
          example: false

    ValidationChecks:
      type: object
      description: Individual validation check results
      properties:
        syntax:
          type: boolean
          description: Email syntax check result
          example: true
        mx_record:
          type: boolean
          description: MX record DNS lookup result
          example: true
        smtp_deliverable:
          type: boolean
          nullable: true
          description: SMTP deliverability check result (null if not checked)
          example: true
        disposable:
          type: boolean
          description: Whether the email domain is a known disposable email provider
          example: false
        typo_suggestion:
          type: string
          nullable: true
          description: Suggested correction for common domain typos
          example: null
        accepts_any_email:
          type: boolean
          nullable: true
          description: Whether the server accepts any email address (null if not checked)
          example: false

    Error:
      type: object
      description: Error response
      required:
        - error
      properties:
        error:
          type: string
          description: Error message
          example: "Unauthorized"

tags:
  - name: Contact Info
    description: Operations for retrieving contact information
  - name: Email Verification
    description: Operations for validating email addresses