openapi: 3.2.0
info:
  title: Ploid Search API
  version: 2.0.0
  description: 'Operations tagged Search 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: Search
paths:
  /v1/search:
    post:
      operationId: syncPeopleSearch
      summary: Search people synchronously
      description: Retrieve up to 150 people inline per request; async:true or a larger num_results starts a background People Set instead and returns 202 with set_id, items_url and events_url. instant and fast return indexed candidates. auto and deep research the complete query and explicit filters before returning matches with verification references; uncertain and rejected candidates are excluded from results, grounding and billing. Auto/deep compile the query, verify candidates, and run one bounded web recovery pass when too few match. Each verification pass permits up to 30 seconds for auto or 45 seconds for deep; recovery discovery permits 45 or 60 seconds respectively. A partial status means the requested count was not filled or verification hit its deadline. Use Sets for durable research of large result sets. Verification is evidence-based model assessment, separate from identity verification. Requires people:search.
      tags:
      - Search
      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/SyncSearchRequest'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncSearchResponse'
        '202':
          description: Async search started as a People Set; read rows from items_url or follow events_url.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchHandoffResponse'
        '401':
          description: Missing, invalid, expired, or revoked API credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '402':
          description: Public-API access is inactive, the workspace has insufficient ACU or API-key budget, or an async count requires sales.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
        '403':
          description: The credential lacks the required scope, its owning user is inactive, or this workspace does not include the requested API capability.
          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: Search backend unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
    servers:
    - url: https://api.ploid.com
  /v1/resolve:
    post:
      operationId: resolvePerson
      summary: Identify one person
      description: Identify one person from a full name plus at least one clue (company name or domain, role, location, address, work or personal email, or phone) by fusing the people index with live web results. Returns the permanent person_id accepted by /v1/person and /v1/enrich, so a deep profile is only bought for the right person. Costs 2 ACU when a person is found; no match is free. A match is model-assessed, not identity-verified. Requires people:search.
      tags:
      - Search
      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/ResolveRequest'
      responses:
        '200':
          description: Resolution result; found is false when no confident match exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolveResponse'
        '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: The credential lacks the required scope, its owning user is inactive, or this workspace does not include the requested API capability.
          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
    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
    PublicCreditsResponseMeta:
      type: object
      additionalProperties: false
      required:
      - request_id
      - credits_charged
      properties:
        request_id:
          type: string
        credits_charged:
          type: number
          minimum: 0
        remaining_credits:
          type: number
          minimum: 0
        cursor:
          type:
          - string
          - 'null'
        message:
          type: string
    SyncSearchGroundingResult:
      type: object
      additionalProperties: false
      required:
      - url
      - title
      - snippet
      - source
      - observed_at
      - person
      properties:
        url:
          type: string
          format: uri
        title:
          type: string
        snippet:
          type:
          - string
          - 'null'
        source:
          type: string
        observed_at:
          type: string
          format: date-time
        person:
          type: object
          additionalProperties: false
          required:
          - name
          - title
          - company
          - location
          - linkedin_url
          - identity_verified
          - resolution_source
          properties:
            name:
              type: string
            title:
              type:
              - string
              - 'null'
            company:
              type:
              - string
              - 'null'
            location:
              type:
              - string
              - 'null'
            linkedin_url:
              type:
              - string
              - 'null'
            identity_verified:
              type: boolean
              const: false
            resolution_source:
              type: string
              const: public_web
    SyncSearchResponse:
      type: object
      additionalProperties: false
      required:
      - data
      - meta
      properties:
        data:
          type: object
          additionalProperties: false
          required:
          - results
          - grounding
          - search_time_ms
          - rows_indexed
          - request
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/SyncSearchResult'
            grounding:
              type: object
              additionalProperties: false
              required:
              - status
              - results
              - source_counts
              - provider_outcomes
              - search_time_ms
              properties:
                status:
                  type: string
                  enum:
                  - not_needed
                  - complete
                  - partial
                  - unavailable
                results:
                  type: array
                  items:
                    $ref: '#/components/schemas/SyncSearchGroundingResult'
                source_counts:
                  type: object
                  additionalProperties:
                    type: integer
                    minimum: 0
                provider_outcomes:
                  type: object
                  additionalProperties:
                    type: string
                    enum:
                    - completed
                    - failed
                    - unconfigured
                search_time_ms:
                  type: number
                  minimum: 0
            search_time_ms:
              type: number
              minimum: 0
              description: Index search duration.
            total_time_ms:
              type: number
              minimum: 0
              description: Total search processing time, including planning, retrieval and verification.
            rows_indexed:
              type: integer
              minimum: 0
            verification:
              type: object
              required:
              - status
              - candidates_checked
              - search_time_ms
              properties:
                status:
                  type: string
                  enum:
                  - complete
                  - partial
                candidates_checked:
                  type: integer
                  minimum: 0
                search_time_ms:
                  type: number
                  minimum: 0
            request:
              type: object
              additionalProperties: false
              required:
              - query
              - type
              - category
              - num_results
              properties:
                query:
                  type: string
                type:
                  type: string
                  enum:
                  - instant
                  - fast
                  - auto
                  - deep
                category:
                  type: string
                  const: people
                num_results:
                  type: integer
                  minimum: 1
                  maximum: 150
                criteria:
                  type: array
                  items:
                    type: string
        meta:
          $ref: '#/components/schemas/PublicCreditsResponseMeta'
    ResolveResponse:
      type: object
      additionalProperties: false
      required:
      - data
      - meta
      properties:
        data:
          type: object
          additionalProperties: false
          required:
          - found
          - person
          - confidence
          - summary
          - sources
          properties:
            found:
              type: boolean
            person:
              oneOf:
              - type: 'null'
              - type: object
                additionalProperties: false
                required:
                - person_id
                - name
                - headline
                - company
                - location
                - profiles
                - identity_verified
                properties:
                  person_id:
                    type: string
                    description: Pass to /v1/person or /v1/enrich as identifier.person_id.
                  name:
                    type: string
                  headline:
                    type:
                    - string
                    - 'null'
                  company:
                    type:
                    - string
                    - 'null'
                  location:
                    type:
                    - string
                    - 'null'
                  profiles:
                    type: object
                    additionalProperties: false
                    description: Profiles found while resolving. Missing platforms are omitted; more_profiles shows how to look for more.
                    properties:
                      linkedin:
                        type: string
                        format: uri
                      github:
                        type: string
                        format: uri
                      x:
                        type: string
                        format: uri
                  identity_verified:
                    type: boolean
                    const: false
            confidence:
              type: number
              minimum: 0
              maximum: 1
            summary:
              type: string
            sources:
              type: array
              items:
                type: string
            more_profiles:
              type: object
              additionalProperties: false
              description: Present when found. A ready-to-send /v1/person request that looks for more public profiles.
              required:
              - message
              - endpoint
              - body
              - estimated_credits
              properties:
                message:
                  type: string
                endpoint:
                  type: string
                  const: POST /v1/person
                body:
                  type: object
                  required:
                  - identifier
                  properties:
                    identifier:
                      type: object
                      required:
                      - person_id
                      properties:
                        person_id:
                          type: string
                estimated_credits:
                  type: integer
                  const: 25
        meta:
          $ref: '#/components/schemas/PublicCreditsResponseMeta'
    ResolveRequest:
      type: object
      additionalProperties: false
      required:
      - name
      properties:
        name:
          type: string
          minLength: 2
          maxLength: 200
          description: Full name; a partial or misspelled surname is tolerated.
        company:
          type: string
          minLength: 1
          maxLength: 200
          description: Company name or web domain, such as Acme or acme.com.
        role:
          type: string
          minLength: 1
          maxLength: 300
          description: Job title or role.
        location:
          type: string
          minLength: 1
          maxLength: 200
          description: City, region, or country.
        address:
          type: string
          minLength: 3
          maxLength: 300
          description: Street or mailing address; it only has to fit the person's area.
        work_email:
          type: string
          format: email
          maxLength: 254
          description: Work email. Its domain identifies the employer unless it is a free mailbox provider.
        personal_email:
          type: string
          format: email
          maxLength: 254
        phone:
          type: string
          maxLength: 40
          pattern: ^\+?[\d\s().-]+$
          description: Phone number with 7 to 15 digits, in any common format.
      anyOf:
      - required:
        - company
      - required:
        - role
      - required:
        - location
      - required:
        - address
      - required:
        - work_email
      - required:
        - personal_email
      - required:
        - phone
    SyncSearchPerson:
      type: object
      additionalProperties: false
      required:
      - person_id
      - confidence
      - contact_status
      - identity_verified
      - resolution_source
      properties:
        person_id:
          type: string
          description: Stable Ploid identity. Deep person enrichment currently requires a linked LinkedIn profile.
        name:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        company:
          type:
          - string
          - 'null'
        location:
          type:
          - string
          - 'null'
        linkedin_url:
          type:
          - string
          - 'null'
        profile_url:
          type: string
          description: Canonical public profile or individual biography when discovered outside LinkedIn.
        confidence:
          type:
          - number
          - 'null'
          minimum: 0
          maximum: 1
          description: Retrieval confidence normalized to 0..1; null when the source has no confidence score.
        contact_status:
          type: string
          enum:
          - requires_enrichment
          - unavailable
          description: LinkedIn contact fields can be resolved through POST /v1/enrich. Results without LinkedIn report unavailable.
        identity_verified:
          type: boolean
          const: false
        resolution_source:
          type: string
          enum:
          - ploid_people_index
          - public_web
      description: Only resolved people are returned. Requested profile fields are present when selected and may be null when the people index has no value.
    SyncSearchResult:
      type: object
      additionalProperties: false
      required:
      - url
      - title
      - score
      - person
      properties:
        url:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        score:
          type:
          - number
          - 'null'
        person:
          $ref: '#/components/schemas/SyncSearchPerson'
        verification:
          type: array
          items:
            type: object
            required:
            - criterionId
            - criterion
            - status
            - reasoning
            - references
            properties:
              criterionId:
                type: string
              criterion:
                type: string
              status:
                type: string
                const: satisfied
              reasoning:
                type: string
              references:
                type: array
                items:
                  type: object
                  required:
                  - source
                  - quote
                  properties:
                    url:
                      type: string
                    source:
                      type: string
                    quote:
                      type: string
    SyncSearchRequest:
      type: object
      additionalProperties: false
      properties:
        query:
          type: string
          maxLength: 4000
          default: ''
          description: Optional semantic query. Supply this, at least one structured filter, or both.
        type:
          type: string
          enum:
          - instant
          - fast
          - auto
          - deep
          default: auto
          description: instant and fast return indexed candidates. auto and deep require evidence-backed matches to the complete query and filters; deep also always runs public-web grounding. Verification may return fewer results within its deadline; Sets supports durable research for larger requests.
        category:
          type: string
          enum:
          - people
          default: people
        num_results:
          type: integer
          minimum: 1
          maximum: 5000
          default: 10
          description: Up to 150 return inline. Larger requests run as a background People Set (self-serve up to 500).
        criteria:
          type: array
          maxItems: 5
          default: []
          items:
            type: string
            minLength: 1
            maxLength: 500
          description: Plain-English conditions every result must satisfy, such as 'Has founded a venture-backed company'. Each is researched and judged separately; results carry one verification entry per criterion and are ranked by evidence strength across all of them. Requires type auto or deep. In async searches they replace the criteria derived from the query.
        async:
          type: boolean
          description: Run as a background People Set and return 202 with set_id. Defaults to true above 150 results; false with a larger num_results is rejected. Async searches always verify each row, so type and contents do not apply.
        webhook_url:
          type: string
          format: uri
          description: Async searches only. Receives the Set's progress events.
        filters:
          type: object
          additionalProperties: false
          default: {}
          properties:
            title:
              type: string
              minLength: 1
              maxLength: 200
            seniority:
              type: string
              minLength: 1
              maxLength: 80
            company:
              type: string
              minLength: 1
              maxLength: 200
            industry:
              type: string
              minLength: 1
              maxLength: 200
            location:
              type: string
              minLength: 1
              maxLength: 200
        contents:
          type: object
          additionalProperties: false
          default: {}
          properties:
            fields:
              type: array
              default:
              - linkedin
              - title
              - company
              - location
              items:
                type: string
                enum:
                - linkedin
                - title
                - company
                - location
                - name
      anyOf:
      - required:
        - query
        properties:
          query:
            type: string
            minLength: 1
      - required:
        - filters
        properties:
          filters:
            anyOf:
            - required:
              - title
            - required:
              - seniority
            - required:
              - company
            - required:
              - industry
            - required:
              - location
    SearchHandoffResponse:
      type: object
      additionalProperties: false
      required:
      - data
      - meta
      properties:
        data:
          type: object
          additionalProperties: false
          required:
          - mode
          - set_id
          - search_id
          - status
          - criteria
          - pricing
          - set_url
          - items_url
          - events_url
          - request
          properties:
            mode:
              type: string
              const: async
            set_id:
              type: string
            search_id:
              type: string
            status:
              type: string
              const: running
            criteria:
              type: array
              items:
                type: string
              description: Criteria every admitted row is verified against.
            pricing:
              type: object
              additionalProperties: true
              description: Estimate; billing settles on admitted rows.
            set_url:
              type: string
            items_url:
              type: string
              description: Page admitted rows, usable while the search runs.
            events_url:
              type: string
              description: Server-sent progress events.
            request:
              type: object
              additionalProperties: false
              required:
              - query
              - category
              - num_results
              properties:
                query:
                  type: string
                category:
                  type: string
                  const: people
                num_results:
                  type: integer
                  minimum: 1
                criteria:
                  type: array
                  items:
                    type: string
                resolved_query:
                  type: string
                notes:
                  type: array
                  items:
                    type: string
        meta:
          $ref: '#/components/schemas/PublicCreditsResponseMeta'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
x-refined-from:
- ploid-openapi.json
- ploid-openapi.yml