openapi: 3.2.0
info:
  title: Ploid Enrichment API
  version: 2.0.0
  description: 'Operations tagged Enrichment across 2 of this provider''s published API definitions: ploid-openapi.json, ploid-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.ploid.com
security:
- bearerAuth: []
- apiKeyAuth: []
tags:
- name: Enrichment
paths:
  /v1/enrich:
    post:
      operationId: enrichPerson
      summary: Enrich one person
      description: Resolve contact fields for one person using a LinkedIn URL, permanent person_id, reverse email, or name plus company domain. Request work_email, personal_email, and/or phone; every field reports found, not_found, or unavailable with confidence, source, and last_seen. Responses include explicit usage.billed and usage.not_found. The legacy lightweight LinkedIn profile contract remains supported; use /v1/person for deep public evidence. Requires the people:enrich scope.
      tags:
      - Enrichment
      security:
      - bearerAuth: []
      - apiKeyAuth: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: Recommended on non-streaming POSTs. Reusing the same key and authenticated request within 24 hours replays the original response and bills once. Live SSE responses reject this header; use a durable async run for replayable work.
        schema:
          type: string
          maxLength: 255
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichRequest'
      responses:
        '200':
          description: Enrichment results, including partial failures and clean not-found results. Complete provider failure returns 503.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichResponse'
            text/markdown:
              schema:
                type: string
        '401':
          description: Missing, invalid, expired, or revoked API credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '402':
          description: Public-API access is inactive, or the workspace has insufficient ACU or API-key budget.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '403':
          description: Missing people:enrich scope, reveal capability, or public-API access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '404':
          description: The supplied person_id could not be resolved in the caller's identity context.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '409':
          description: Idempotency-Key is in progress or was reused for a different request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '422':
          description: The request body, path parameters, or query parameters failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '429':
          description: The organization or API-key per-minute rate limit was exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
                minimum: 1
        '503':
          description: All requested fields are unavailable, or enrichment exceeded its deadline. Retryable with Retry-After; unsuccessful fields are not billed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
                minimum: 1
    servers:
    - url: https://api.ploid.com
components:
  schemas:
    PublicApiError:
      type: object
      additionalProperties: false
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - request_id
          properties:
            code:
              type: string
            message:
              type: string
            request_id:
              type: string
            http_status:
              type: integer
              minimum: 400
              maximum: 599
              description: Semantic status when an error terminates a response after streaming headers opened.
            retryable:
              type: boolean
            unavailable_fields:
              type: array
              items:
                type: string
                enum:
                - work_email
                - personal_email
                - phone
                - profile
                - email
              description: Requested enrichment fields that could not complete. Present when all requested fields are unavailable.
            usage:
              type: object
              additionalProperties: false
              required:
              - acu_used
              - billed
              - free
              - not_found
              properties:
                acu_used:
                  type: number
                  minimum: 0
                acu_remaining:
                  type: number
                  minimum: 0
                acu_value_usd:
                  type: number
                  const: 0.1
                billed:
                  type: array
                  items:
                    type: string
                free:
                  type: array
                  items:
                    type: string
                not_found:
                  type: array
                  items:
                    type: string
          additionalProperties: true
    EnrichResponse:
      oneOf:
      - $ref: '#/components/schemas/EnrichLegacyResponse'
      - $ref: '#/components/schemas/EnrichContactResponse'
    EnrichContactResponse:
      type: object
      additionalProperties: false
      required:
      - data
      - meta
      properties:
        data:
          type: object
          additionalProperties: false
          properties:
            work_email:
              $ref: '#/components/schemas/EnrichFieldResult'
            personal_email:
              $ref: '#/components/schemas/EnrichFieldResult'
            phone:
              $ref: '#/components/schemas/EnrichFieldResult'
          description: Only requested contact fields are present.
        meta:
          type: object
          additionalProperties: false
          required:
          - request_id
          - usage
          - warnings
          properties:
            request_id:
              type: string
            warnings:
              type: array
              items:
                type: string
            usage:
              type: object
              additionalProperties: false
              required:
              - acu_used
              - acu_remaining
              - acu_value_usd
              - billed
              - free
              - not_found
              properties:
                acu_used:
                  type: number
                  minimum: 0
                acu_remaining:
                  type:
                  - number
                  - 'null'
                  minimum: 0
                acu_value_usd:
                  type: number
                  const: 0.1
                billed:
                  type: array
                  items:
                    type: string
                    enum:
                    - work_email
                    - personal_email
                    - phone
                free:
                  type: array
                  items:
                    type: string
                not_found:
                  type: array
                  items:
                    type: string
                    enum:
                    - work_email
                    - personal_email
                    - phone
    EnrichContactRequest:
      type: object
      additionalProperties: false
      required:
      - fields
      properties:
        linkedin_url:
          type: string
          format: uri
          pattern: ^https?://(?:[^/]+\.)?linkedin\.com/in/[^/?#]+/?(?:[?#].*)?$
        person_id:
          type: string
          description: Permanent Ploid person id.
        email:
          type: string
          format: email
          description: Reverse contact lookup anchor.
        name:
          type: string
        company_domain:
          type: string
          pattern: ^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,63}$
        first_name:
          type: string
        last_name:
          type: string
        fields:
          type: array
          minItems: 1
          maxItems: 3
          uniqueItems: true
          items:
            type: string
            enum:
            - work_email
            - personal_email
            - phone
        response_format:
          const: standard
      oneOf:
      - required:
        - linkedin_url
      - required:
        - person_id
      - required:
        - email
      - required:
        - name
        - company_domain
    EnrichContact:
      type: object
      additionalProperties: false
      required:
      - value
      - confidence
      - verification_status
      properties:
        value:
          type: string
        confidence:
          type: string
          enum:
          - guess
          - strong
          - verified
        verification_status:
          type: string
          enum:
          - matched
          - verified
    EnrichFieldResult:
      type: object
      additionalProperties: false
      required:
      - value
      - status
      - confidence
      - source
      - last_seen
      properties:
        value:
          type:
          - string
          - 'null'
        status:
          type: string
          enum:
          - found
          - not_found
          - unavailable
        confidence:
          type:
          - string
          - 'null'
          enum:
          - guess
          - strong
          - verified
          - null
        source:
          type:
          - string
          - 'null'
          enum:
          - contact_network
          - linked_profile
          - public_code
          - public_web
          - null
        last_seen:
          type:
          - string
          - 'null'
          format: date-time
    EnrichRequest:
      oneOf:
      - $ref: '#/components/schemas/EnrichLegacyRequest'
      - $ref: '#/components/schemas/EnrichContactRequest'
    EnrichLegacyResponse:
      type: object
      additionalProperties: false
      required:
      - data
      - meta
      properties:
        data:
          type: object
          additionalProperties: false
          properties:
            linkedin_profile:
              oneOf:
              - $ref: '#/components/schemas/EnrichLinkedInProfile'
              - type: 'null'
            email:
              oneOf:
              - $ref: '#/components/schemas/EnrichContact'
              - type: 'null'
            phone:
              oneOf:
              - $ref: '#/components/schemas/EnrichContact'
              - type: 'null'
          description: Only requested enrichment fields are present; an unavailable field is null.
        meta:
          type: object
          additionalProperties: false
          required:
          - request_id
          - acu_used
          - acu_remaining
          - acu_value_usd
          - warnings
          properties:
            request_id:
              type: string
            acu_used:
              type: number
              minimum: 0
            acu_remaining:
              type:
              - number
              - 'null'
              minimum: 0
            acu_value_usd:
              type: number
              const: 0.1
            warnings:
              type: array
              items:
                type: string
    EnrichLegacyRequest:
      type: object
      additionalProperties: false
      required:
      - linkedin_url
      properties:
        linkedin_url:
          type: string
          format: uri
          pattern: ^https?://(?:[^/]+\.)?linkedin\.com/in/[^/?#]+/?(?:[?#].*)?$
        first_name:
          type: string
        last_name:
          type: string
        enrichments:
          type: array
          minItems: 1
          maxItems: 3
          default:
          - profile
          items:
            type: string
            enum:
            - profile
            - linkedin_profile
            - email
            - phone
        response_format:
          type: string
          enum:
          - standard
          - markdown
          default: standard
    EnrichLinkedInProfile:
      type: object
      additionalProperties: false
      required:
      - linkedin_url
      - name
      - headline
      - company
      - location
      - photo_url
      - skills
      - companies
      - schools
      - total_years_experience
      - open_to_work
      - follower_count
      - verification_status
      properties:
        linkedin_url:
          type: string
          format: uri
        name:
          type: string
        headline:
          type:
          - string
          - 'null'
        company:
          type:
          - string
          - 'null'
        location:
          type:
          - string
          - 'null'
        photo_url:
          type:
          - string
          - 'null'
        skills:
          type: array
          items:
            type: string
        companies:
          type: array
          items:
            type: string
        schools:
          type: array
          items:
            type: string
        total_years_experience:
          type:
          - number
          - 'null'
          minimum: 0
        open_to_work:
          type: boolean
        follower_count:
          type:
          - number
          - 'null'
          minimum: 0
        verification_status:
          type: string
          const: refreshed
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
x-refined-from:
- ploid-openapi.json
- ploid-openapi.yml