openapi: 3.1.0
info:
  title: "Contact Enrichment API — Headless AI SDR (Reply.io)"
  version: "3.0"
  description: |
    Fill the gaps in contact records — find missing emails and phone numbers,
    enrich by email or LinkedIn URL, and populate AI custom fields.

    This module is COMING SOON. Reply's API reference still marks all five
    contact-enrichment operations Coming soon as of 2026-07-05 (targeted late July 2026). Paths, request
    bodies, and response shapes in this summary specification are indicative and
    will be superseded by the published reference. The authoritative source is
    https://docs.reply.io/api-reference/contact-enrichment/enrich-contacts-by-email
    and the full platform OpenAPI at https://docs.reply.io/api-reference/bundled.yaml.
  contact:
    name: Reply.io
    url: https://reply.io
servers:
  - url: https://api.reply.io/v3
security:
  - bearerAuth: []
tags:
  - name: Contact Enrichment
paths:
  /contact-enrichment/enrich-by-email:
    post:
      tags: [Contact Enrichment]
      operationId: enrichContactsByEmail
      summary: Enrich contacts by email
      description: |
        **Coming soon** — still Coming soon in Reply's API reference as of
        2026-07-05 (targeted late July 2026). Scope not yet published; expected to follow the `contacts`
        domain. Hand over one or more email addresses and get back filled
        contact records.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [emails]
              properties:
                emails:
                  type: array
                  items:
                    type: string
                    format: email
      responses:
        "200":
          description: Enrichment results per submitted email.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EnrichmentResultList"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
  /contact-enrichment/enrich-by-linkedin-url:
    post:
      tags: [Contact Enrichment]
      operationId: enrichContactsByLinkedInUrl
      summary: Enrich contacts by LinkedIn URL
      description: |
        **Coming soon** — still Coming soon in Reply's API reference as of
        2026-07-05 (targeted late July 2026). Scope not yet published; expected to follow the `contacts`
        domain. The lookup path when an agent has a LinkedIn profile URL but no
        email address.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [linkedInUrls]
              properties:
                linkedInUrls:
                  type: array
                  items:
                    type: string
                    format: uri
      responses:
        "200":
          description: Enrichment results per submitted LinkedIn URL.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EnrichmentResultList"
        "403":
          $ref: "#/components/responses/Forbidden"
  /contact-enrichment/find-missing-email-addresses:
    post:
      tags: [Contact Enrichment]
      operationId: findMissingEmailAddresses
      summary: Find missing email addresses
      description: |
        **Coming soon** — still Coming soon in Reply's API reference as of
        2026-07-05 (targeted late July 2026). Scope not yet published; expected to follow the `contacts`
        domain. Resolves email addresses for existing Reply contacts that lack
        one; discovered addresses land on the contact record.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [contactIds]
              properties:
                contactIds:
                  type: array
                  items:
                    type: string
      responses:
        "200":
          description: Lookup results per contact.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EnrichmentResultList"
        "403":
          $ref: "#/components/responses/Forbidden"
  /contact-enrichment/find-phone-numbers:
    post:
      tags: [Contact Enrichment]
      operationId: findPhoneNumbers
      summary: Find phone numbers
      description: |
        **Coming soon** — still Coming soon in Reply's API reference as of
        2026-07-05 (targeted late July 2026). Scope not yet published; expected to follow the `contacts`
        domain. Resolves phone numbers for existing Reply contacts, e.g. ahead
        of a call step.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [contactIds]
              properties:
                contactIds:
                  type: array
                  items:
                    type: string
      responses:
        "200":
          description: Lookup results per contact.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EnrichmentResultList"
        "403":
          $ref: "#/components/responses/Forbidden"
  /contact-enrichment/fill-ai-custom-fields:
    post:
      tags: [Contact Enrichment]
      operationId: fillAiCustomFields
      summary: Fill AI custom fields
      description: |
        **Coming soon** — still Coming soon in Reply's API reference as of
        2026-07-05 (targeted late July 2026). Scope not yet published; expected to follow the `contacts`
        domain. Populates AI-generated custom fields on contacts, ready to use
        as merge variables in outreach.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [contactIds]
              properties:
                contactIds:
                  type: array
                  items:
                    type: string
                customFieldIds:
                  type: array
                  items:
                    type: string
      responses:
        "200":
          description: Fill results per contact.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EnrichmentResultList"
        "403":
          $ref: "#/components/responses/Forbidden"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        Reply.io API key sent as a Bearer token. Create one in the Reply.io app
        under Settings → API Key. See
        https://docs.reply.io/api-reference/authentication.
  schemas:
    EnrichmentResultList:
      type: object
      description: |
        Generic result envelope. Field names are indicative until the endpoints
        publish their final response schemas.
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/EnrichmentResult"
    EnrichmentResult:
      type: object
      properties:
        contactId:
          type: string
        email:
          type: string
        status:
          type: string
          description: Per-contact enrichment outcome (e.g. enriched, not found).
    Problem:
      type: object
      description: RFC 7807 problem document (application/problem+json).
      properties:
        type: { type: string }
        title: { type: string }
        status: { type: integer }
        detail: { type: string }
  responses:
    Forbidden:
      description: The API key is missing a required scope.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
    RateLimited:
      description: |
        Rate limit exceeded (100 requests/minute, 3,000/hour per user). Honor
        the Retry-After header.
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
