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) - Participants
  version: 1.4.1
  description: |
    Read and upsert campaign participants from an external CRM. Responses are
    the whitelisted PublicParticipant projection: the linked Assessor.io userId, the
    avatar URL, and the assigned-auditor records are internal and never
    returned. Reads need participants:read; the upsert needs participants:write
    and is written to the account audit log.

    1.1.0 MADE TWO metadata KEYS THE SYSTEM'S. takerLink and synthetic
    can no longer be written, overwritten or removed through the upsert, on
    create or on update; a body naming one is answered 200/201 with the stored
    value intact and the refused keys in meta.preservedKeys. The rest of the bag
    is unchanged.

    1.2.0 GAVE THE UPSERT A DELETE CHANNEL. A metadata key sent as an
    explicit JSON null is now REMOVED from the participant's bag rather than
    stored as a null, which is what the same body has always meant on the v1
    PATCH. The two system-owned keys are the exception and are still refused,
    never removed. The Public API (v2) guide on docs.assessor.io describes
    both changes.
servers:
  - url: /
security:
  - serviceToken: []
tags:
  - name: PublicParticipants
paths:
  /api/v2/public/accounts/{accountId}/campaigns/{campaignId}/participants:
    get:
      tags: [PublicParticipants]
      operationId: v2ListParticipants
      summary: List a campaign's participants.
      description: |
        Paginated. The status, email, and label filters are applied in-process
        after the campaign's participants are loaded, and combine with AND.
        Scope participants:read.
      parameters:
        - $ref: '../components/v2-common.yaml#/components/parameters/AccountId'
        - $ref: '../components/v2-common.yaml#/components/parameters/CampaignId'
        - name: status
          in: query
          required: false
          description: Exact-match participant status. An unknown value simply matches nothing (no 400).
          schema:
            $ref: '#/components/schemas/ParticipantStatus'
        - name: email
          in: query
          required: false
          description: Exact match, case-insensitive.
          schema:
            type: string
            format: email
        - name: label
          in: query
          required: false
          description: Keeps participants whose labels array contains this exact label (case-sensitive).
          schema:
            type: string
        - $ref: '../components/v2-common.yaml#/components/parameters/Page'
        - $ref: '../components/v2-common.yaml#/components/parameters/Limit'
      responses:
        '200':
          description: Participants loaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicParticipantListResponse'
        '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' }
        '404': { $ref: '../../v1/components/errors.yaml#/components/responses/NotFound' }
        '429': { $ref: '../../v1/components/errors.yaml#/components/responses/TooManyRequests' }
        '500': { $ref: '../../v1/components/errors.yaml#/components/responses/InternalError' }
    post:
      tags: [PublicParticipants]
      operationId: v2UpsertParticipant
      summary: Create or update one participant, keyed on email.
      description: |
        The CRM push. email is the upsert key and is lower-cased before
        matching, so re-sending the same contact updates the existing
        participant instead of duplicating it. Responds 201 when a participant
        was created and 200 when an existing one was updated; meta.created says
        which happened. Every call writes a PARTICIPANT audit-log entry
        attributed to the token's principal id with via=v2_public_api.
        Scope participants:write.

        METADATA IS MERGED, AND TWO KEYS ARE THE SYSTEM'S (1.1.0). Every
        top-level key the body names replaces that key on the participant; every
        key it does not name survives. Since 1.2.0 a key sent as null is
        DELETED from the bag - see the metadata property below. takerLink and synthetic are the
        exceptions: they are application state read back as truth - takerLink
        holds the link-revocation generation a signed taker link is checked
        against, and synthetic holds the provenance a manufactured cohort is
        purged by - so the API can neither write nor remove them, on either
        branch of the upsert. A body naming one is answered 200/201 with the
        stored value intact and the refused keys listed in meta.preservedKeys,
        NOT 400: a sync that re-sends the whole bag it read a minute ago is the
        ordinary case, and refusing it would make a correlation bag unwritable
        for the callers it exists for. The same list is enforced on the v1
        PATCH; it lives in one module.
      parameters:
        - $ref: '../components/v2-common.yaml#/components/parameters/AccountId'
        - $ref: '../components/v2-common.yaml#/components/parameters/CampaignId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertParticipantRequest'
      responses:
        '200':
          description: An existing participant with this email was updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertParticipantResponse'
        '201':
          description: A new participant was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertParticipantResponse'
        '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' }
        '404': { $ref: '../../v1/components/errors.yaml#/components/responses/NotFound' }
        '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:
    ParticipantStatus:
      type: string
      enum: [Invited, Active, Suspended, Completed]
    PublicParticipant:
      type: object
      description: |
        Whitelisted participant projection (toPublicParticipant). userId,
        avatarUrl, assignedAuditors, and updatedAt are internal and excluded.
        Optional properties are OMITTED, not null, when absent; metadata is
        omitted entirely when it has no keys.
      required: [id, campaignId, email, status, labels]
      properties:
        id:
          type: string
        campaignId:
          type: string
        email:
          type: string
          format: email
        firstName:
          type: string
        lastName:
          type: string
        affiliation:
          type: string
        role:
          type: string
        language:
          type: string
          enum: [en, fr, pt-BR, es]
          description: |
            The language this person is written to in, when their record
            states one.

            ABSENT MEANS "STATES NOTHING", never "English": a recipient with no
            stated language is written to in both of the account's languages
            rather than one guessed at. ADDITIVE and OPTIONAL — a client that
            ignores it reads exactly the document it read yesterday, and
            `metadata.lang` (the earlier convention) is still read as the fallback, so a
            CRM that has been writing that key keeps being heard.
        organisationId:
          type: string
          description: |
            The `organisations` row this participant belongs to, when one
            has been resolved. ADDITIVE and OPTIONAL: `metadata.organisation`
            still carries the name exactly as before, so a client that ignores
            this field reads what it read yesterday. Absent means "no row", not
            "no organisation" — the name still resolves through the documented
            fallback chain. Read the rows at
            `GET /api/v1/accounts/{accountId}/organisations`.
        status:
          $ref: '#/components/schemas/ParticipantStatus'
        labels:
          type: array
          items:
            type: string
        metadata:
          type: object
          description: |
            Free-form integrator bag round-tripped verbatim. Capped at 50 keys
            on write. This is the bag AS THE ROW HOLDS IT after the write, not
            the fragment you sent, so a key you deleted with a null (1.2.0) is
            simply absent here.
          additionalProperties: true
        createdAt:
          type: integer
          description: Epoch milliseconds.
    UpsertParticipantRequest:
      type: object
      description: |
        Validated by normalizeParticipantUpsert. Unknown properties are ignored.
        Blank strings for the optional name/affiliation/role fields are treated
        as absent.
      required: [email]
      properties:
        email:
          type: string
          format: email
          description: Required upsert key. Must contain '@'. Lower-cased before matching.
        firstName:
          type: string
        lastName:
          type: string
        affiliation:
          type: string
        role:
          type: string
        language:
          type: string
          nullable: true
          enum: [en, fr, pt-BR, es, null]
          description: |
            Since 1.4.0 — the language this person is written to in.

            AN EXPLICIT null CLEARS it — the metadata rule from 1.2.0 ("one door,
            one meaning") applied to a field rather than to a bag key, so this endpoint and the
            v1 PATCH .../participants/{participantId} mean the same thing by the
            same body. Omit the key to leave the stored value alone. On the
            CREATE branch a null is simply silence: there is nothing to clear.

            A value outside the enum is a 400 naming the vocabulary — an
            integrator sending "de" has a bug, and a silent 200 would hide it.
        status:
          $ref: '#/components/schemas/ParticipantStatus'
        labels:
          type: array
          description: Trimmed and de-duplicated; empty strings are dropped.
          items:
            type: string
        metadata:
          type: object
          description: |
            Plain object, at most 50 keys - anything larger is rejected with
            400. Shallow-merged into the participant's stored bag: named keys
            replace, unnamed keys survive, and nesting is not merged.

            A NULL DELETES THE KEY (1.2.0). Sending {"crm_id": null}
            removes crm_id from the stored bag; the key is then absent, not
            present with a null value, so a reader never has to special-case
            one. It is the same body, and now the same meaning, as the v1
            PATCH .../participants/{participantId}. Deleting a key the row does
            not carry is a no-op, on the create branch as much as the update,
            and false, 0 and "" are VALUES - only null deletes. Before 1.2.0 a
            null was stored verbatim.

            metadata.segments is a null like any other: it clears the whole
            segment key, unless the same request also names an axis (through
            either door), in which case the value you just wrote wins.

            The system-owned keys takerLink and synthetic are the exception at
            both ends: they are dropped from the merge whatever their value,
            a null for one REMOVES NOTHING, and each is reported in
            meta.preservedKeys.
          additionalProperties: true
    PublicParticipantListResponse:
      allOf:
        - $ref: '../../v1/components/envelopes.yaml#/components/schemas/SuccessEnvelope'
        - type: object
          required: [data, meta]
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/PublicParticipant'
            meta:
              $ref: '../components/v2-common.yaml#/components/schemas/PageMeta'
    UpsertParticipantResponse:
      allOf:
        - $ref: '../../v1/components/envelopes.yaml#/components/schemas/SuccessEnvelope'
        - type: object
          required: [data, meta]
          properties:
            data:
              $ref: '#/components/schemas/PublicParticipant'
            meta:
              type: object
              required: [created]
              properties:
                created:
                  type: boolean
                  description: true when a participant row was inserted, false when an existing one was updated.
                preservedKeys:
                  type: array
                  description: |
                    Added in 1.1.0. The system-owned metadata keys this request
                    tried to write, which were kept as the row already holds
                    them. Present ONLY when the body named one, so its absence
                    means nothing was refused. Listed in the order the
                    server-owned list declares them, not the order the body
                    wrote them.
                  items:
                    type: string
                    enum: [takerLink, synthetic]
