superagnt-com superagnt Lead APIs: People — Email API

openapi: 3.2.0
info:
  title: 'superagnt Lead APIs: People — Email API'
  description: Unified API for social media data. Access LinkedIn, YouTube, TikTok, X, Instagram, Reddit, and Facebook through a single API key.
  version: 1.0.0
  contact:
    name: superagnt
    url: https://superagnt.com
servers:
- url: https://api.superagnt.com
  description: superagnt API
security:
- ApiKeyAuth: []
tags:
- name: 'superagnt Lead APIs: People — Email'
  description: Find, verify, and enrich professional email addresses.
paths:
  /v1/data/agnt/people/email-finder:
    post:
      operationId: people_email_finder
      summary: Find a person's professional email
      description: 'Find a verified professional email for a person at a company. Identifier fields are at the TOP LEVEL of the body (NOT inside an `identifiers` object): `first_name` + `last_name` (or `full_name`) plus `domain` (or `company` / `company_name`). LinkedIn URL/handle is not currently supported here — if that is all you have, call `/people/enrich` first with `identifiers.linkedin_url` to resolve name + domain, then call this endpoint. agntdata waterfalls cheapest-first across providers until an email is returned (or your `max_cost_cents` budget is exhausted). If you already know the email and want to look up other fields, use `/people/enrich` instead with `identifiers.email`.'
      tags:
      - 'superagnt Lead APIs: People — Email'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PeopleEmailFinderRequest'
            example:
              first_name: Patrick
              last_name: Collison
              domain: stripe.com
              max_cost_cents: 2.5
      responses:
        '200':
          description: Email finder result.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    enum:
                    - true
                  data:
                    $ref: '#/components/schemas/PeopleEmailFinderResponse'
                  meta:
                    $ref: '#/components/schemas/AgntMeta'
        '400':
          description: Validation error.
        '401':
          description: Unauthorized — missing or invalid API key.
        '402':
          description: Insufficient credits.
        '429':
          description: Rate limit exceeded.
        5XX:
          description: Upstream or internal error.
      security:
      - ApiKeyAuth: []
  /v1/data/agnt/people/email-verifier:
    post:
      operationId: people_email_verifier
      summary: Verify a professional email
      description: Verify the deliverability and reputation of an email address. Returns a normalized status (valid, accept_all, unknown, invalid) and provider-agnostic signals (smtp, mx, disposable, webmail, gibberish).
      tags:
      - 'superagnt Lead APIs: People — Email'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PeopleEmailVerifierRequest'
            example:
              email: patrick@stripe.com
      responses:
        '200':
          description: Verification result.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    enum:
                    - true
                  data:
                    $ref: '#/components/schemas/PeopleEmailVerifierResponse'
                  meta:
                    $ref: '#/components/schemas/AgntMeta'
        '400':
          description: Validation error.
        '401':
          description: Unauthorized.
        '402':
          description: Insufficient credits.
      security:
      - ApiKeyAuth: []
components:
  schemas:
    PeopleEmailVerifierResponse:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    AgntMeta:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    PeopleEmailVerifierRequest:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    PeopleEmailFinderResponse:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
    PeopleEmailFinderRequest:
      type: object
      description: Referenced by this document but never defined in it. API Evangelist added this empty placeholder so the document resolves; the shape is unknown and is NOT a claim about the API.
      x-ae-placeholder: true
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Bearer token. Pass your agntdata API key as: Authorization: Bearer agnt_live_...'