openapi: 3.1.0
info:
  title: Banking Admin Customer Audience Connections
  description: |-
    The Customer Audience Connections API allows clients to connect customer audiences with similar resources in other providers. The implementation of this service determines how the audience will map to the resource in a provider. The implementation also determines the connection details, such as how often an external resource is synchronized with the audience and what the synchronization process entails. Only one connection can exist between an audience and a single provider `name`.
    Customer Audience Connections are stateful so that the client can view and manage the status of the connection. The following states are available:

      * `pending` indicates that the associated resource is still being created or updated in the provider.
      * `active` indicates that the audience and connected provider resource are actively linked and
        being synchronized.
      * `inactive` indicates that the connection was created, but the synchronization between resources
        has been suspended until the connection is activated again.
      * `failed` indicates that the service failed to establish the data connection between the audience
        and the connected provider.

    The audience connection operations are available only if the institution configuration indicates if the feature is enabled. Use the `getInstitution` operation in Admin Institutions API, then inspect the `enabledFeatures.customerAudienceConnections` value in the response.
  version: 0.7.0
  contact:
    name: Apiture
    url: https://developer.apiture.com/help/support/
    email: api@apiture.com
  termsOfService: https://developer.apiture.com/docs/Apiture-API-License-Agreement.pdf
  license:
    name: Apiture API License
    url: https://developer.apiture.com/docs/Apiture-API-License-Agreement.pdf
x-apiture-namespace: bankingCustomerAudienceConnections
tags:
  - name: Customer Audience Connections
    description: Customer Audience Connections
  - name: Customer Audience Connection Actions
    description: Actions on Customer Audience Connections
servers:
  - url: /bankingAdmin
paths:
  /customerAudienceConnections:
    get:
      summary: Return a collection of customer audience connections
      description: Return a collection of customer audience connections.
      operationId: listCustomerAudienceConnections
      x-apiture-api: bankingCustomerAudienceConnections
      x-apiture-group: customerAudienceConnections
      tags:
        - Customer Audience Connections
      parameters:
        - name: audience
          description: Return connections whose `audience.id` equals the given `audience` value.
          in: query
          schema:
            $ref: '#/components/schemas/resourceId'
        - name: state
          in: query
          description: Filter the response to only connections whose `state` is in this pipe-delimited set of state names.
          style: pipeDelimited
          explode: false
          schema:
            type: array
            minItems: 1
            maxItems: 4
            uniqueItems: true
            items:
              $ref: '#/components/schemas/customerAudienceConnectionState'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerAudienceConnections'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '422':
          description: |
            Unprocessable Entity. The request body and/or query parameters were well formed but otherwise invalid.

            This problem response may have one of the following `type` values:
            * [`https://static.api.apiture.com/errors/audienceConnectionsNotAvailable/v1.0.0`](https://static.api.apiture.com/errors/audienceConnectionsNotAvailable/v1.0.0)<br>
              The financial institution does not have customer audience connections enabled.
              Remediation: Enable the customer audience connection feature for the application and/or institution and retry the operation.

            * [`https://static.api.apiture.com/errors/invalidProviderKey/v1.0.0`](https://static.api.apiture.com/errors/invalidProviderKey/v1.0.0)<br>
              The given provider is not configured with a valid integration key.
              Remediation: Update the configured provider integration key and retry the operation.
          x-apiture-errors:
            - audienceConnectionsNotAvailable
            - invalidProviderKey
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problemResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/problemResponse'
        '429':
          $ref: '#/components/responses/429'
        4XX:
          $ref: '#/components/responses/4XX'
        5XX:
          $ref: '#/components/responses/5XX'
      security:
        - adminAccessToken:
            - adminData/read
    post:
      summary: Create a new customer audience connection
      description: Create a new customer audience connection within the customer audience connections collection.
      operationId: createCustomerAudienceConnection
      x-apiture-api: bankingCustomerAudienceConnections
      x-apiture-group: customerAudienceConnections
      tags:
        - Customer Audience Connections
      requestBody:
        required: true
        description: The data necessary to create a new customer audience connection.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/newCustomerAudienceConnection'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerAudienceConnection'
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Location:
              description: The URI of the new customer audience connection.
              schema:
                type: string
                format: uri-reference
                maxLength: 2048
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '409':
          description: |
            Conflict.

            This problem response may have one of the following `type` values:
            * [`https://static.api.apiture.com/errors/duplicateProviderAudienceConnection/v1.0.0`](https://static.api.apiture.com/errors/duplicateProviderAudienceConnection/v1.0.0)<br>
              The given audience already has a connection for the given provider `name`.
              Remediation: Reactivate the existing audience connection for the given provider `name`, or delete the existing connection and create a new one.
          x-apiture-errors:
            - duplicateProviderAudienceConnection
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problemResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/problemResponse'
        '422':
          description: |
            Unprocessable Entity. The request body and/or query parameters were well formed but otherwise invalid.

            This problem response may have one of the following `type` values:
            * [`https://static.api.apiture.com/errors/audienceConnectionsNotAvailable/v1.0.0`](https://static.api.apiture.com/errors/audienceConnectionsNotAvailable/v1.0.0)<br>
              The financial institution does not have customer audience connections enabled.
              Remediation: Enable the customer audience connection feature for the application and/or institution and retry the operation.

            * [`https://static.api.apiture.com/errors/invalidAudience/v1.0.0`](https://static.api.apiture.com/errors/invalidAudience/v1.0.0)<br>
              The given audience does not exist or is not eligible for a connection.
              Remediation: Pass the `id` of a valid, active audience.

            * [`https://static.api.apiture.com/errors/invalidProviderKey/v1.0.0`](https://static.api.apiture.com/errors/invalidProviderKey/v1.0.0)<br>
              The given provider is not configured with a valid integration key.
              Remediation: Update the configured provider integration key and retry the operation.

            * [`https://static.api.apiture.com/errors/unsupportedProviderName/v1.0.0`](https://static.api.apiture.com/errors/unsupportedProviderName/v1.0.0)<br>
              The given provider `name` is not supported by the application.
              Remediation: Pass the `name` of a valid provider.
          x-apiture-errors:
            - audienceConnectionsNotAvailable
            - invalidAudience
            - invalidProviderKey
            - unsupportedProviderName
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problemResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/problemResponse'
        '429':
          $ref: '#/components/responses/429'
        4XX:
          $ref: '#/components/responses/4XX'
        5XX:
          $ref: '#/components/responses/5XX'
      security:
        - adminAccessToken:
            - adminData/write
  /customerAudienceConnections/{customerAudienceConnectionId}:
    parameters:
      - $ref: '#/components/parameters/customerAudienceConnectionIdPathParam'
    get:
      summary: Fetch a representation of this customer audience connection
      description: Return the JSON representation of this customer audience connection resource.
      operationId: getCustomerAudienceConnection
      x-apiture-api: bankingCustomerAudienceConnections
      x-apiture-group: customerAudienceConnections
      tags:
        - Customer Audience Connections
      parameters:
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerAudienceConnection'
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404CustomerAudienceConnection'
        '422':
          description: |
            Unprocessable Entity. The request body and/or query parameters were well formed but otherwise invalid.

            This problem response may have one of the following `type` values:
            * [`https://static.api.apiture.com/errors/audienceConnectionsNotAvailable/v1.0.0`](https://static.api.apiture.com/errors/audienceConnectionsNotAvailable/v1.0.0)<br>
              The financial institution does not have customer audience connections enabled.
              Remediation: Enable the customer audience connection feature for the application and/or institution and retry the operation.

            * [`https://static.api.apiture.com/errors/invalidProviderKey/v1.0.0`](https://static.api.apiture.com/errors/invalidProviderKey/v1.0.0)<br>
              The given provider is not configured with a valid integration key.
              Remediation: Update the configured provider integration key and retry the operation.
          x-apiture-errors:
            - audienceConnectionsNotAvailable
            - invalidProviderKey
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problemResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/problemResponse'
        '429':
          $ref: '#/components/responses/429'
        4XX:
          $ref: '#/components/responses/4XX'
        5XX:
          $ref: '#/components/responses/5XX'
      security:
        - adminAccessToken:
            - adminData/read
    delete:
      summary: Delete this customer audience connection resource
      description: Delete this customer audience connection resource and any resources that are owned by it.
      operationId: deleteCustomerAudienceConnection
      x-apiture-api: bankingCustomerAudienceConnections
      x-apiture-group: customerAudienceConnections
      tags:
        - Customer Audience Connections
      responses:
        '204':
          $ref: '#/components/responses/204'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404CustomerAudienceConnection'
        '429':
          $ref: '#/components/responses/429'
        4XX:
          $ref: '#/components/responses/4XX'
        5XX:
          $ref: '#/components/responses/5XX'
      security:
        - adminAccessToken:
            - adminData/write
  /customerAudienceConnections/{customerAudienceConnectionId}/failed:
    parameters:
      - $ref: '#/components/parameters/customerAudienceConnectionIdPathParam'
    post:
      operationId: failCustomerAudienceConnection
      x-apiture-api: bankingCustomerAudienceConnections
      x-apiture-group: customerAudienceConnections
      summary: Fail a customer audience connection
      description: 'Fail a customer audience connection. This changes the `state` property of the customer audience connection to `failed`. The response is the updated representation of the customer audience connection. This operation is idempotent: no changes are made if the customer audience connection is already `failed`. The `If-Match` request header value, if passed, must match the current entity tag value of the customer audience connection.'
      tags:
        - Customer Audience Connection Actions
      parameters:
        - $ref: '#/components/parameters/ifMatchHeaderParam'
      responses:
        '200':
          description: OK. The operation succeeded. The customer audience connection was updated and its `state` changed to `failed`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerAudienceConnection'
            application/vnd.restful+json:
              schema:
                $ref: '#/components/schemas/customerAudienceConnection'
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404CustomerAudienceConnection'
        '409':
          $ref: '#/components/responses/409'
        '412':
          $ref: '#/components/responses/412'
        '422':
          description: |
            Unprocessable Entity. The customerAudienceConnection parameter was malformed or does not refer to an existing or accessible customer audience connection.

            This problem response may have one of the following `type` values:
            * [`https://static.api.apiture.com/errors/audienceConnectionsNotAvailable/v1.0.0`](https://static.api.apiture.com/errors/audienceConnectionsNotAvailable/v1.0.0)<br>
              The financial institution does not have customer audience connections enabled.
              Remediation: Enable the customer audience connection feature for the application and/or institution and retry the operation.

            * [`https://static.api.apiture.com/errors/invalidCustomerAudienceConnection/v1.0.0`](https://static.api.apiture.com/errors/invalidCustomerAudienceConnection/v1.0.0)<br>
              The customerAudienceConnection parameter is invalid.
              Remediation: Pass the ID of an existing customer audience connection.

            * [`https://static.api.apiture.com/errors/invalidProviderKey/v1.0.0`](https://static.api.apiture.com/errors/invalidProviderKey/v1.0.0)<br>
              The given provider is not configured with a valid integration key.
              Remediation: Update the configured provider integration key and retry the operation.
          x-apiture-errors:
            - audienceConnectionsNotAvailable
            - invalidCustomerAudienceConnection
            - invalidProviderKey
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problemResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/problemResponse'
        '429':
          $ref: '#/components/responses/429'
        4XX:
          $ref: '#/components/responses/4XX'
        5XX:
          $ref: '#/components/responses/5XX'
      security:
        - adminAccessToken:
            - adminData/write
  /customerAudienceConnections/{customerAudienceConnectionId}/inactive:
    parameters:
      - $ref: '#/components/parameters/customerAudienceConnectionIdPathParam'
    post:
      operationId: deactivateCustomerAudienceConnection
      x-apiture-api: bankingCustomerAudienceConnections
      x-apiture-group: customerAudienceConnections
      summary: Deactivate a customer audience connection
      description: 'Deactivate a customer audience connection. This changes the `state` property of the customer audience connection to `inactive`. The response is the updated representation of the customer audience connection. This operation is idempotent: no changes are made if the customer audience connection is already `inactive`. The `If-Match` request header value, if passed, must match the current entity tag value of the customer audience connection.'
      tags:
        - Customer Audience Connection Actions
      parameters:
        - $ref: '#/components/parameters/ifMatchHeaderParam'
      responses:
        '200':
          description: OK. The operation succeeded. The customer audience connection was updated and its `state` changed to `inactive`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerAudienceConnection'
            application/vnd.restful+json:
              schema:
                $ref: '#/components/schemas/customerAudienceConnection'
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404CustomerAudienceConnection'
        '409':
          $ref: '#/components/responses/409'
        '412':
          $ref: '#/components/responses/412'
        '422':
          description: |
            Unprocessable Entity. The customerAudienceConnection parameter was malformed or does not refer to an existing or accessible customer audience connection.

            This problem response may have one of the following `type` values:
            * [`https://static.api.apiture.com/errors/audienceConnectionsNotAvailable/v1.0.0`](https://static.api.apiture.com/errors/audienceConnectionsNotAvailable/v1.0.0)<br>
              The financial institution does not have customer audience connections enabled.
              Remediation: Enable the customer audience connection feature for the application and/or institution and retry the operation.

            * [`https://static.api.apiture.com/errors/invalidCustomerAudienceConnection/v1.0.0`](https://static.api.apiture.com/errors/invalidCustomerAudienceConnection/v1.0.0)<br>
              The customerAudienceConnection parameter is invalid.
              Remediation: Pass the ID of an existing customer audience connection.

            * [`https://static.api.apiture.com/errors/invalidProviderKey/v1.0.0`](https://static.api.apiture.com/errors/invalidProviderKey/v1.0.0)<br>
              The given provider is not configured with a valid integration key.
              Remediation: Update the configured provider integration key and retry the operation.
          x-apiture-errors:
            - audienceConnectionsNotAvailable
            - invalidCustomerAudienceConnection
            - invalidProviderKey
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problemResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/problemResponse'
        '429':
          $ref: '#/components/responses/429'
        4XX:
          $ref: '#/components/responses/4XX'
        5XX:
          $ref: '#/components/responses/5XX'
      security:
        - adminAccessToken:
            - adminData/write
  /customerAudienceConnections/{customerAudienceConnectionId}/active:
    parameters:
      - $ref: '#/components/parameters/customerAudienceConnectionIdPathParam'
    post:
      operationId: activateCustomerAudienceConnection
      x-apiture-api: bankingCustomerAudienceConnections
      x-apiture-group: customerAudienceConnections
      summary: Activate a customer audience connection
      description: 'Activate a customer audience connection. This changes the `state` property of the customer audience connection to `active`. The response is the updated representation of the customer audience connection. This operation is idempotent: no changes are made if the customer audience connection is already `active`. The `If-Match` request header value, if passed, must match the current entity tag value of the customer audience connection.'
      tags:
        - Customer Audience Connection Actions
      parameters:
        - $ref: '#/components/parameters/ifMatchHeaderParam'
      responses:
        '200':
          description: OK. The operation succeeded. The customer audience connection was updated and its `state` changed to `active`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customerAudienceConnection'
            application/vnd.restful+json:
              schema:
                $ref: '#/components/schemas/customerAudienceConnection'
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404CustomerAudienceConnection'
        '409':
          $ref: '#/components/responses/409'
        '412':
          $ref: '#/components/responses/412'
        '422':
          description: |
            Unprocessable Entity. The customerAudienceConnection parameter was malformed or does not refer to an existing or accessible customer audience connection.

            This problem response may have one of the following `type` values:
            * [`https://static.api.apiture.com/errors/audienceConnectionsNotAvailable/v1.0.0`](https://static.api.apiture.com/errors/audienceConnectionsNotAvailable/v1.0.0)<br>
              The financial institution does not have customer audience connections enabled.
              Remediation: Enable the customer audience connection feature for the application and/or institution and retry the operation.

            * [`https://static.api.apiture.com/errors/invalidCustomerAudienceConnection/v1.0.0`](https://static.api.apiture.com/errors/invalidCustomerAudienceConnection/v1.0.0)<br>
              The customerAudienceConnection parameter is invalid.
              Remediation: Pass the ID of an existing customer audience connection.

            * [`https://static.api.apiture.com/errors/invalidProviderKey/v1.0.0`](https://static.api.apiture.com/errors/invalidProviderKey/v1.0.0)<br>
              The given provider is not configured with a valid integration key.
              Remediation: Update the configured provider integration key and retry the operation.
          x-apiture-errors:
            - audienceConnectionsNotAvailable
            - invalidCustomerAudienceConnection
            - invalidProviderKey
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/problemResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/problemResponse'
        '429':
          $ref: '#/components/responses/429'
        4XX:
          $ref: '#/components/responses/4XX'
        5XX:
          $ref: '#/components/responses/5XX'
      security:
        - adminAccessToken:
            - adminData/write
components:
  securitySchemes:
    apiKey:
      type: apiKey
      name: API-Key
      in: header
      description: API Key based client identification. See details at [Secure Access](https://developer.apiture.com/docs/secure-access).
      x-resolved-from: ../../common/openapi.yaml#/components/securitySchemes/apiKey
    adminAccessToken:
      type: openIdConnect
      description: OpenId Connect (OIDC) authentication/authorization for an administrative user, such as financial institution staff or Apiture administrators. The client uses the `authorization_endpoint` and `token_endpoint` to obtain an access token to pass in the `Authorization` header. Those endpoints are available via the OIDC Configuration URL. The actual URL may vary with each financial institution. See details at [Secure Access](https://dx.apiture.com/docs/api/concepts/api-keys/).
      openIdConnectUrl: https://auth.apiture.com/oidc/.well-known/openid-configuration
      x-resolved-from: ../../common/openapi.yaml#/components/securitySchemes/adminAccessToken
  parameters:
    customerAudienceConnectionIdPathParam:
      name: customerAudienceConnectionId
      description: The unique identifier of this customer audience connection. This is an opaque string.
      in: path
      schema:
        $ref: '#/components/schemas/resourceId'
      required: true
    ifNoneMatchHeaderParam:
      name: If-None-Match
      description: The entity tag that was returned in the `ETag` response header of a previous call. If the resource's current entity tag value matches this header value, the `GET` will return 304 (Not Modified) and no response body, else the current resource representation and updated `ETag` is returned.
      in: header
      schema:
        $ref: '#/components/schemas/entityTag'
      x-resolved-from: ../../common/openapi.yaml#/components/parameters/ifNoneMatchHeaderParam
    ifMatchHeaderParam:
      name: If-Match
      description: The entity tag that was returned in the `ETag` response header of a previous call. If passed, this must match the current entity tag of the resource, else the operation fails with a 412 Precondition Failed error.
      in: header
      schema:
        $ref: '#/components/schemas/entityTag'
      x-resolved-from: ../../common/openapi.yaml#/components/parameters/ifMatchHeaderParam
  responses:
    '204':
      description: No Content. The operation succeeded but returned no response body.
      x-resolved-from: ../../common/openapi.yaml#/components/responses/204
    '400':
      description: |
        Bad Request. The request body, request headers, and/or query parameters are not well-formed.

        This problem response may have one of the following `type` values:
        * [`https://static.api.apiture.com/errors/badRequest/v1.0.0`](https://static.api.apiture.com/errors/badRequest/v1.0.0)<br>
          The request body and/or parameters was not well-formed.
          Remediation: Correct any syntax or schema errors in the request body or parameters.
      x-apiture-errors:
        - $ref: '#/components/x-apiture-errors/badRequest'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problemResponse'
            example:
              id: 3fbad566-be86-4b22-9ba6-3ca99fdc0799
              type: https://static.api.apiture.com/errors/badRequest/v1.0.0
              title: Bad Request
              status: 400
              occurredAt: '2022-04-25T12:42:21.375Z'
              detail: Input did not parse as JSON
              instance: https://static.api.apiture.com/banking/transfers/bb709151-575041fcd617
        application/json:
          schema:
            $ref: '#/components/schemas/problemResponse'
            example:
              id: 3fbad566-be86-4b22-9ba6-3ca99fdc0799
              type: https://static.api.apiture.com/errors/badRequest/v1.0.0
              title: Bad Request
              status: 400
              occurredAt: '2022-04-25T12:42:21.375Z'
              detail: Input did not parse as JSON
              instance: https://static.api.apiture.com/banking/transfers/bb709151-575041fcd617
      x-resolved-from: ../../common/openapi.yaml#/components/responses/400
    '401':
      description: |
        Unauthorized. The operation requires authentication but no authentication or insufficient authentication was given.

        This problem response may have one of the following `type` values:
        * [`https://static.api.apiture.com/errors/unauthorized/v1.0.0`](https://static.api.apiture.com/errors/unauthorized/v1.0.0)<br>
          The request lacks valid authentication credentials for the target resource or operation.
          Remediation: Authenticate the user and pass the required authorization with the request.
      x-apiture-errors:
        - $ref: '#/components/x-apiture-errors/unauthorized'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problemResponse'
            example:
              id: 3fbad566-be86-4b22-9ba6-3ca99fdc0799
              type: https://static.api.apiture.com/errors/unauthorized/v1.0.0
              title: Unauthorized
              status: 401
              occurredAt: '2022-04-25T12:42:21.375Z'
              detail: The request lacks valid authentication credentials
              instance: https://static.api.apiture.com/banking/transfers/bb709151-575041fcd617
        application/json:
          schema:
            $ref: '#/components/schemas/problemResponse'
            example:
              id: 3fbad566-be86-4b22-9ba6-3ca99fdc0799
              type: https://static.api.apiture.com/errors/unauthorized/v1.0.0
              title: Unauthorized
              status: 401
              occurredAt: '2022-04-25T12:42:21.375Z'
              detail: The request lacks valid authentication credentials
              instance: https://static.api.apiture.com/banking/transfers/bb709151-575041fcd617
      x-resolved-from: ../../common/openapi.yaml#/components/responses/401
    '403':
      description: |
        Forbidden. The authenticated caller is not authorized to perform the requested operation.

        This problem response may have one of the following `type` values:
        * [`https://static.api.apiture.com/errors/forbidden/v1.0.0`](https://static.api.apiture.com/errors/forbidden/v1.0.0)<br>
          The user or agent is not allowed to perform this operation; authentication credentials were provided in the request, but the server considers them insufficient to grant access.
          Remediation: Check the user's permissions and entitlements before attempting the operation.

        * [`https://static.api.apiture.com/errors/customerDisabled/v1.0.0`](https://static.api.apiture.com/errors/customerDisabled/v1.0.0)<br>
          The customer is disabled.
          Remediation: Have the customer contact the financial institution for support.

        * [`https://static.api.apiture.com/errors/antiMalwareRequired/v1.0.0`](https://static.api.apiture.com/errors/antiMalwareRequired/v1.0.0)<br>
          The financial institution requires the customer to have anti-malware software installed.
          Remediation: Direct the user to the software requirements guide to install the correct anti-malware software.

        * [`https://static.api.apiture.com/errors/modificationForbidden/v1.0.0`](https://static.api.apiture.com/errors/modificationForbidden/v1.0.0)<br>
          The customer is properly authenticated but not authorized to create, modify, or delete resources.
          Remediation: Avoid modification operation for customers with read-only authorization.

        * [`https://static.api.apiture.com/errors/challengeRequired/v1.0.0`](https://static.api.apiture.com/errors/challengeRequired/v1.0.0)<br>
          The operation requires the customer to complete an identity challenge.
          Remediation: Complete the challenge as per the problem response, and add an additional `Challenge` header to the call.
        The `attributes` object in the error may have the properties defined by the [`requiredIdentityChallenge` schema](#schema-requiredIdentityChallenge).
        * [`https://static.api.apiture.com/errors/challengeBlocked/v1.0.0`](https://static.api.apiture.com/errors/challengeBlocked/v1.0.0)<br>
          The user has failed challenges too many times and is blocked from attempting more or performing operations which require additional authentication.
          Remediation: Have the user end their login session and login again.

        * [`https://static.api.apiture.com/errors/noIdentityChallengeFactors/v1.0.0`](https://static.api.apiture.com/errors/noIdentityChallengeFactors/v1.0.0)<br>
          This operation requires an identity challenge, but the user does not have the necessary registered authentication factors.
          Remediation: Have the user register one or more challenge security code delivery factors.

        * [`https://static.api.apiture.com/errors/invalidIdentityChallengeHeader/v1.0.0`](https://static.api.apiture.com/errors/invalidIdentityChallengeHeader/v1.0.0)<br>
          The additional on-time `Challenge` header in this request is expired, already used, or otherwise invalid.
          Remediation: Supply a valid, unexpired, unclaimed `Challenge` header in the request.
      x-apiture-errors:
        - $ref: '#/components/x-apiture-errors/forbidden'
        - $ref: '#/components/x-apiture-errors/customerDisabled'
        - $ref: '#/components/x-apiture-errors/antiMalwareRequired'
        - $ref: '#/components/x-apiture-errors/modificationForbidden'
        - $ref: '#/components/x-apiture-errors/challengeRequired'
        - $ref: '#/components/x-apiture-errors/challengeBlocked'
        - $ref: '#/components/x-apiture-errors/noIdentityChallengeFactors'
        - $ref: '#/components/x-apiture-errors/invalidIdentityChallengeHeader'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problemResponse'
            example:
              id: 3fbad566-be86-4b22-9ba6-3ca99fdc0799
              type: https://static.api.apiture.com/errors/forbidden/v1.0.0
              title: Forbidden
              status: 403
              occurredAt: '2022-04-25T12:42:21.375Z'
              detail: The request has valid authentication, but the authenticated agent is forbidden from accessing this resource or operation
              instance: https://static.api.apiture.com/banking/transfers/bb709151-575041fcd617
        application/json:
          schema:
            $ref: '#/components/schemas/problemResponse'
            example:
              id: 3fbad566-be86-4b22-9ba6-3ca99fdc0799
              type: https://static.api.apiture.com/errors/forbidden/v1.0.0
              title: Forbidden
              status: 403
              occurredAt: '2022-04-25T12:42:21.375Z'
              detail: The request has valid authentication, but the authenticated agent is forbidden from accessing this resource or operation
              instance: https://static.api.apiture.com/banking/transfers/bb709151-575041fcd617
      x-resolved-from: ../../common/openapi.yaml#/components/responses/403
    '409':
      description: |
        Conflict. The request conflicts with the state of the application.

        This problem response may have one of the following `type` values:
        * [`https://static.api.apiture.com/errors/conflict/v1.0.0`](https://static.api.apiture.com/errors/conflict/v1.0.0)<br>
          The request could not be completed due to a conflict with the current state of the target resource.
          Remediation: Try another operation that is allowed.
      x-apiture-errors:
        - $ref: '#/components/x-apiture-errors/conflict'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problemResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/problemResponse'
      x-resolved-from: ../../common/openapi.yaml#/components/responses/409
    '412':
      description: |
        Precondition Failed. One or more conditions given in the request header fields evaluated to false when tested on the server.

        This problem response may have one of the following `type` values:
        * [`https://static.api.apiture.com/errors/preconditionFailed/v1.0.0`](https://static.api.apiture.com/errors/preconditionFailed/v1.0.0)<br>
          One or more conditions given in the request header fields evaluated to false when tested on the server.
          Remediation: Update resources and use it's most recent ETag or modification time stamp.
      x-apiture-errors:
        - $ref: '#/components/x-apiture-errors/preconditionFailed'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problemResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/problemResponse'
      x-resolved-from: ../../common/openapi.yaml#/components/responses/412
    '429':
      description: |
        Too Many Requests. The client has sent too many requests in a given amount of time.

        This problem response may have one of the following `type` values:
        * [`https://static.api.apiture.com/errors/tooManyRequests/v1.0.0`](https://static.api.apiture.com/errors/tooManyRequests/v1.0.0)<br>
          The client has sent too many requests in a given amount of time, exceeding rate limiting.
          Remediation: Slow down the rate of API calls.
      x-apiture-errors:
        - $ref: '#/components/x-apiture-errors/tooManyRequests'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problemResponse'
            example:
              id: 3fbad566-be86-4b22-9ba6-3ca99fdc0799
              type: https://static.api.apiture.com/errors/tooManyRequests/v1.0.0
              title: Too Many Requests
              status: 429
              occurredAt: '2022-04-25T12:42:21.375Z'
              detail: The user has sent too many requests in a given amount of time.
              instance: https://static.api.apiture.com/banking/transfers/bb709151-575041fcd617
        application/json:
          schema:
            $ref: '#/components/schemas/problemResponse'
            example:
              id: 3fbad566-be86-4b22-9ba6-3ca99fdc0799
              type: https://static.api.apiture.com/errors/tooManyRequests/v1.0.0
              title: Too Many Requests
              status: 429
              occurredAt: '2022-04-25T12:42:21.375Z'
              detail: The user has sent too many requests in a given amount of time.
              instance: https://static.api.apiture.com/banking/transfers/bb709151-575041fcd617
      x-resolved-from: ../../common/openapi.yaml#/components/responses/429
    404CustomerAudienceConnection:
      description: Not Found. There is no such customer audience connection resource at the specified `{customerAudienceConnectionId}`.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problemResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/problemResponse'
    4XX:
      description: Client Request Problem. The client request had a problem not listed under another specific 400-level HTTP response code. View the `detail` in the problem response for additional details.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problemResponse'
            example:
              id: 3fbad566-be86-4b22-9ba6-3ca99fdc0799
              type: https://static.api.apiture.com/errors/methodNotAllowed/v1.0.0
              title: Method Not Allowed
              status: 405
              occurredAt: '2022-04-25T12:42:21.375Z'
              detail: This HTTP method is not allowed for the given resource URL.
              instance: https://static.api.apiture.com/banking/transfers/bb709151-575041fcd617
        application/json:
          schema:
            $ref: '#/components/schemas/problemResponse'
            example:
              id: 3fbad566-be86-4b22-9ba6-3ca99fdc0799
              type: https://static.api.apiture.com/errors/methodNotAllowed/v1.0.0
              title: Method Not Allowed
              status: 405
              occurredAt: '2022-04-25T12:42:21.375Z'
              detail: This HTTP method is not allowed for the given resource URL.
              instance: https://static.api.apiture.com/banking/transfers/bb709151-575041fcd617
      x-resolved-from: ../../common/openapi.yaml#/components/responses/4XX
    5XX:
      description: Server Problem. The server encountered a problem not listed under another specific 500-level HTTP response code. View the `detail` in the problem response for additional details.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/problemResponse'
            example:
              id: 3fbad566-be86-4b22-9ba6-3ca99fdc0799
              type: https://static.api.apiture.com/errors/gatewayTimeout/v1.0.0
              title: Insufficient Storage
              status: 507
              occurredAt: '2022-04-25T12:42:21.375Z'
              detail: The server is unable to store the representation needed to successfully complete the request.
              instance: https://static.api.apiture.com/banking/transfers/bb709151-575041fcd617
        application/json:
          schema:
            $ref: '#/components/schemas/problemResponse'
            example:
              id: 3fbad566-be86-4b22-9ba6-3ca99fdc0799
              type: https://static.api.apiture.com/errors/gatewayTimeout/v1.0.0
              title: Insufficient Storage
              status: 507
              occurredAt: '2022-04-25T12:42:21.375Z'
              detail: The server is unable to store the representation needed to successfully complete the request.
              instance: https://static.api.apiture.com/banking/transfers/bb709151-575041fcd617
      x-resolved-from: ../../common/openapi.yaml#/components/responses/5XX
  schemas:
    customerAudienceConnectionState:
      title: Customer Audience Connection State (v1.0.0)
      description: |+
        The state of a customer audience connection

        <strong><code>customerAudienceConnectionState</code></strong> strings may have one of the following
        [enumerated values](https://developer.apiture.com/docs/concepts/label-groups#enumerations):

        <table>
        <tr>
          <th>Value</th><th>Description</th>
        </tr>

        <tr>
            <td><strong><code>active</code></strong></td><td>Active: <p>The audience connection is active and available for use.</p>
        </td>
            </tr>
        <tr>
            <td><strong><code>inactive</code></strong></td><td>Inactive: <p>The audience connection is inactive. The connection must be reactivated before it can be used.</p>
        </td>
            </tr>
        <tr>
            <td><strong><code>pending</code></strong></td><td>Pending: <p>The audience connection is pending and not yet available for use.</p>
        </td>
            </tr>
        <tr>
            <td><strong><code>failed</code></strong></td><td>Failed: <p>The audience connection failed. Activate the connection to retry connecting.</p>
        </td>
            </tr>
        </table>

      type: string
      x-apiture-enum: customerAudienceConnectionState
      enum:
        - active
        - inactive
        - pending
        - failed
      x-apiture-version: 1.0.0
    customerAudienceReference:
      title: Customer Audience Reference (v1.0.0)
      description: An object that references a Customer Audience by its `id` and `name`.
      required:
        - id
      type: object
      properties:
        id:
          description: The unique identifier for this audience resource. This is an immutable opaque string.
          $ref: '#/components/schemas/resourceId'
        name:
          description: The audience name.
          type: string
          format: text
          maxLength: 100
      example:
        id: 590c0c441f3241de9526
        name: New Customers Ages 35-49
      x-apiture-version: 1.0.0
    customerAudienceConnectionFields:
      title: Customer Audience Connection Fields (v1.0.0)
      description: Common fields of the customer audience connection resource used to build other model schemas.
      type: object
      x-apiture-fragment: true
      properties:
        audience:
          $ref: '#/components/schemas/customerAudienceReference'
        provider:
          description: Properties that pertain to the audience connection provider.
          $ref: '#/components/schemas/customerAudienceConnectionProvider'
      x-apiture-version: 1.0.0
    immutableCustomerAudienceConnectionFields:
      title: Immutable Customer Audience Connection Fields (v1.0.0)
      description: Fields used to define other Customer Audience Connection schemas.
      x-apiture-fragment: true
      type: object
      properties:
        id:
          description: The unique identifier for this customer audience connection resource. This is an immutable opaque string.
          $ref: '#/components/schemas/readOnlyResourceId'
        state:
          $ref: '#/components/schemas/customerAudienceConnectionState'
        createdAt:
          description: The date-time when the audience connection was created.
          $ref: '#/components/schemas/readOnlyTimestamp'
        createdBy:
          description: The admin user that created this audience connection.
          $ref: '#/components/schemas/userAccountReference'
        updatedAt:
          description: The date-time when the audience connection was last updated.
          $ref: '#/components/schemas/readOnlyTimestamp'
        updatedBy:
          description: The admin user that last updated this audience connection.
          $ref: '#/components/schemas/userAccountReference'
        lastSyncedAt:
          description: The date-time when the audience connection was last synced with the provider.
          $ref: '#/components/schemas/readOnlyTimestamp'
      x-apiture-version: 1.0.0
    newCustomerAudienceConnection:
      title: New Customer Audience Connection (v1.0.0)
      description: Representation used to create a new customer audience connection.
      type: object
      required:
        - audience
        - provider
      allOf:
        - $ref: '#/components/schemas/abstractBody'
        - $ref: '#/components/schemas/customerAudienceConnectionFields'
      example:
        audience:
          id: 590c0c441f3241de9526
          name: New Customers Ages 35-49
        provider:
          name: pendo
          resourceId: 9TJNmXu5IA2222CL9S51HBUsxDY
      x-apiture-version: 1.0.0
    customerAudienceConnectionProvider:
      title: Customer Audience Connection Provider (v1.0.0)
      description: Properties that are specific to the audience connection's provider for an institution.
      type: object
      properties:
        name:
          description: The audience connection provider name.
          type: string
          format: text
          maxLength: 80
        connectedResourceId:
          description: A value that uniquely identifies the resource associated with the audience in the connected provider.
          $ref: '#/components/schemas/externalResourceId'
      x-apiture-version: 1.0.0
    customerAudienceConnectionItem:
      title: Customer Audience Connection Item (v1.0.0)
      description: Summary representation of a customer audience connection resource in customer audience connections collections. To fetch the full representation of this customer audience connection, use the [`getCustomerAudienceConnection`](#op-getCustomerAudienceConnection) operation, passing this item's `id` field as the `customerAudienceConnectionId` path parameter.
      type: object
      unevaluatedProperties: false
      required:
        - id
        - state
        - audience
        - provider
        - createdAt
        - updatedAt
        - lastSyncedAt
      allOf:
        - $ref: '#/components/schemas/abstractBody'
        - $ref: '#/components/schemas/customerAudienceConnectionFields'
        - $ref: '#/components/schemas/immutableCustomerAudienceConnectionFields'
      example:
        id: 0399abed-fd3d
        state: active
        provider:
          name: pendo
          resourceId: 9TJNmXu5IA2222CL9S51HBUsxDY
        audience:
          id: 590c0c441f3241de9526
          name: New Customers Ages 35-49
        createdAt: '2024-09-28T10:31:41.375Z'
        createdBy:
          id: 22707c1196c6f1c6938e
          username: MetricMagician
          firstName: Andy
          lastName: Analytics
        updatedAt: '2024-09-28T10:31:41.375Z'
        updatedBy:
          id: 22707c1196c6f1c6938e
          username: MetricMagician
          firstName: Andy
          lastName: Analytics
        lastSyncedAt: '2024-09-28T10:31:41.375Z'
      x-apiture-version: 1.0.0
    customerAudienceConnection:
      title: Customer Audience Connection (v1.0.0)
      description: Representation of a customer audience connection resource.
      type: object
      unevaluatedProperties: false
      required:
        - id
        - state
        - audience
        - provider
        - createdAt
        - createdBy
        - updatedAt
        - updatedBy
        - lastSyncedAt
      allOf:
        - $ref: '#/components/schemas/customerAudienceConnectionFields'
        - $ref: '#/components/schemas/immutableCustomerAudienceConnectionFields'
      example:
        id: 0399abed-fd3d
        state: active
        provider:
          name: pendo
          resourceId: 9TJNmXu5IA2222CL9S51HBUsxDY
        audience:
          id: 590c0c441f3241de9526
          name: New Customers Ages 35-49
        createdAt: '2024-09-28T10:31:41.375Z'
        createdBy:
          id: 22707c1196c6f1c6938e
          username: MetricMagician
          firstName: Andy
          lastName: Analytics
        updatedAt: '2024-09-28T10:31:41.375Z'
        updatedBy:
          id: 22707c1196c6f1c6938e
          username: MetricMagician
          firstName: Andy
          lastName: Analytics
        lastSyncedAt: '2024-09-28T10:31:41.375Z'
      x-apiture-version: 1.0.0
    customerAudienceConnections:
      title: Customer Audience Connection Collection (v1.0.0)
      description: Collection of customer audience connections. The items in the collection are ordered in the `items` array.
      type: object
      unevaluatedProperties: false
      allOf:
        - type: object
          required:
            - items
          properties:
            items:
              description: An array containing customer audience connection items.
              type: array
              maxItems: 1000
              items:
                $ref: '#/components/schemas/customerAudienceConnectionItem'
      example:
        items:
          - id: 0399abed-fd3d
            state: active
            provider:
              name: pendo
              resourceId: 9TJNmXu5IA2222CL9S51HBUsxDY
            audience:
              id: 590c0c441f3241de9526
              name: New Customers Ages 35-49
            createdAt: '2024-09-28T10:31:41.375Z'
            createdBy:
              id: 22707c1196c6f1c6938e
              username: MetricMagician
              firstName: Andy
              lastName: Analytics
            updatedAt: '2024-09-28T10:31:41.375Z'
            updatedBy:
              id: 22707c1196c6f1c6938e
              username: MetricMagician
              firstName: Andy
              lastName: Analytics
            lastSyncedAt: '2024-09-28T10:31:41.375Z'
          - id: d62c0701-0d74-4836-83f9-ebf3709442ea
            state: inactive
            provider:
              name: pendo
              resourceId: q6PioQIWPFAhOA
            audience:
              id: 590c0c441f3241de9526
              name: New Customers Ages 35-49
            createdAt: '2024-09-29T10:31:41.375Z'
            createdBy:
              id: 22707c1196c6f1c6938e
              username: MetricMagician
              firstName: Andy
              lastName: Analytics
            updatedAt: '2024-09-29T10:31:41.375Z'
            updatedBy:
              id: 22707c1196c6f1c6938e
              username: MetricMagician
              firstName: Andy
              lastName: Analytics
            lastSyncedAt: '2024-09-29T10:31:41.375Z'
      x-apiture-version: 1.0.0
    customerAudienceConnectionReference:
      title: Customer Audience Connection Reference (v1.0.0)
      description: An object that references a customer audience connection by its `id`, `provider`, and `state`.
      required:
        - id
        - provider
        - state
      type: object
      properties:
        id:
          description: The unique identifier for this customer audience connection resource. This is an immutable opaque string.
          $ref: '#/components/schemas/resourceId'
        provider:
          description: Properties that pertain to the audience connection provider.
          $ref: '#/components/schemas/customerAudienceConnectionProvider'
        state:
          $ref: '#/components/schemas/customerAudienceConnectionState'
      example:
        id: 0399abed-fd3d
        state: active
        provider:
          name: pendo
          resourceId: q6PioQIWPFAhOA
      x-apiture-version: 1.0.0
    resourceId:
      x-apiture-version: 1.0.1
      title: Resource Identifier (v1.0.1)
      description: The unique, opaque system identifier for a resource. This case-sensitive ID is also used as path parameters in URLs or in other properties or parameters that reference a resource by ID rather than URL.
      type: string
      pattern: ^[-_:.~$a-zA-Z0-9]{6,48}$
      minLength: 6
      maxLength: 48
      x-resolved-from: ../../common/openapi.yaml#/components/schemas/resourceId
    problemResponse:
      title: Problem Response (v0.4.1)
      x-apiture-version: 0.4.1
      description: API problem or error response, as per [RFC 9457 application/problem+json](https://tools.ietf.org/html/rfc9457).
      type: object
      allOf:
        - $ref: '#/components/schemas/abstractBody'
        - $ref: '#/components/schemas/apiProblem'
      example:
        id: 3fbad566-be86-4b22-9ba6-3ca99fdc0799
        type: https://static.api.apiture.com/errors/noSuchAccount/v1.0.0
        title: Account Not Found
        status: 422
        occurredAt: '2022-04-25T12:42:21.375Z'
        detail: No account exists for the given account reference
        instance: https://static.api.apiture.com/banking/transfers/bb709151-575041fcd617
      x-resolved-from: ../../common/openapi.yaml#/components/schemas/problemResponse
    entityTag:
      title: Entity Tag (v1.0.0)
      description: An strong or weak [HTTP Entity Tag (ETag)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag). Strong ETags take the form `"{printable-non-control-ASCII-characters}"` but for backwards compatibility the surrounding double quotes are optional. Weak ETags take the form `W/"{printable-non-control-ASCII-characters}"`.
      type: string
      minLength: 3
      maxLength: 512
      pattern: ^(([\x21\x23-\x7e]{1,512})|(W\/\"[\x21\x23-\x7e]{1,509}\"))$
      example: W/"325cf1cc-e370-4baf-8faf-c6db23f195a2"
      x-apiture-version: 1.0.0
      x-resolved-from: ../../common/openapi.yaml#/components/schemas/entityTag
    readOnlyResourceId:
      x-apiture-version: 1.0.1
      title: Read-only Resource Identifier (v1.0.1)
      description: The unique, opaque system-assigned identifier for a resource. This case-sensitive ID is also used in URLs as path parameters or in other properties or parameters that reference a resource by ID rather than URL. Resource IDs are immutable.
      readOnly: true
      allOf:
        - $ref: '#/components/schemas/resourceId'
      x-resolved-from: ../../common/openapi.yaml#/components/schemas/readOnlyResourceId
    readOnlyTimestamp:
      title: Read-Only Timestamp (v1.0.0)
      description: 'A readonly or derived timestamp (an instant in time) formatted in [RFC 3339](https://tools.ietf.org/html/rfc3339) `date-time` UTC format: `YYYY-MM-DDThh:mm:ss.sssZ`.'
      type: string
      minLength: 20
      maxLength: 30
      format: date-time
      readOnly: true
      example: '2021-10-30T19:06:04.250Z'
      x-apiture-since: 0.4.0
      x-resolved-from: ../../common/openapi.yaml#/components/schemas/readOnlyTimestamp
      x-apiture-version: 1.0.0
    userAccountReference:
      x-apiture-version: 2.0.0
      title: User Account Reference (v2.0.0)
      description: The representation of a user account.
      type: object
      required:
        - id
        - firstName
        - lastName
        - username
      properties:
        id:
          description: The immutable, unique, opaque identifier for the user.
          $ref: '#/components/schemas/resourceId'
        firstName:
          description: The user's first name.
          type: string
          format: text
          maxLength: 56
        lastName:
          description: The user's last name.
          type: string
          format: text
          maxLength: 56
        username:
          description: The user's login name.
          $ref: '#/components/schemas/customerUsername'
      example:
        id: 0399abed-fd3d
        firstName: Benny
        lastName: Billings
        username: bbillings
      x-resolved-from: ../../common/openapi.yaml#/components/schemas/userAccountReference
    abstractBody:
      title: Abstract Body (v0.2.0)
      x-apiture-version: 0.2.0
      description: An abstract schema used to define other request and response body model schemas.
      x-apiture-fragment: true
      type: object
      properties: {}
      x-resolved-from: ../../common/openapi.yaml#/components/schemas/abstractBody
    externalResourceId:
      x-apiture-version: 1.1.0
      title: External Resource Identifier (v1.1.0)
      description: The unique, opaque system identifier for an external resource. This case-sensitive ID is also used as path parameters in URLs or in other properties or parameters that reference an external resource by ID rather than URL.
      type: string
      format: text
      readOnly: true
      minLength: 1
      maxLength: 256
      x-resolved-from: ../../common/openapi.yaml#/components/schemas/externalResourceId
    apiProblem:
      x-apiture-version: 1.2.1
      title: API Problem (v1.2.1)
      description: API problem or error, as per [RFC 7807 application/problem+json](https://tools.ietf.org/html/rfc7807).
      type: object
      properties:
        type:
          type: string
          format: uri-reference
          description: |
            A [URI reference (RFC3986)](https://tools.ietf.org/html/rfc3986) that identifies the problem type. If present, this is the URL of human-readable HTML documentation for the problem type. When this member is not present, its value is assumed to be `"about:blank"`.
          example: https://static.api.apiture.com/errors/forbidden/v1.0.0
          maxLength: 2048
        title:
          type: string
          description: |
            A short, human-readable summary of the problem type. The title is usually the same for all problem with the same `type`.
          maxLength: 120
          format: text
          example: User is not authorized to perform the requested action or access the requested resource.
        status:
          type: integer
          format: int32
          description: |
            The [HTTP status code](https://datatracker.ietf.org/doc/html/rfc7231#section-6) for this occurrence of the problem.
          minimum: 100
          maximum: 599
          example: 403
        detail:
          type: string
          description: |
            A human-readable explanation specific to this occurrence of the problem.
          maxLength: 256
          format: text
          example: User is not authorized to perform this operation.
        instance:
          type: string
          format: uri-reference
          description: |
            A URI reference that identifies the specific occurrence of the problem. This is the URI of an API resource that the problem is related to, with a unique error correlation ID URI fragment
          example: https://prduction.api.apiture.com/banking/accounts/ad80fc3e722q5402a#189c13ff-c54c-45f7-b8e0-c88984ba724d
          maxLength: 2048
        id:
          description: The unique identifier for this problem. This is an immutable opaque string.
          $ref: '#/components/schemas/readOnlyResourceId'
        occurredAt:
          description: The timestamp when the problem occurred, in [RFC 3339](https://tools.ietf.org/html/rfc3339) date-time `YYYY-MM-DDThh:mm:ss.sssZ` format, UTC.
          $ref: '#/components/schemas/readOnlyTimestamp'
        problems:
          description: Optional root-causes if there are multiple problems in the request or API call processing.
          type: array
          maxItems: 128
          items:
            $ref: '#/components/schemas/apiProblem'
        attributes:
          type: object
          description: Additional optional attributes related to the problem. This data conforms to the schema associated with the error type.
      example:
        id: 3fbad566-be86-4b22-9ba6-3ca99fdc0799
        type: https://static.api.apiture.com/errors/accountNotFound/v1.0.0
        title: Account Not Found
        status: 422
        occurredAt: '2022-04-25T12:42:21.375Z'
        detail: No account exists at the given account_url
        instance: https://static.api.apiture.com/banking/transfers/bb709151-575041fcd617
      x-resolved-from: ../../common/openapi.yaml#/components/schemas/apiProblem
    customerUsername:
      x-apiture-version: 2.0.0
      title: Customer Username (v2.0.0)
      description: A customer's login username.
      type: string
      format: text
      minLength: 5
      maxLength: 20
      x-resolved-from: ../../common/openapi.yaml#/components/schemas/customerUsername
    requiredIdentityChallenge:
      x-apiture-version: 1.2.3
      title: Required Challenge (v1.2.3)
      description: A request from the service for the user to verify their identity. This contains a challenge ID, the corresponding operation ID, and a list of challenge factors for identity verification. The user must complete one of these challenge factors to satisfy the challenge. This schema defines the attributes in the 401 [Unauthorized problem response](#schema-apiProblem) when the 401 problem type name is `challengeRequired`. See the "Challenge API" for details.
      type: object
      required:
        - operationId
        - challengeId
        - factors
      properties:
        operationId:
          $ref: '#/components/schemas/challengeOperationId'
        challengeId:
          description: The unique ID of this challenge instance. This is an opaque string. This is passed when starting a challenge factor or when validating the identity challenge responses.
          $ref: '#/components/schemas/readOnlyResourceId'
        factors:
          description: 'A list of challenge factors. The user must complete one of these challenge factors. The `labels` in each factor identify one or more channels the user may use, such as a list of email addresses the system may use to send a one-time passcode to the user. ***Note**: The same channel may be used by multiple factors in the array of factors. For example, the user''s primary mobile phone number may be used for both an `sms` factor and a `voice` factor.'
          type: array
          minItems: 1
          maxItems: 8
          items:
            $ref: '#/components/schemas/challengeFactor'
      example:
        operationId: createTransfer
        challengeId: 0504076c566a3cf7009c
        factors:
          - type: sms
            labels:
              - '9876'
            id: 85c0ee5753fcd0b0953f
          - type: voice
            labels:
              - '9876'
            id: d089e10a80a8627df37b
          - type: voice
            labels:
              - '6754'
            id: 10506ecf9d1c2ee00403
          - type: email
            labels:
              - an****nk@example.com
              - an****98@example.com
            id: e917d671cb2f030b56f1
          - type: authenticatorToken
            labels:
              - Acme fob
            id: fe6c452d7da0bbb4e407
          - type: securityQuestions
            securityQuestions:
              questions:
                - id: q1
                  prompt: What is your mother's maiden name?
                - id: q4
                  prompt: What is your high school's name?
                - id: q9
                  prompt: What is the name of your first pet?
            id: df33c6f88a37d6b3f0a6
      x-resolved-from: ../../common/openapi.yaml#/components/schemas/requiredIdentityChallenge
    challengeOperationId:
      x-apiture-version: 1.0.1
      title: Challenge Operation ID (v1.0.1)
      description: The ID of an operation/action for which the user must verify their identity via an identity challenge. This is passed when starting a challenge factor or when validating the identity challenge responses.
      type: string
      pattern: ^[-a-zA-Z0-9$_]{6,48}$
      minLength: 6
      maxLength: 48
      x-resolved-from: ../../common/openapi.yaml#/components/schemas/challengeOperationId
    challengeFactor:
      x-apiture-version: 1.2.1
      title: Challenge Factor (v1.2.1)
      description: A challenge factor. See [`requiredIdentityChallenge`](#schema-requiredIdentityChallenge) for multiple examples.
      type: object
      required:
        - type
      properties:
        id:
          description: |-
            The ID of an a challenge factor. This ID is unique within the challenge factors associated with a challenge. The client should pass this `id` value as the `factorId` when starting or verifying a challenge factor.

            *Note*: The `id` will become `required` in a future update to this schema.
          $ref: '#/components/schemas/challengeFactorId'
        type:
          $ref: '#/components/schemas/challengeFactorType'
        labels:
          description: A list of text label which identifies the channel(s) through which the user completes the challenge. For an `sms` or `voice` challenge, the only label item is the last four digits of the corresponding phone number. For an `email` challenge, each label is the masked email address.
          type: array
          minItems: 1
          maxItems: 4
          items:
            type: string
            maxLength: 300
            format: text
        securityQuestions:
          $ref: '#/components/schemas/challengeSecurityQuestions'
      example:
        type: sms
        labels:
          - '9876'
      x-resolved-from: ../../common/openapi.yaml#/components/schemas/challengeFactor
    challengeFactorId:
      title: Challenge Factor ID (v1.0.0)
      description: The ID of an a challenge factor. This ID is unique within the factors offered with a challenge.
      type: string
      pattern: ^[-a-zA-Z0-9$_]{3,48}$
      minLength: 3
      maxLength: 48
      x-resolved-from: ../../common/openapi.yaml#/components/schemas/challengeFactorId
      x-apiture-version: 1.0.0
    challengeFactorType:
      title: Challenge Factor Type (v1.0.0)
      description: |+
        The name of challenge factor.

        <strong><code>challengeFactorType</code></strong> strings may have one of the following
        [enumerated values](https://developer.apiture.com/docs/concepts/label-groups#enumerations):

        <table>
        <tr>
          <th>Value</th><th>Description</th>
        </tr>

        <tr>
            <td><strong><code>sms</code></strong></td><td>SMS: <p>One-time passcode sent to the primary mobile phone number</p>
        </td>
            </tr>
        <tr>
            <td><strong><code>email</code></strong></td><td>Email: <p>One-time passcode sent to the primary email address</p>
        </td>
            </tr>
        <tr>
            <td><strong><code>voice</code></strong></td><td>Voice: <p>One-time passcode communicated via automated voice phone call</p>
        </td>
            </tr>
        <tr>
            <td><strong><code>authenticatorToken</code></strong></td><td>authenticator Token: <p>One-time passcode issued by a pre-registered hardware device, such as a token key fob, or an authenticator app</p>
        </td>
            </tr>
        <tr>
            <td><strong><code>securityQuestions</code></strong></td><td>Security Questions: <p>Prompt with the user&#39;s security questions registered with their security profile</p>
        </td>
            </tr>
        </table>

      type: string
      x-apiture-enum: challengeFactorType
      enum:
        - sms
        - email
        - voice
        - securityQuestions
        - authenticatorToken
      x-resolved-from: ../../common/openapi.yaml#/components/schemas/challengeFactorType
      x-apiture-version: 1.0.0
    challengeSecurityQuestions:
      x-apiture-version: 1.0.1
      title: Challenge Security Questions (v1.0.1)
      description: Describes a `securityQuestions` challenge. This is omitted if the challenge `type` is not `securityQuestions`.
      type: object
      required:
        - questions
      properties:
        questions:
          description: The array of security questions.
          type: array
          minItems: 1
          maxItems: 8
          items:
            $ref: '#/components/schemas/challengeSecurityQuestion'
      example:
        questions:
          - id: q1
            prompt: What is your mother's maiden name?
          - id: q4
            prompt: What is your high school's name?
          - id: q9
            prompt: What is the name of your first pet?
      x-resolved-from: ../../common/openapi.yaml#/components/schemas/challengeSecurityQuestions
    challengeSecurityQuestion:
      x-apiture-version: 1.0.1
      title: Challenge Security Question (v1.0.1)
      description: A single security question within the `questions` array of the [`challengeSecurityQuestions`](#schema-challengeSecurityQuestions)
      type: object
      required:
        - id
        - prompt
      properties:
        id:
          description: The unique ID of security question prompt. This should be included in the [`challengeVerification`](#schema-challengeVerification) response as the `promptId`.
          $ref: '#/components/schemas/challengePromptId'
        prompt:
          description: The text prompt of this security question.
          type: string
          format: text
          maxLength: 80
      example:
        id: 74699fa628911e762ea5
        prompt: What is your mother's maiden name?
      x-resolved-from: ../../common/openapi.yaml#/components/schemas/challengeSecurityQuestion
    challengePromptId:
      title: Challenge Prompt ID (v1.0.0)
      description: The unique ID of a prompt (such as a security question) in a challenge factor.
      type: string
      pattern: ^[-_:.~$a-zA-Z0-9]+$
      minLength: 1
      maxLength: 48
      x-resolved-from: ../../common/openapi.yaml#/components/schemas/challengePromptId
      x-apiture-version: 1.0.0
  headers:
    ETag:
      description: The value of this resource's _entity tag_, to be passed with `If-Match` and `If-None-Match` request headers in other conditional API calls for this resource.
      schema:
        $ref: '#/components/schemas/entityTag'
      x-resolved-from: ../../common/openapi.yaml#/components/headers/ETag
  x-apiture-errors:
    badRequest:
      description: The request body and/or parameters was not well-formed.
      remediation: Correct any syntax or schema errors in the request body or parameters.
      x-resolved-from: ../../common/openapi.yaml#/components/x-apiture-errors/badRequest
    unauthorized:
      description: The request lacks valid authentication credentials for the target resource or operation.
      remediation: Authenticate the user and pass the required authorization with the request.
      x-resolved-from: ../../common/openapi.yaml#/components/x-apiture-errors/unauthorized
    forbidden:
      description: The user or agent is not allowed to perform this operation; authentication credentials were provided in the request, but the server considers them insufficient to grant access.
      remediation: Check the user's permissions and entitlements before attempting the operation.
      x-resolved-from: ../../common/openapi.yaml#/components/x-apiture-errors/forbidden
    customerDisabled:
      description: The customer is disabled.
      remediation: Have the customer contact the financial institution for support.
      x-resolved-from: ../../common/openapi.yaml#/components/x-apiture-errors/customerDisabled
    antiMalwareRequired:
      description: The financial institution requires the customer to have anti-malware software installed.
      remediation: Direct the user to the software requirements guide to install the correct anti-malware software.
      x-resolved-from: ../../common/openapi.yaml#/components/x-apiture-errors/antiMalwareRequired
    modificationForbidden:
      description: The customer is properly authenticated but not authorized to create, modify, or delete resources.
      remediation: Avoid modification operation for customers with read-only authorization.
      x-resolved-from: ../../common/openapi.yaml#/components/x-apiture-errors/modificationForbidden
    challengeRequired:
      description: The operation requires the customer to complete an identity challenge.
      remediation: Complete the challenge as per the problem response, and add an additional `Challenge` header to the call.
      attributes:
        $ref: '#/components/schemas/requiredIdentityChallenge'
      x-resolved-from: ../../common/openapi.yaml#/components/x-apiture-errors/challengeRequired
    challengeBlocked:
      description: The user has failed challenges too many times and is blocked from attempting more or performing operations which require additional authentication.
      remediation: Have the user end their login session and login again.
      x-resolved-from: ../../common/openapi.yaml#/components/x-apiture-errors/challengeBlocked
    noIdentityChallengeFactors:
      description: This operation requires an identity challenge, but the user does not have the necessary registered authentication factors.
      remediation: Have the user register one or more challenge security code delivery factors.
      x-resolved-from: ../../common/openapi.yaml#/components/x-apiture-errors/noIdentityChallengeFactors
    invalidIdentityChallengeHeader:
      description: The additional on-time `Challenge` header in this request is expired, already used, or otherwise invalid.
      remediation: Supply a valid, unexpired, unclaimed `Challenge` header in the request.
      x-resolved-from: ../../common/openapi.yaml#/components/x-apiture-errors/invalidIdentityChallengeHeader
    conflict:
      description: The request could not be completed due to a conflict with the current state of the target resource.
      remediation: Try another operation that is allowed.
      x-resolved-from: ../../common/openapi.yaml#/components/x-apiture-errors/conflict
    preconditionFailed:
      description: One or more conditions given in the request header fields evaluated to false when tested on the server.
      remediation: Update resources and use it's most recent ETag or modification time stamp.
      x-resolved-from: ../../common/openapi.yaml#/components/x-apiture-errors/preconditionFailed
    tooManyRequests:
      description: The client has sent too many requests in a given amount of time, exceeding rate limiting.
      remediation: Slow down the rate of API calls.
      x-resolved-from: ../../common/openapi.yaml#/components/x-apiture-errors/tooManyRequests
x-apiture-errors:
  invalidCustomerAudienceConnection:
    description: The customerAudienceConnection parameter is invalid.
    remediation: Pass the ID of an existing customer audience connection.
  unsupportedProviderName:
    description: The given provider `name` is not supported by the application.
    remediation: Pass the `name` of a valid provider.
  invalidProviderKey:
    description: The given provider is not configured with a valid integration key.
    remediation: Update the configured provider integration key and retry the operation.
  invalidAudience:
    description: The given audience does not exist or is not eligible for a connection.
    remediation: Pass the `id` of a valid, active audience.
  audienceConnectionsNotAvailable:
    description: The financial institution does not have customer audience connections enabled.
    remediation: Enable the customer audience connection feature for the application and/or institution and retry the operation.
  duplicateProviderAudienceConnection:
    description: The given audience already has a connection for the given provider `name`.
    remediation: Reactivate the existing audience connection for the given provider `name`, or delete the existing connection and create a new one.
x-apiture-traits:
  - api:
      name: admin customer audience connections
      applied: true
      basePath: customer audience connections
  - resource:
      name: customer audience connection
      excludeMethods:
        - put
        - patch
      cursorPaged: false
      applied: true
  - action:
      name: customer audience connection
      state: active
      verb: activate
      applied: true
  - action:
      name: customer audience connection
      state: inactive
      verb: deactivate
      applied: true
  - action:
      name: customer audience connection
      state: failed
      verb: fail
      applied: true
  - security:
      baseScope: adminData
      applied: true
x-resolved-from: ../../adminCustomerAudienceConnections/status-codes-openapi.yaml
x-resolved-at: '2024-12-09T22:02:17.694Z'
x-apiture-annotated-at: '2024-12-09T22:02:17.924Z'
