Zywave Activation API

openapi: 3.2.0
info:
  title: Client Engagement API v1.0 Activation API
  version: v1.0
servers:
- url: https://api.zywave.com
tags:
- name: Activation
paths:
  /v3/clientEngagement/v1.0/org/{organizationId}/agency/{agencyId}/activation/activate:
    post:
      tags:
      - Activation
      summary: Activates a client.
      description: 'Idempotent — if an Employer already exists for the AccountId, this method

        skips creation and returns the existing EmployerId. Tool-package assignment

        is queued via the same job pipeline used by the invitation flow.


        Note: this method does not currently restore previously-deactivated Employers.

        The downstream Employers service filters soft-deleted rows out of all reads,

        so an Employer that was Deactivated for this AccountId is invisible here and

        a new row would be created. A proper reactivation path requires either a

        downstream restore endpoint or an extension to IEmployerHelper.'
      operationId: Activation_Activate
      parameters:
      - name: organizationId
        in: path
        required: true
        schema:
          type: string
          format: guid
        x-position: 1
      - name: agencyId
        in: path
        required: true
        schema:
          type: integer
          format: int32
        x-position: 2
      requestBody:
        x-name: request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivationRequest'
        required: true
        x-position: 3
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: integer
                format: int32
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /v3/clientEngagement/v1.0/org/{organizationId}/agency/{agencyId}/activation/deactivate:
    post:
      tags:
      - Activation
      summary: Deactivates a client by soft-deleting the Employer record bound to the supplied…
      operationId: Activation_Deactivate
      parameters:
      - name: organizationId
        in: path
        required: true
        schema:
          type: string
          format: guid
        x-position: 1
      - name: agencyId
        in: path
        required: true
        schema:
          type: integer
          format: int32
        x-position: 2
      requestBody:
        x-name: request
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivationRequest'
        required: true
        x-position: 3
      responses:
        '204':
          description: ''
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /v3/clientEngagement/v1.0/org/{organizationId}/agency/{agencyId}/activation/invite:
    post:
      tags:
      - Activation
      summary: Sends one or more invitations to clients or account contacts.
      operationId: Activation_Invite
      parameters:
      - name: organizationId
        in: path
        required: true
        schema:
          type: string
          format: guid
        x-position: 1
      - name: agencyId
        in: path
        required: true
        schema:
          type: integer
          format: int32
        x-position: 2
      requestBody:
        x-name: invitationRequest
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InviteRequest'
        required: true
        x-position: 3
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type:
                - integer
                - 'null'
                format: int32
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    InviteType:
      type: string
      description: The kind of invitation being sent.
      x-enumNames:
      - Unknown
      - ClientPortal
      - BenefitDocumentBuilder
      enum:
      - Unknown
      - ClientPortal
      - BenefitDocumentBuilder
    ProblemDetails:
      type: object
      additionalProperties: {}
      properties:
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
          format: int32
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
    InviteRequest:
      type: object
      description: Payload describing a set of invitations to send to recipients derived from lists, accounts, contacts, or prior invitations.
      additionalProperties: false
      required:
      - portalId
      - type
      properties:
        listIds:
          type: array
          description: The IDs of static lists from which recipients should be derived.
          items:
            type: integer
            format: int32
        accountIds:
          type: array
          description: The IDs of accounts to invite directly.
          items:
            type: integer
            format: int32
        accountContactIds:
          type: array
          description: The IDs of account contacts to invite directly.
          items:
            type: integer
            format: int32
        invitationIds:
          type: array
          description: The IDs of existing invitations the send should reference (used for series).
          items:
            type: integer
            format: int32
        toolPackageIds:
          type: array
          description: The IDs of tool packages to attach to the invitation.
          items:
            type: integer
            format: int32
        portalId:
          type: integer
          description: The ID of the portal the invitation targets. Required.
          format: int32
          maximum: 2147483647
          minimum: 1
        subject:
          type:
          - string
          - 'null'
          description: The email subject line.
          maxLength: 512
          minLength: 0
        header:
          type:
          - string
          - 'null'
          description: The email header text.
          maxLength: 512
          minLength: 0
        emailBody:
          type:
          - string
          - 'null'
          description: The email body (HTML or text).
          maxLength: 65536
          minLength: 0
        actionText:
          type:
          - string
          - 'null'
          description: The call-to-action text rendered in the email button.
          maxLength: 128
          minLength: 0
        sendFromUser:
          type: boolean
          description: Whether the email should be sent from the acting user rather than a shared sender.
        agencyDomainId:
          type:
          - integer
          - 'null'
          description: The ID of the agency mail domain to send from. Falls back to default if not owned by the agency.
          format: int32
          maximum: 2147483647
          minimum: 1
        type:
          description: The type of invitation being sent.
          oneOf:
          - $ref: '#/components/schemas/InviteType'
        bulkReinvite:
          type: boolean
          description: Whether this is a bulk reinvite (processed as a background job).
        bulkInviteNew:
          type: boolean
          description: Whether this is a bulk invite for new contacts (processed as a background job).
        isSeries:
          type: boolean
          description: Whether this send represents part of an invitation series.
        scheduledDate:
          type: string
          description: The date/time the invitation should be sent (used for scheduled sends).
          format: date-time
        fromEmailAddress:
          type:
          - string
          - 'null'
          description: Optional override for the from-email address. Defaults to the configured notification address.
          format: email
          maxLength: 255
          minLength: 0
    ActivationRequest:
      type: object
      description: Payload for activating or deactivating a client.
      additionalProperties: false
      required:
      - accountId
      properties:
        accountId:
          type: integer
          description: The identifier of the account to activate or deactivate.
          format: int32
          maximum: 2147483647
          minimum: 1
        toolPackageIds:
          type:
          - array
          - 'null'
          description: 'Optional tool packages to assign to the account on activation. Ignored on

            deactivation.'
          items:
            type: integer
            format: int32