openapi: 3.0.0
servers:
  - url: 'https://api.devbank.apiture.com/invitations'
x-note: DO NOT EDIT THIS GENERATED FILE. Edit source file src/openapi/openapi.yaml
x-note-generated-by: openapi-schema-resolver
x-note-generated-on: '2020-08-12T12:18:21-0400'
info:
  title: Invitations
  description: >-
    This API allows digital banking customers to send invitations to other people to become joint owners on personal accounts or to become authorized
    signers of business organizations.


    When a user creates a new invitation (`createInvitation` below), the service sends an email, on behalf of the financial institution, to the
    invitee's email address with instructions to accept the invitation by visiting a web page. The link in the generated email includes parameters
    that describe the invitation resource, including but not limited to `invitationId`.  The `invitationId` is required on the `verifyInvitation`
    operation below.


    The "shared secret" is a string the invitee shares the inviter to verify their identity.  See (`sharedSecret` below)


    Invitation States may be one of the following:

      * **`sent`** Invitation sent to invitee
      * **`accepted`** Invitation accepted by invitee
      * **`completed`** Invitee has been added to their invited role
      * **`revoked`** Invitation revoked by inviter
      * **`expired`** Invitation expired

    The invitation also references the account or organization they are being invited to join, depending on the `type` of the invitation. For joint
    owner invitations, other existing joint owners on the account can see outstanding invitations for the account. For authorized signer invitation,
    other existing joint owners can see outstanding invitations for the business organization.


    The Inviter should share the secret with the invitee through another secure channel (such as face to face or in a phone conversation) so that
    unauthorized people cannot accept the invitation.


    The Inviter can `revoke` an invitation if the state of the invitation is `sent`.


    When the invitee visits the web form listed in their invitation email, they enter the `sharedSecret` to accept. The client can use the
    `verifyInvitation` operation below to determine if the invitee entered the secret correctly. If they enter the data correctly, the invitation is
    `accepted`.


    If not already users, invitees must register as users on the financial institution's digital banking platform in order to assume these roles.
    Unverified users must also execute the financial institution's identity verification process before they are added as a joint user or authorized
    signer.  Once added as a joint user or authorized signer, the invitation is `completed`.


    Inviters can update an invitation's shared secret. Inviters can also request an invitation be resent, or they can revoke an invitation. Unaccepted
    invitations expire after some time (such as 30 or 45 days).
  version: 0.3.3
  contact:
    name: Apiture
    url: 'https://developer.apiture.com'
    email: api@apiture.com
  termsOfService: 'https://developer.apiture.com/docs/Apiture-Open-API-License-Agreement.pdf'
tags:
  - name: API
    description: The Invitations API
  - name: Invitation
    description: Invitations
  - name: Verification
    description: Invitation Verifications
paths:
  /invitations:
    get:
      summary: Return a collection of invitations
      description: >-
        Return a [paginated](http://developer.apiture.com/docs/concepts/pagination) [sortable](http://developer.apiture.com/docs/concepts/sorting)
        [filterable](http://developer.apiture.com/docs/concepts/filtering) [searchable](http://developer.apiture.com/docs/concepts/searching)
        collection of invitations. The [links](http://developer.apiture.com/docs/concepts/links) in the response include pagination links.
      operationId: getInvitations
      x-apiture-implemented: true
      tags:
        - Invitation
      x-apiture-traits:
        sortBy:
          - type
          - state
        itemSchema: invitations
        filters:
          state:
            filter:
              - eq
              - ne
              - in
          type:
            filter:
              - eq
              - ne
              - in
          emailAddress:
            filter:
              - eq
              - contains
              - search
          accountUri:
            filter:
              - eq
              - contains
              - search
          organizationUri:
            filter:
              - eq
              - contains
              - search
          createdBy:
            filter:
              - eq
              - contains
              - search
          customerId:
            filter:
              - eq
              - contains
              - search
      parameters:
        - name: start
          in: query
          description: The zero-based index of the first invitation item to include in this page. The default 0 denotes the beginning of the collection.
          schema:
            type: integer
            format: int64
            default: 0
        - name: limit
          in: query
          description: The maximum number of invitation representations to return in this page.
          schema:
            type: integer
            format: int32
            default: 100
        - name: sortBy
          in: query
          description: 'Optional sort criteria. See [sort criteria format](http://developer.apiture.com/docs/concepts/sorting), such as `?sortBy=field1,-field2`.'
          schema:
            type: string
        - $ref: '#/components/parameters/filterQueryParam'
        - $ref: '#/components/parameters/qQueryParam'
        - $ref: '#/components/parameters/pendingInvitationsParam'
        - $ref: '#/components/parameters/accountUriQueryParam'
        - $ref: '#/components/parameters/organizationUriQueryParam'
        - $ref: '#/components/parameters/stateQueryParam'
        - $ref: '#/components/parameters/typeQueryParam'
        - $ref: '#/components/parameters/emailAddressQueryParam'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/invitations'
            application/json:
              schema:
                $ref: '#/components/schemas/invitations'
        '400':
          $ref: '#/components/responses/400'
        '422':
          $ref: '#/components/responses/422'
      security:
        - apiKey: []
          accessToken:
            - banking/read
    post:
      summary: Create a new invitation
      description: Create a new invitation resource and send the invitation email to the invitee.
      operationId: createInvitation
      x-apiture-implemented: true
      tags:
        - Invitation
      responses:
        '201':
          description: Created
          headers:
            Location:
              description: >-
                The URI of the new resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with
                *`scheme`*`://host`
              schema:
                type: string
                format: uri
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
                operations which update the resource.
              schema:
                type: string
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/invitation'
            application/json:
              schema:
                $ref: '#/components/schemas/invitation'
        '400':
          $ref: '#/components/responses/400'
        '409':
          $ref: '#/components/responses/409CreateInvitation'
      security:
        - apiKey: []
          accessToken:
            - banking/write
      requestBody:
        content:
          application/hal+json:
            schema:
              $ref: '#/components/schemas/createInvitation'
          application/json:
            schema:
              $ref: '#/components/schemas/createInvitation'
        description: The data necessary to create a new invitation.
        required: true
  '/invitations/{invitationId}':
    get:
      summary: Fetch a representation of this invitation
      description: 'Return a [HAL](http://developer.apiture.com/docs/concepts/hal) representation of this invitation resource.'
      operationId: getInvitation
      x-apiture-implemented: true
      tags:
        - Invitation
      parameters:
        - $ref: '#/components/parameters/invitationIdPathParam'
        - $ref: '#/components/parameters/ifNoneMatchHeaderParam'
      responses:
        '200':
          description: OK
          headers:
            ETag:
              description: >-
                The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
                operations which update this invitation resource.
              schema:
                type: string
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/invitation'
            application/json:
              schema:
                $ref: '#/components/schemas/invitation'
        '304':
          $ref: '#/components/responses/304'
        '404':
          $ref: '#/components/responses/404Invitation'
      security:
        - apiKey: []
          accessToken:
            - banking/read
    delete:
      summary: Delete this invitation resource
      description: Delete this invitation resource and any resources that are owned by it.
      operationId: deleteInvitation
      x-apiture-implemented: true
      tags:
        - Invitation
      parameters:
        - $ref: '#/components/parameters/invitationIdPathParam'
      responses:
        '204':
          $ref: '#/components/responses/204Deleted'
      security:
        - apiKey: []
          accessToken:
            - banking/delete
  /revoked:
    post:
      summary: Revoke an Invitation
      description: >-
        Revoke an invitation that is eligible to be revoked.  Only Invitations which are `sent` can be revoked.  This operation is invoked from the
        `apiture:revoke` link on an Invitation, which only exists if the action is allowed.  This changes the `state` to `revoked`.
      operationId: revokeInvitation
      tags:
        - Invitation
      parameters:
        - $ref: '#/components/parameters/invitationQueryParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/invitation'
            application/json:
              schema:
                $ref: '#/components/schemas/invitation'
        '400':
          $ref: '#/components/responses/400'
        '409':
          $ref: '#/components/responses/409InvitationStateChange'
        '422':
          $ref: '#/components/responses/422'
      security:
        - apiKey: []
          accessToken:
            - banking/write
  /sent:
    post:
      summary: Send an Invitation
      description: >-
        This action will re-send an already `sent` invitation to the invitee. Only Invitations which are already `sent` can be re-sent.  This
        operation is invoked from  the `apiture:send` link on an Invitation, which only exists if the action is allowed.  There is a configurable
        limit of times that an invitation can be re-sent.
      operationId: sendInvitation
      tags:
        - Invitation
      parameters:
        - $ref: '#/components/parameters/invitationQueryParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/invitation'
            application/json:
              schema:
                $ref: '#/components/schemas/invitation'
        '400':
          $ref: '#/components/responses/400'
        '409':
          $ref: '#/components/responses/409InvitationStateChange'
        '422':
          $ref: '#/components/responses/422'
      security:
        - apiKey: []
          accessToken:
            - banking/write
  /completed:
    post:
      summary: Complete an Invitation
      description: >-
        Complete an invitation that is eligible to be completed.  Only Invitations which are `accepted` can be completed.  This admin operation is
        invoked from the `apiture:complete` link on an Invitation, which only exists if the action is allowed.  This changes the `state` to
        `completed`. `Completed` means the desired result (user added as joint owner or authorized signer) has been completed.
      operationId: completeInvitation
      tags:
        - Invitation
      parameters:
        - $ref: '#/components/parameters/invitationQueryParam'
        - $ref: '#/components/parameters/ifMatchHeaderParam'
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/invitation'
            application/json:
              schema:
                $ref: '#/components/schemas/invitation'
        '400':
          $ref: '#/components/responses/400'
        '409':
          $ref: '#/components/responses/409InvitationStateChange'
        '422':
          $ref: '#/components/responses/422'
      security:
        - apiKey: []
          accessToken:
            - banking/write
  /verifications:
    post:
      summary: Verify an Invitation
      description: >-
        Verify an Invitation that is eligible to be verified. Only Invitations in a state of `sent` can be verified. `sharedSecret` and `invitationId`
        are required. This operation increases the `verificationCount` of the invitation identified by `invitationId`. Invitations that are `revoked`
        or `expired` are not processed. This operation does not verify invitations with a state of `revoked` or `expired`.
      operationId: verifyInvitation
      x-apiture-implemented: true
      tags:
        - Verification
      responses:
        '200':
          description: OK - the invitation was matched and accepted.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/verification'
            application/json:
              schema:
                $ref: '#/components/schemas/verification'
        '400':
          $ref: '#/components/responses/400'
        '409':
          $ref: '#/components/responses/409VerifyInvitation'
        '429':
          $ref: '#/components/responses/429'
      security:
        - apiKey: []
          accessToken:
            - banking/write
      requestBody:
        content:
          application/hal+json:
            schema:
              $ref: '#/components/schemas/verification'
          application/json:
            schema:
              $ref: '#/components/schemas/verification'
        description: The data necessary to verify an invitation.
        required: true
  /:
    get:
      summary: Top-level resources and operations in this API
      description: Return links to the top-level resources and operations in this API.
      operationId: getApi
      x-apiture-implemented: true
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/root'
            application/json:
              schema:
                $ref: '#/components/schemas/root'
      tags:
        - API
      security:
        - apiKey: []
  /apiDoc:
    get:
      summary: Return API definition document
      description: Return the OpenAPI document that describes this API.
      operationId: getApiDoc
      x-apiture-implemented: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
            application/openapi+json;version=2.0:
              schema:
                type: object
            application/openapi+yaml;version=2.0:
              schema:
                type: object
            application/hal+json:
              schema:
                type: object
      tags:
        - API
      security:
        - apiKey: []
x-apiture-errors:
  invitationAccessDenied:
    description: The credentials supplied in the request are insufficient to grant access
    remediation: Check the supplied credentials for validity
  jointOwnersDisabled:
    description: Co owners are not supported in this account.
    remediation: Contact your financial institution.
  verificationInvitationExpired:
    description: The invitation you are attempting to accept is expired.
    remediation: Check to ensure that you are following the latest invitation email or contact your inviter.
  verificationInvitationRevoked:
    description: The invitation you are attempting to accept is revoked.
    remediation: Check to ensure that you are following the latest invitation email or contact your inviter.
x-apiture-traits:
  - api:
      title: Invitations
      basePath: invitations
      applied: true
      links:
        - getApi
        - getApiDoc
        - getInvitations
        - createInvitation
        - verifyInvitation
  - resource:
      name: invitation
      description: An invitation to join digital banking
      simpleModelSchema: true
      applied: true
  - resource:
      name: verification
      description: Representation of verification resources
      simpleModelSchema: true
      applied: true
  - security:
      baseScope: banking
      applied: true
components:
  schemas:
    verification:
      x-apiture-version: 2.0.0
      title: Verification
      description: Representation of verification resources.
      required:
        - sharedSecret
        - invitationId
      example:
        sharedSecret: obsolete obese octopus
        invitationId: d62c0701-0d74-4836-83f9-ebf3709442ea
        _profile: 'https://api.apiture.com/schemas/invitations/verification/v2.0.0/profile.json'
      x-apiture-composition:
        - $ref: '#/components/schemas/abstractResource'
        - properties:
            - firstName
            - lastName
            - identification
            - sharedSecret
            - invitationId
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
          type: object
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
        _error:
          description: An object which describes an error. This value is omitted if the operation succeeded without error.
          type: object
          allOf:
            - $ref: '#/components/schemas/error'
        firstName:
          x-apiture-deprecated: true
          description: 'The first name of the invitee. **Warning**: This property is deprecated and no longer used in invitation verification.'
          type: string
        lastName:
          x-apiture-deprecated: true
          description: 'The lastName name of the invitee. **Warning**: This property is deprecated and no longer used in invitation verification.'
          type: string
        identification:
          x-apiture-deprecated: true
          description: >-
            The last 4 digits of the government ID (SSN or other ID) of invitee. **Warning**: This property is deprecated and no longer used in
            invitation verification.
          type: string
        sharedSecret:
          description: A string shared by the inviter with the invitee to verify their identity.
          type: string
          minLength: 8
        invitationId:
          description: 'A optional id of an invitation resource.  If included, the service will compare the key data against this invitation only.'
          type: string
      type: object
      x-apiture-flattened: true
    createInvitation:
      x-apiture-version: 2.0.0
      title: Create Invitation
      description: Representation used to create a new Invitation.
      required:
        - sharedSecret
        - type
        - inviterFullName
        - emailAddress
      x-apiture-composition:
        - $ref: '#/components/schemas/invitationFields'
        - $ref: '#/components/schemas/abstractRequest'
      properties:
        firstName:
          x-apiture-deprecated: true
          description: 'The first name of the invitee. **Warning**: This property is deprecated and no longer used in invitation verification.'
          type: string
        lastName:
          x-apiture-deprecated: true
          description: 'The lastName name of the invitee. **Warning**: This property is deprecated and no longer used in invitation verification.'
          type: string
        identification:
          x-apiture-deprecated: true
          description: >-
            The last 4 digits of the government ID (SSN or other ID) of invitee. **Warning**: This property is deprecated and no longer used in
            invitation verification.
          type: string
        sharedSecret:
          description: A string shared by the inviter with the invitee to verify their identity.
          type: string
          minLength: 8
        emailAddress:
          description: The email address of the invitee.
          type: string
        type:
          description: The type of invitation.
          type: string
          enum:
            - joint
            - authorizedSigner
          x-apiture-enum: invitationType
        accountUri:
          description: 'If `type` is `joint`, this is the uri of the account the invitee is being invited to.'
          type: string
        organizationUri:
          description: 'If `type` is `authorizedSigner`, this is the uri of the organization the invitee is being invited to.'
          type: string
        role:
          description: 'If `type` is `authorizedSigner`, this is the role of the invitee at the organization is being invited to.'
          type: string
        inviterFullName:
          description: The full name of the user sending the invitation.
          type: string
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
          type: object
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
      type: object
      x-apiture-flattened: true
    invitation:
      title: Invitation
      description: Representation of invitation resources.
      x-apiture-composition:
        - $ref: '#/components/schemas/invitationFields'
        - $ref: '#/components/schemas/abstractResource'
        - properties:
            - _id
            - state
            - createdAt
            - updatedAt
            - expiresAt
            - customerId
            - customerGroup
            - verificationCount
            - createdBy
      properties:
        firstName:
          x-apiture-deprecated: true
          description: 'The first name of the invitee. **Warning**: This property is deprecated and no longer used in invitation verification.'
          type: string
        lastName:
          x-apiture-deprecated: true
          description: 'The lastName name of the invitee. **Warning**: This property is deprecated and no longer used in invitation verification.'
          type: string
        identification:
          x-apiture-deprecated: true
          description: >-
            The last 4 digits of the government ID (SSN or other ID) of invitee. **Warning**: This property is deprecated and no longer used in
            invitation verification.
          type: string
        sharedSecret:
          description: A string shared by the inviter with the invitee to verify their identity.
          type: string
          minLength: 8
        emailAddress:
          description: The email address of the invitee.
          type: string
        type:
          description: The type of invitation.
          type: string
          enum:
            - joint
            - authorizedSigner
          x-apiture-enum: invitationType
        accountUri:
          description: 'If `type` is `joint`, this is the uri of the account the invitee is being invited to.'
          type: string
        organizationUri:
          description: 'If `type` is `authorizedSigner`, this is the uri of the organization the invitee is being invited to.'
          type: string
        role:
          description: 'If `type` is `authorizedSigner`, this is the role of the invitee at the organization is being invited to.'
          type: string
        inviterFullName:
          description: The full name of the user sending the invitation.
          type: string
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
          type: object
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
        _error:
          description: An object which describes an error. This value is omitted if the operation succeeded without error.
          type: object
          allOf:
            - $ref: '#/components/schemas/error'
        _id:
          description: The unique identifier for this organization resource. This is an immutable opaque string.
          readOnly: true
          type: string
        state:
          description: The derived state of invitation.
          type: string
          enum:
            - sent
            - accepted
            - completed
            - revoked
            - expired
          x-apiture-enum: invitationState
          readOnly: true
        createdAt:
          description: >-
            The date-time when the invitation was created. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339)format, UTC. This is derived and
            immutable.
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          description: >-
            The date-time when the invitation was last updated. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339)format, UTC. This is derived
            and immutable.
          type: string
          format: date-time
          readOnly: true
        expiresAt:
          description: >-
            The date-time when the invitation will expire. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339)format, UTC. This is derived and
            immutable.
          type: string
          format: date-time
          readOnly: true
        customerId:
          description: The derived core Customer Id of the person who created the Invitation.
          type: string
          readOnly: true
        customerGroup:
          description: The derived core Customer group of the person who created the Invitation.
          type: string
          readOnly: true
        verificationCount:
          description: The derived count of attempted verifications of this invitation.
          type: integer
          readOnly: true
        createdBy:
          description: The unique User Id of the person who created the Invitation. This is derived and immutable.
          type: string
          readOnly: true
      type: object
      x-apiture-flattened: true
    invitationFields:
      title: Invitation Fields
      description: Representation of invitation resources.
      x-apiture-composition:
        - properties:
            - firstName
            - lastName
            - identification
            - sharedSecret
            - emailAddress
            - type
            - accountUri
            - organizationUri
            - role
            - inviterFullName
      properties:
        firstName:
          x-apiture-deprecated: true
          description: 'The first name of the invitee. **Warning**: This property is deprecated and no longer used in invitation verification.'
          type: string
        lastName:
          x-apiture-deprecated: true
          description: 'The lastName name of the invitee. **Warning**: This property is deprecated and no longer used in invitation verification.'
          type: string
        identification:
          x-apiture-deprecated: true
          description: >-
            The last 4 digits of the government ID (SSN or other ID) of invitee. **Warning**: This property is deprecated and no longer used in
            invitation verification.
          type: string
        sharedSecret:
          description: A string shared by the inviter with the invitee to verify their identity.
          type: string
          minLength: 8
        emailAddress:
          description: The email address of the invitee.
          type: string
        type:
          description: The type of invitation.
          type: string
          enum:
            - joint
            - authorizedSigner
          x-apiture-enum: invitationType
        accountUri:
          description: 'If `type` is `joint`, this is the uri of the account the invitee is being invited to.'
          type: string
        organizationUri:
          description: 'If `type` is `authorizedSigner`, this is the uri of the organization the invitee is being invited to.'
          type: string
        role:
          description: 'If `type` is `authorizedSigner`, this is the role of the invitee at the organization is being invited to.'
          type: string
        inviterFullName:
          description: The full name of the user sending the invitation.
          type: string
      type: object
      x-apiture-flattened: true
    invitations:
      title: Invitation Collection
      description: |-
        Collection of invitations. The items in the collection are ordered in the `_embedded.items` array; the `name` is `invitations`.
         The top-level `_links` object may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`.)
      example:
        _profile: 'https://api.apiture.com/schemas/invitations/invitations/v1.0.0/profile.json'
        start: 10
        limit: 10
        count: 67
        name: invitations
        _links:
          self:
            href: /invitations/invitations?start=10&limit=10
          first:
            href: /invitations/invitations?start=0&limit=10
          next:
            href: /invitations/invitations?start=20&limit=10
          collection:
            href: /invitations/invitations
        _embedded:
          items:
            anyOf:
              - _id: 0399abed-fd3d-4830-a88b-30f38b8a365c
                _profile: 'https://api.apiture.com/schemas/invitations/invitation/v1.0.0/profile.json'
                _links:
                  self:
                    href: /invitations/invitations/0399abed-fd3d-4830-a88b-30f38b8a365c
              - _id: d62c0701-0d74-4836-83f9-ebf3709442ea
                _profile: 'https://api.apiture.com/schemas/invitations/invitation/v1.0.0/profile.json'
                _links:
                  self:
                    href: /invitations/invitations/d62c0701-0d74-4836-83f9-ebf3709442ea
      x-apiture-composition:
        - $ref: '#/components/schemas/collection'
        - properties:
            - _embedded
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          type: object
          description: Embedded objects.
          properties:
            items:
              description: An array containing a page of invitation items.
              type: array
              items:
                $ref: '#/components/schemas/invitation'
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
        _error:
          description: An object which describes an error. This value is omitted if the operation succeeded without error.
          type: object
          allOf:
            - $ref: '#/components/schemas/error'
        count:
          description: >-
            The number of items in the collection. This value is _optional_ and may be omitted if the count is not computable efficiently. If a filter
            is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the
            filter.
          type: integer
        start:
          description: The start index of this page of items.
          type: integer
        limit:
          description: The maximum number of items per page.
          type: integer
        name:
          description: The name of the collection.
          type: string
      type: object
      x-apiture-flattened: true
    localizedLabel:
      title: Localized Label
      description: A localized label and optional description for localizable content defined in this API.
      type: object
      properties:
        label:
          type: string
          description: A localized label or title which may be used labels or other UI controls which present a value.
          example: Limited Liability Corporation
        description:
          type: string
          description: A more detailed localized description of a localizable label.
        language:
          type: string
          description: >-
            The actual natural language tag to which this localized label is associated, as per [RFC
            7231](https://tools.ietf.org/html/rfc7231#section-3.1.3.1)
          example: en-us
        code:
          type: string
          description: 'If the localized value is associated with an external standard, this is a lookup code or key or URI for that value.'
          example: '31'
      x-apiture-flattened: true
    root:
      x-apiture-version: 2.0.0
      title: API Root (v2.0.0)
      description: 'A HAL response, with hypermedia `_links` for the top-level resources and operations in API.'
      example:
        id: apiName
        name: API name
        apiVersion: 1.0.0
        _profile: 'https://production.api.apiture.com/schemas/common/root/v2.0.0/profile.json'
        _links: {}
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/root/v2.0.0/model.json'
      x-apiture-namespace: common
      x-apiture-composition:
        - $ref: '#/components/schemas/abstractResource'
        - properties:
            - _id
            - name
            - apiVersion
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
          type: object
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
        _error:
          description: An object which describes an error. This value is omitted if the operation succeeded without error.
          type: object
          allOf:
            - $ref: '#/components/schemas/error'
        _id:
          description: This API's unique ID.
          readOnly: true
          type: string
        name:
          type: string
          description: This API's name.
        apiVersion:
          type: string
          description: This API's version.
      type: object
      x-apiture-flattened: true
    errorResponse:
      x-apiture-version: 2.0.0
      title: Error Response (v2.0.0)
      description: 'Describes an error response, typically returned on 4xx or 5xx errors from API operations. The `_error` object contains the error details.'
      example:
        _profile: 'https://api.apiture.com/schemas/common/errorResponse/v2.0.0/profile.json'
        _error:
          _id: 2eae46e1-575c-4d69-8a8f-0a7b0115a4b3
          message: The value for deposit must be greater than 0.
          statusCode: 422
          type: positiveNumberRequired
          attributes:
            value: -125.5
          remediation: Provide a value which is greater than 0
          occurredAt: '2018-01-25T05:50:52.375Z'
          _links:
            describedby:
              href: 'https://api.apiture.com/errors/positiveNumberRequired'
          _embedded:
            errors: []
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/errorResponse/v2.0.0/model.json'
      x-apiture-namespace: common
      x-apiture-composition:
        - $ref: '#/components/schemas/abstractResource'
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
          type: object
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
        _error:
          description: An object which describes an error. This value is omitted if the operation succeeded without error.
          type: object
          allOf:
            - $ref: '#/components/schemas/error'
      type: object
      x-apiture-flattened: true
    abstractResource:
      x-apiture-version: 2.0.0
      title: Abstract Resource (v2.0.0)
      description: >-
        An abstract schema used to define other schemas for request and response bodies. This is a
        [HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource representation. This model contains hypermedia `_links`, and either
        optional domain object data with `_profile` and optional `_embedded` objects, or an `_error` object. In responses, if the operation was
        successful, this object will not include the `_error`, but if the operation was a 4xx or 5xx error, this object will not include `_embedded`
        or any data fields, only `_error` and optionally `_links`.
      example:
        _profile: '{uri of resource profile.json}'
        _links:
          self:
            href: '{uri of current resource}'
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/abstractResource/v2.0.0/model.json'
      x-apiture-namespace: common
      x-apiture-composition:
        - $ref: '#/components/schemas/abstractRequest'
        - properties:
            - _error
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
          type: object
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
        _error:
          description: An object which describes an error. This value is omitted if the operation succeeded without error.
          type: object
          allOf:
            - $ref: '#/components/schemas/error'
      type: object
      x-apiture-flattened: true
    abstractRequest:
      x-apiture-version: 2.0.0
      title: Abstract Request (v2.0.0)
      description: >-
        An abstract schema used to define other request-only schemas. This is a [HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource
        representation, minus the `_error` defined in `abstractResource`.
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
          type: object
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
      example:
        _profile: '{uri of resource profile.json}'
        _links:
          self:
            href: '{uri of current resource}'
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/model.json'
      x-apiture-namespace: common
      type: object
      x-apiture-flattened: true
    collection:
      x-apiture-version: 2.0.0
      title: Collection (v2.0.0)
      description: A collection of resources. This is an abstract model schema which is extended to define specific resource collections.
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/collection/v2.0.0/model.json'
      x-apiture-namespace: common
      x-apiture-composition:
        - $ref: '#/components/schemas/abstractResource'
        - properties:
            - count
            - start
            - limit
            - name
      properties:
        _links:
          description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
          allOf:
            - $ref: '#/components/schemas/links'
        _embedded:
          description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
          type: object
        _profile:
          description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
          type: string
          format: uri
        _error:
          description: An object which describes an error. This value is omitted if the operation succeeded without error.
          type: object
          allOf:
            - $ref: '#/components/schemas/error'
        count:
          description: >-
            The number of items in the collection. This value is _optional_ and may be omitted if the count is not computable efficiently. If a filter
            is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the
            filter.
          type: integer
        start:
          description: The start index of this page of items.
          type: integer
        limit:
          description: The maximum number of items per page.
          type: integer
        name:
          description: The name of the collection.
          type: string
      type: object
      x-apiture-flattened: true
    error:
      x-apiture-version: 2.0.0
      title: Error (v2.0.0)
      description: Describes an error in an API request or in a service called via the API.
      required:
        - message
      properties:
        message:
          type: string
          description: A localized message string describing the error condition.
        _id:
          description: >-
            A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at
            the source of the error). This is is an opaque string.
          readOnly: true
          type: string
        statusCode:
          description: The HTTP status code associate with this error.
          type: integer
          minimum: 100
          maximum: 599
          example: 422
        type:
          type: string
          description: >-
            An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to
            render an appropriate message or hint. This provides a finer level of granularity than the `statusCode`. For example, instead of just 400
            Bad Request, the `type` may be much more specific. such as `integerValueNotInAllowedRange` or `numericValueExceedsMaximum` or
            `stringValueNotInAllowedSet`.
        occurredAt:
          type: string
          format: date-time
          description: 'An [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC time stamp indicating when the error occurred.'
          example: '2018-02-02T03:37:15.375Z'
        attributes:
          description: >-
            Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the
            `minimum` and `maximum` values. This allows clients to present error messages as they see fit (the API does not assume the
            client/presentation tier). The set of attributes varies by error `type`.
          allOf:
            - $ref: '#/components/schemas/attributes'
        remediation:
          type: string
          description: An optional localized string which provides hints for how the user or client can resolve the error.
        errors:
          description: An optional array of nested error objects. This property is not always present.
          type: array
          items:
            $ref: '#/components/schemas/error'
        _links:
          $ref: '#/components/schemas/links'
      example:
        _id: 2eae46e1575c0a7b0115a4b3
        message: Descriptive error message...
        statusCode: 422
        type: errorType1
        remediation: Remediation string...
        occurredAt: '2018-01-25T05:50:52.375Z'
        errors:
          - _id: ccdbe2c5c938a230667b3827
            message: An optional embedded error
          - _id: dbe9088dcfe2460f229338a3
            message: Another optional embedded error
        _links:
          describedby:
            href: 'https://developer.apiture.com/errors/errorType1'
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/error/v2.0.0/model.json'
      x-apiture-namespace: common
      type: object
      x-apiture-flattened: true
    links:
      title: Links (v1.0.0)
      x-apiture-version: 1.0.0
      description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
      type: object
      x-apiture-key: linkRelationName
      additionalProperties:
        $ref: '#/components/schemas/link'
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/links/v1.0.0/model.json'
      x-apiture-namespace: common
      properties: {}
      x-apiture-flattened: true
    attributes:
      x-apiture-version: 2.0.0
      title: Attributes (v2.0.0)
      description: An optional map of name/value pairs which contains additional dynamic data about the resource.
      type: object
      x-apiture-key: attributeName
      additionalProperties:
        $ref: '#/components/schemas/attributeValue'
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/attributes/v2.0.0/model.json'
      x-apiture-namespace: common
      properties: {}
      x-apiture-flattened: true
    link:
      x-apiture-version: 1.0.0
      title: Link (v1.0.0)
      description: >-
        Describes a hypermedia link within a `_links` object in HAL representations. In Apiture APIs, links are [HAL
        links](https://developer.apiture.com/docs/concepts/links), but Apiture APIs do not use the `name` or `hreflang` properties of HAL. Apiture
        links _may_ include a `method` property.
      required:
        - href
      properties:
        href:
          type: string
          format: uri
          description: The URI or URI template for the resource/operation this link refers to.
        type:
          type: string
          description: The media type for the resource.
        templated:
          type: boolean
          description: 'If true, the link''s href is a [URI template](https://tools.ietf.org/html/rfc6570).'
        title:
          type: string
          description: An optional human-readable localized title for the link.
        deprecation:
          type: string
          format: uri
          description: 'If present, the containing link is deprecated and the value is a URI which provides human-readable text information about the deprecation.'
        profile:
          type: string
          format: uri
          description: 'The URI of a profile document, a JSON document which describes the target resource/operation.'
      example:
        href: /contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f
        title: Applicant
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/link/v1.0.0/model.json'
      x-apiture-namespace: common
      type: object
      x-apiture-flattened: true
    attributeValue:
      x-apiture-version: 2.0.0
      title: Attribute Value (v2.0.0)
      description: The data associated with this attribute.
      x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/attributeValue/v2.0.0/model.json'
      x-apiture-namespace: common
      type: object
      properties: {}
      x-apiture-flattened: true
  responses:
    '304':
      description: Not Modified. The resource has not been modified since it was last fetched.
    '400':
      description: >-
        Bad Request. The request body or one or more of the query parameters was not well formed.  The `_error` field in the response will contain
        details about the request error.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    '412':
      description: >-
        Precondition Failed. The supplied `if-Match` header value does not match the most recent `ETag` response header value. The resource has
        changed in the interim.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    '422':
      description: >-
        Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The `_error` field in the response will
        contain details about the request error.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    '429':
      description: >-
        Too Many Requests.  If the threshold for number of requests from an IP address is exceeded, the IP will be blocked from further requests until
        a period of time has passed.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    409CreateInvitation:
      description: >-
        Conflict. Cannot create an invitation, possibly because joint owners are disabled or the account does not allow additional owners. Consult the
        _error object in the response for details.
      x-apiture-errors:
        - jointOwnersDisabled
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    409VerifyInvitation:
      description: Conflict. Only an invitation with a state of `sent` can be verified. Consult the `_error` object in the response for details.
      x-apiture-errors:
        - jointOwnersDisabled
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    409InvitationStateChange:
      description: >-
        Conflict. The request to change the state of the invitation is not allowed. For example, one cannot change the state of a `completed`
        invitation, or change a non-`sent` invitation to `revoked`. The `_error` field in the response will contain details about the request error.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    404Invitation:
      description: >-
        Not Found. There is no such invitation resource at the specified `{invitationId}`. The `_error` field in the response will contain details
        about the request error.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/errorResponse'
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
    204Deleted:
      description: No Content. The resource was deleted successfully.
  parameters:
    invitationIdPathParam:
      name: invitationId
      description: The unique identifier of this invitation. This is an opaque string.
      in: path
      required: true
      schema:
        type: string
    invitationQueryParam:
      name: invitation
      description: A server-supplied value which identifies the invitation instance.
      in: query
      required: true
      schema:
        type: string
    pendingInvitationsParam:
      name: pendingInvitations
      in: query
      description: >-
        Subset the invitations collection to those pending invitations for the currently authenticated user.  These are invitations that have been
        verified by the authenticated user but still require some user action to complete the invitation process. This is combined with an implicit
        `and` with other filters if they are used. See [filtering](https://developer.apiture.com/docs/concepts/filtering).
      schema:
        type: boolean
    stateQueryParam:
      name: state
      in: query
      description: >-
        Subset the invitations collection to those whose `state` matches this value. Use `|` to separate multiple values. For example, `?state=sent`
        matches only items whose `state` is `sent`; `?state=sent|accepted` matches items whose `state` is `sent` or `accepted`. This is combined with
        an implicit `and` with other filters if they are used. See [filtering](https://developer.apiture.com/docs/concepts/filtering).
      schema:
        type: string
        enum:
          - sent
          - accepted
          - completed
          - revoked
          - expired
    typeQueryParam:
      name: type
      in: query
      description: >-
        Subset the invitations collection to those whose `type` matches this value. Use `|` to separate multiple values. For example, `?type=joint`
        matches only items whose `type` is `joint`; `?state=joint|authorizedSigner` matches items whose `type` is `joint` or `authorizedSigner`. This
        is combined with an implicit `and` with other filters if they are used. See
        [filtering](https://developer.apiture.com/docs/concepts/filtering).
      schema:
        type: string
        enum:
          - joint
          - authorizedSigner
    emailAddressQueryParam:
      name: emailAddress
      in: query
      description: >-
        Subset the invitations collection to those with this `emailAddress` value. Use `|` to separate multiple values. For example,
        `?emailAddress=johnsmith@email.com` matches only items whose `emailAddress` is `johnsmith@email.com`;
        `?emailAddress=johnsmith@email.com|tomjones@email.com` will match items whose `emailAddress` is `johnsmith@email.com` or `tomjones@email.com`.
        This is combined with an implicit `and` with other filters if they are used. See
        [filtering](https://developer.apiture.com/docs/concepts/filtering).
      schema:
        type: string
    accountUriQueryParam:
      name: accountUri
      in: query
      description: >-
        Subset the invitations collection to those with this `accountUri` value. Use `|` to separate multiple values. For example,
        `?accountUri=https://api.apiture.com/accounts/accounts/0399abed-fd3d-4830-a88b-30f38b8a365c` matches only items whose `accountUri` is
        `https://api.apiture.com/accounts/accounts/0399abed-fd3d-4830-a88b-30f38b8a365c`. This is combined with an implicit `and` with other filters
        if they are used. See [filtering](https://developer.apiture.com/docs/concepts/filtering).
      schema:
        type: string
    organizationUriQueryParam:
      name: organizationUri
      in: query
      description: >-
        Subset the invitations collection to those with this `organizationUri` value. Use `|` to separate multiple values. For example,`
        ?organizationUri=https://api.apiture.com/organizations/organizations/0399abed-fd3d-4830-a88b-30f38b8a365c` matches only items whose
        `organizationUri` is `https://api.apiture.com/organizations/organizations/0399abed-fd3d-4830-a88b-30f38b8a365c`. This is combined with an
        implicit `and` with other filters if they are used. See [filtering](https://developer.apiture.com/docs/concepts/filtering).
      schema:
        type: string
    filterQueryParam:
      name: filter
      in: query
      description: 'Optional filter criteria. See [filtering](http://developer.apiture.com/docs/concepts/filtering).'
      schema:
        type: string
    qQueryParam:
      name: q
      in: query
      description: 'Optional search string. See [searching](http://developer.apiture.com/docs/concepts/searching).'
      schema:
        type: string
    ifMatchHeaderParam:
      name: If-Match
      description: The entity tag that was returned in the `ETag` response. This must match the current entity tag of the resource.
      in: header
      schema:
        type: string
    ifNoneMatchHeaderParam:
      name: If-None-Match
      description: >-
        The entity tag that was returned in the `ETag` response. If the resource's current entity tag matches, the `GET` will return 304 (Not
        Modified) and no response body, else the resource representation will be returned.
      in: header
      schema:
        type: string
  securitySchemes:
    apiKey:
      type: apiKey
      name: API-Key
      in: header
      description: >-
        API Key based authentication. Each client application must pass its private, unique API key, allocated in the developer portal, via the
        `API-Key: {api-key}` request header.
    accessToken:
      type: oauth2
      description: >-
        OAuth2 client access token authentication. The client authenticates against the server at `authorizationUrl`, passing the client's private
        `clientId` (and optional `clientSecret`) as part of this flow. The client obtains an access token from the server at `tokenUrl`. It then
        passes the received access token via the `Authorization: Bearer {access-token}` header in subsequent API calls. The authorization process also
        returns a refresh token which the client should use to renew the access token before it expires.
      flows:
        authorizationCode:
          authorizationUrl: /auth/oauth2/authorize
          tokenUrl: /auth/oauth2/token
          scopes:
            banking/read: Read access to invitations
            banking/write: Write (update) access to invitations
            banking/delete: Delete access to invitations
            banking/full: Full access to invitations
