superagnt-com superagnt Lead APIs: People — Enrich API

openapi: 3.2.0
info:
  title: 'superagnt Lead APIs: People — Enrich 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 — Enrich'
  description: Enrich people with structured profile data.
paths:
  /v1/data/agnt/people/enrich:
    post:
      operationId: people_enrich
      summary: Enrich a person
      description: 'Enrich a person with normalized fields (email, mobile, job title, company, LinkedIn URL, location, …). REQUIRES a `identifiers` object containing ONLY `email` and/or `linkedin_url` — these are the unique handles we use to resolve the person upstream. `first_name`, `last_name`, `domain`, `company`, etc. are NOT accepted here and will return a VALIDATION_ERROR. If you only have a name + company, call `/people/email-finder` first to obtain an email, then pass that email here. Optional `fields[]` narrows the waterfall to only fetch the fields you care about. agntdata runs a field-aware waterfall: it stops once all requested fields are filled or your `max_cost_cents` budget is exhausted.'
      tags:
      - 'superagnt Lead APIs: People — Enrich'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PeopleEnrichRequest'
            example:
              identifiers:
                linkedin_url: https://linkedin.com/in/patrickcollison
              fields:
              - email
              - job_title
              - company_name
              - company_domain
      responses:
        '200':
          description: Person enrichment result.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    enum:
                    - true
                  data:
                    $ref: '#/components/schemas/PeopleEnrichResponse'
                  meta:
                    $ref: '#/components/schemas/AgntMeta'
        '400':
          description: Validation error.
        '401':
          description: Unauthorized.
        '402':
          description: Insufficient credits.
      security:
      - ApiKeyAuth: []
  /v1/data/agnt/people/bulk-enrich:
    post:
      operationId: people_bulk_enrich
      summary: Bulk enrich people
      description: Enrich up to 100 people in one call. Each input record requires `email` and/or `linkedin_url` (either at the top level of the input object or nested under `identifiers`). `first_name`/`last_name`/`domain` are NOT accepted — if you only have name+company, call `/people/email-finder` per record first. Each input runs the same field-aware waterfall as `/people/enrich`. Use `max_cost_cents_per_record` to cap per-record spend.
      tags:
      - 'superagnt Lead APIs: People — Enrich'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PeopleBulkEnrichRequest'
            example:
              inputs:
              - identifier: row-1
                linkedin_url: https://linkedin.com/in/patrickcollison
              - identifier: row-2
                email: elon@spacex.com
              fields:
              - email
              - job_title
              - company_name
      responses:
        '200':
          description: Bulk enrichment results.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    type: boolean
                    enum:
                    - true
                  data:
                    $ref: '#/components/schemas/PeopleBulkEnrichResponse'
                  meta:
                    $ref: '#/components/schemas/AgntMeta'
        '400':
          description: Validation error.
        '402':
          description: Insufficient credits.
      security:
      - ApiKeyAuth: []
components:
  schemas:
    PeopleBulkEnrichRequest:
      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
    PeopleBulkEnrichResponse:
      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
    PeopleEnrichResponse:
      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
    PeopleEnrichRequest:
      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_...'