openapi: 3.1.0
# Published on the public docs site, as a reference page and as this file.
# A contract without this key is internal.
x-docs-visibility: public
info:
  title: Assessor.io API v2 (public) - Contacts
  version: 1.1.1
  description: |
    Read-only export of the account's in-app CRM contacts, for an external CRM
    to pull from. Read-only by design: two-way sync is deliberately out of
    scope, so there is no create, update, or delete here. Responses are the
    whitelisted PublicContact projection, so the free-form metadata bag
    (internal notes, the captured contact-form message, sync correlation ids),
    the owning user, the polymorphic source reference, and the archive
    timestamp are never returned. Scope contacts:read.
servers:
  - url: /
security:
  - serviceToken: []
tags:
  - name: PublicContacts
paths:
  /api/v2/public/accounts/{accountId}/contacts:
    get:
      tags: [PublicContacts]
      operationId: v2ListContacts
      summary: List the account's CRM contacts.
      description: |
        Paginated, ordered by last activity (falling back to creation time),
        newest first. Archived contacts are always excluded. Scope contacts:read.
      parameters:
        - $ref: '../components/v2-common.yaml#/components/parameters/AccountId'
        - name: stage
          in: query
          required: false
          description: Filter by lifecycle stage. Any other value is rejected with 400.
          schema:
            $ref: '#/components/schemas/ContactStage'
        - name: search
          in: query
          required: false
          description: Case-insensitive substring match against email, first name, last name, or company.
          schema:
            type: string
        - $ref: '../components/v2-common.yaml#/components/parameters/Page'
        - $ref: '../components/v2-common.yaml#/components/parameters/Limit'
      responses:
        '200':
          description: Contacts loaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicContactListResponse'
        '400': { $ref: '../../v1/components/errors.yaml#/components/responses/BadRequest' }
        '401': { $ref: '../../v1/components/errors.yaml#/components/responses/Unauthorized' }
        '403': { $ref: '../../v1/components/errors.yaml#/components/responses/Forbidden' }
        '429': { $ref: '../../v1/components/errors.yaml#/components/responses/TooManyRequests' }
        '500': { $ref: '../../v1/components/errors.yaml#/components/responses/InternalError' }
components:
  securitySchemes:
    serviceToken:
      $ref: '../components/v2-security.yaml#/components/securitySchemes/serviceToken'
  schemas:
    ContactStage:
      type: string
      description: Lead lifecycle. The normal flow is new to contacted to qualified, then converted or lost.
      enum: [new, contacted, qualified, converted, lost]
    ContactSource:
      type: string
      description: Where the contact originated. participant means it was pushed in from a campaign participant.
      enum: [registration, participant, manual, import]
    PublicContact:
      type: object
      description: |
        Whitelisted contact projection (toPublicContact). Optional properties
        are OMITTED, not null, when absent.
      required: [id, email, stage, source, tags]
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        firstName:
          type: string
        lastName:
          type: string
        company:
          type: string
        phone:
          type: string
        jobTitle:
          type: string
        language:
          type: string
          enum: [en, fr, pt-BR, es]
          description: |
            Since 1.1.0 — the language this contact is written to in, when their
            record states one.

            ADDITIVE and OPTIONAL: absent means "states nothing", never
            "English", and a client that ignores the field reads exactly the
            document it read yesterday.

            WHERE IT COMES FROM: a contact captured directly keeps whatever it
            was given; a Journey B sync from a campaign participant fills it only
            when the contact states nothing, so what the CRM was told directly is
            never overwritten by a roster push.
        stage:
          $ref: '#/components/schemas/ContactStage'
        source:
          $ref: '#/components/schemas/ContactSource'
        tags:
          type: array
          items:
            type: string
        createdAt:
          type: integer
          description: Epoch milliseconds.
        updatedAt:
          type: integer
          description: Epoch milliseconds.
    PublicContactListResponse:
      allOf:
        - $ref: '../../v1/components/envelopes.yaml#/components/schemas/SuccessEnvelope'
        - type: object
          required: [data, meta]
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/PublicContact'
            meta:
              $ref: '../components/v2-common.yaml#/components/schemas/PageMeta'
