openapi: 3.0.0 servers: - url: 'https://api.devbank.apiture.com/notifications' 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-09-14T08:46:54-0400' info: title: Notifications description: |- The Notifications API supports in-app notifications for Apiture digital banking clients. Using this API, services can generate notifications and clients can pull notifications for different contexts, such as users or accounts or a global context. These notifications are not related to operating system or devices notifications. This API manages two types of resources: * Notification definitions * Notification instances (Unless explicitly stated, the term "notification" in this document refers to a _notification instance_. When discussing _notification definitions_, we use the term "notification definition" or "definition".) Services or administrative applications [create _notification definitions_](#op-createNotificationDefinition) which act as templates for individual _notification instances_. A definition defines the context name for the notifications, the notification type, its message text, etc. Definitions are not associated with specific users. After creating a definition, services call [`createNotifications`](#op-createNotifications) to create _instances_ from that definition. Instances contain contexts (usually the URI of a specific resource such as an account or transfer, etc), a user, and optional expiration timestamp. Instances also derive the notification message from their definition. The client applications [fetch _notification instances_](#op-getActiveNotifications) for an authenticated user in order to render an in-application message. Users may dismiss a notification and that is tracked with the notification instance (they are exclude on the next `getActiveNotifications` call). Users can only view their own notifications and notifications definitions. End users do not have access to create or mofify definitions, create notification instances, expire or delete definitions, or expire or delete notification instances. Those operations are reserved for administrators and services. version: 0.10.1 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: Notification Definitions description: Definitions of In-app Notifications - name: Notification Definition Actions description: Actions on Notification Definitions - name: Notifications description: In-app Notifications - name: Notifications Actions description: Actions on Notifications - name: API description: The Notifications API paths: /expiredDefinitions: post: operationId: expireDefinition security: - apiKey: [] accessToken: - admin/write summary: Expire a notification definition description: >- Expire a notification definition. This changes the `expired` property of the definition to `true`. This operation is available via the `apiture:expire` link on the definition resource, if the current time is past the definition's `expiresAt` date-time value. This operation may be invoked before the `expiresAt` time to expire it earlier. This operation also expires all `active` notification instances defined by this definition. This operation does nothing if the definition has already expired. this definition. The response is the updated representation of the definition. The `If-Match` request header value, if passed, must match the current entity tag value of the definition. tags: - Definition Actions parameters: - $ref: '#/components/parameters/definitionQueryParam' - $ref: '#/components/parameters/ifMatchHeaderParam' responses: '200': description: OK. The operation succeeded. headers: ETag: description: >- The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update the resource to perform conditional updates. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/notificationDefinition' application/json: schema: $ref: '#/components/schemas/notificationDefinition' '400': $ref: '#/components/responses/400ExpireNotificationDefinition' '412': $ref: '#/components/responses/412' /definitions: get: summary: Return a collection of notification definitions description: >- Return a [paginated](https://developer.apiture.com/docs/concepts/pagination) [sortable](https://developer.apiture.com/docs/concepts/sorting) [filterable](https://developer.apiture.com/docs/concepts/filtering) [searchable](https://developer.apiture.com/docs/concepts/searching) collection of notification definitions. The [links](https://developer.apiture.com/docs/concepts/links) in the response include pagination links. operationId: getDefinitions security: - apiKey: [] accessToken: - data/read tags: - Notification Definitions parameters: - name: start in: query description: The zero-based index of the first definition 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 definition 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](https://developer.apiture.com/docs/concepts/sorting), such as `?sortBy=field1,-field2`.' schema: type: string - name: expired in: query description: Filter definitions whose `expired` property matches the given value. schema: type: boolean - $ref: '#/components/parameters/definitionTypeQueryParam' - $ref: '#/components/parameters/definitionContextNameQueryParam' - $ref: '#/components/parameters/filterQueryParam' - $ref: '#/components/parameters/qQueryParam' responses: '200': description: OK content: application/hal+json: schema: $ref: '#/components/schemas/notificationDefinitions' application/json: schema: $ref: '#/components/schemas/notificationDefinitions' '400': $ref: '#/components/responses/400' '422': $ref: '#/components/responses/422' post: summary: Create a new notification definition description: >- Create a new notification definition that specifies the notification type and message. After creating a notification, [create notification instances](#op-createNotifications) for specific users and contexts. **Note**: To add a global notification, use [`createGlobalDefinition`](#op-createGlobalDefinition) instead. operationId: createDefinition security: - apiKey: [] accessToken: - admin/write tags: - Notification Definitions 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: An entity tag which may be passed in the `If-Match` request header for *`PUT`* or *`PATCH`* operations which update the resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/notificationDefinition' application/json: schema: $ref: '#/components/schemas/notificationDefinition' '400': $ref: '#/components/responses/400' '422': $ref: '#/components/responses/422NotificationDefinition' requestBody: content: application/hal+json: schema: $ref: '#/components/schemas/createNotificationDefinition' application/json: schema: $ref: '#/components/schemas/createNotificationDefinition' description: The data necessary to create a new notification definition. required: true /globalDefinitions: post: summary: Create a new global notification definition description: >- Create a new global notification definition with a message. A global notification definition is one whose `contextName` is `global`. This is used for announcements targeted to all financial institution customers. The new definition is available in the [`getDefinitions`](#op-getDefinitions) collection. Clients should request active global notifications for users via [`getActiveNotifications`](#op-getActiveNotifications) and `?context=global` (or `?context=global|user`). The services does not create Instances of a global notification for each user until a client requests them. To add a non-global notification, use [`createDefinition`](#op-createDefinition) instead. operationId: createGlobalDefinition security: - apiKey: [] accessToken: - admin/write tags: - Notification Definitions 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: An entity tag which may be passed in the `If-Match` request header for *`PUT`* or *`PATCH`* operations which update the resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/notificationDefinition' application/json: schema: $ref: '#/components/schemas/notificationDefinition' '400': $ref: '#/components/responses/400' '422': $ref: '#/components/responses/422CreateNotification' requestBody: content: application/hal+json: schema: $ref: '#/components/schemas/createGlobalNotificationDefinition' application/json: schema: $ref: '#/components/schemas/createGlobalNotificationDefinition' description: The data necessary to create a new global notification definition. required: true '/definitions/{definitionId}': get: summary: Fetch a representation of this notification definition description: 'Return a [HAL](https://developer.apiture.com/docs/concepts/hal) representation of this notification definition resource.' operationId: getDefinition security: - apiKey: [] accessToken: - data/read tags: - Notification Definitions parameters: - $ref: '#/components/parameters/definitionIdPathParam' - $ref: '#/components/parameters/ifNoneMatchHeaderParam' responses: '200': description: OK headers: ETag: description: >- The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this definition resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/notificationDefinition' application/json: schema: $ref: '#/components/schemas/notificationDefinition' '304': $ref: '#/components/responses/304' '404': $ref: '#/components/responses/404NotificationDefinition' put: summary: Update this definition description: Perform a complete replacement of this definition. operationId: updateDefinition security: - apiKey: [] accessToken: - admin/write tags: - Notification Definitions parameters: - $ref: '#/components/parameters/definitionIdPathParam' - $ref: '#/components/parameters/ifMatchHeaderParam' responses: '200': description: OK headers: ETag: description: >- The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this definition resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/notificationDefinition' application/json: schema: $ref: '#/components/schemas/notificationDefinition' '400': $ref: '#/components/responses/400' '404': $ref: '#/components/responses/404NotificationDefinition' '412': $ref: '#/components/responses/412' '422': $ref: '#/components/responses/422NotificationDefinition' requestBody: content: application/hal+json: schema: $ref: '#/components/schemas/notificationDefinition' application/json: schema: $ref: '#/components/schemas/notificationDefinition' required: true patch: summary: Update this definition description: >- Perform a partial update of this definition. Fields which are omitted are not updated. Nested `_embedded` and `_links` are ignored if included. operationId: patchDefinition security: - apiKey: [] accessToken: - admin/write tags: - Notification Definitions parameters: - $ref: '#/components/parameters/definitionIdPathParam' - $ref: '#/components/parameters/ifMatchHeaderParam' responses: '200': description: OK headers: ETag: description: >- The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this definition resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/notificationDefinition' application/json: schema: $ref: '#/components/schemas/notificationDefinition' '400': $ref: '#/components/responses/400' '404': $ref: '#/components/responses/404NotificationDefinition' '412': $ref: '#/components/responses/412' '422': $ref: '#/components/responses/422NotificationDefinition' requestBody: content: application/hal+json: schema: $ref: '#/components/schemas/notificationDefinition' application/json: schema: $ref: '#/components/schemas/notificationDefinition' required: true delete: summary: Delete this notification definition resource description: >- Delete this notification definition resource and any notification instances that are defined by it. Normally, the service deletes definitions some time after they have expired. operationId: deleteDefinition security: - apiKey: [] accessToken: - admin/delete tags: - Notification Definitions parameters: - $ref: '#/components/parameters/definitionIdPathParam' responses: '204': $ref: '#/components/responses/204Deleted' '/definitions/{definitionId}/notifications': parameters: - $ref: '#/components/parameters/definitionIdPathParam' post: summary: Create notifications from a notification definition. description: Create notification instances from a notification definition. operationId: createNotifications security: - apiKey: [] accessToken: - admin/write tags: - Notifications responses: '200': description: OK. The instances have been created for this notification definition. headers: ETag: description: An entity tag which may be passed in the `If-Match` request header for *`PUT`* or *`PATCH`* operations which update the resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/notificationDefinition' application/json: schema: $ref: '#/components/schemas/notificationDefinition' '400': $ref: '#/components/responses/400' '409': $ref: '#/components/responses/409InstancesConflict' requestBody: content: application/hal+json: schema: $ref: '#/components/schemas/instances' application/json: schema: $ref: '#/components/schemas/instances' description: The data necessary to create new notification instances from this definition. required: true /dismissedNotifications: post: operationId: dismissNotification security: - apiKey: [] accessToken: - data/write summary: Dismiss a notification description: >- Dismiss a notification. This changes the `dismissed` property of a notification to `true` and records the `dismissedAt` timestamp. This operation is available via the `apiture:dismiss` link on the notification resource if both `expired` and `dismissed` are `false`. Dismissing an expired notification is allowed. Dismissing a previously dismissed notification is allowed, but does not change the state of the instance. The response is the updated representation of the notification. The `If-Match` request header value, if passed, must match the current entity tag value of the notification. tags: - Notification Actions parameters: - $ref: '#/components/parameters/notificationQueryParam' - $ref: '#/components/parameters/ifMatchHeaderParam' responses: '200': description: OK. The operation succeeded. headers: ETag: description: >- The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update the resource to perform conditional updates. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/notification' application/json: schema: $ref: '#/components/schemas/notification' '400': $ref: '#/components/responses/400DismissNotification' '409': $ref: '#/components/responses/409DismissNotificationConflict' '412': $ref: '#/components/responses/412' /expiredNotifications: post: operationId: expireNotification security: - apiKey: [] accessToken: - admin/write summary: Expire a notification description: >- Expire a notification instance. This changes the `expired` property of the notification to `true`. This operation is available via the `apiture:expire` link on the notification resource if both `dismissed` and `expired` are false. Expiring a dismissed notification is allowed. Expiring a previously expired notification is allowed, but does not change the state of the instance. Expiring a definition invokes this operation on all instances derived from that definition. The response is the updated representation of the notification. The `If-Match` request header value, if passed, must match the current entity tag value of the notification. tags: - Notification Actions parameters: - $ref: '#/components/parameters/notificationQueryParam' - $ref: '#/components/parameters/ifMatchHeaderParam' responses: '200': description: OK. The operation succeeded. headers: ETag: description: >- The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update the resource to perform conditional updates. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/notification' application/json: schema: $ref: '#/components/schemas/notification' '400': $ref: '#/components/responses/400ExpireNotification' '409': $ref: '#/components/responses/409ExpireNotificationConflict' '412': $ref: '#/components/responses/412' /activeNotifications: get: summary: Return active notifications description: |- Return a list of active notifications for a user which match a context by name or URI. The response excludes dismissed or expired notifications. This is the primary operation clients used to fetch (a.k.a. _pull_) notifications for a user for a given context, client type (`web` or `mobile`), and user language preferences. Each active notification in the response `_embedded.items` contains the details of the notification in its `_embedded.definition` This operation returns the preferred text and image (based on the client type and languages) in each active notification's `message` property. The `message` in each instance in the response is the best match from the notification definition's `message`, `webMessage` and `mobileMessage`, as determined by the `?clientType=` and `?languages=` query parameters. The service also resolves any `{variableName}` variables in the message text with the `values` from the instance or definition. The client should display the notifications in the user interface. Notifications defined with `indicator: true` should be displayed with the `message.imageUri` icon, although the client may use the rendered `message.text` as a hover tip. This acts as a "badge". Clients should display other (non-indicator) notifications as text notifications, with optional icon, and with a **Dismiss** or **OK** or other control to dismiss the notification. The client should convert the [Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/) text to rich text before displaying it. When the user dismisses a notification, the client should `POST` to that notification's `apiture:dismiss` link so the service can exclude the notification from the response the next time the client calls this operation for this context. operationId: getActiveNotifications security: - apiKey: [] accessToken: - data/read tags: - Notifications parameters: - $ref: '#/components/parameters/contextQueryParam' - name: clientType in: query description: >- If `?clientType=web`, the notifications' `message` is derived from the `webMessage` in the corresponding notification definition, ignoring the the definition's `mobileMessage`. If no `webMessage` is defined for the requested 'languages', the notifications' `message` is derived from the definitions `message`. `?clientType=mobile` is handled analogously, using `mobileMessage`. The default uses the definition's `message` if it is defined, else `webMessage`. schema: type: string enum: - web - mobile - name: languages description: >- Return message variants that match the user's language preference. The array is ordered by highest to lowest preference language tag(s). For example, for `?languages=es,en`, the response will include message variants based on the following search priority: `es` ⇒ `en` ⇒ ⇒ (_default_)
Items are [RFC 3066](https://tools.ietf.org/html/rfc3066) language identifiers. If used, `Accept-Language` header is ignored. Language codes are case insensitive. in: query style: form schema: type: array items: type: string minLength: 2 maxLength: 8 format: language pattern: '^[a-z]{2,3}(-[a-zA-Z0-9]{2,4})?$' minItems: 1 maxItems: 6 - name: replace in: query description: >- If `false`, the operation does not replace the variable references in the `message.text` of each [active notification](#schema-activeNotification) with the corresponding value from the notification's `values`. The client should perform the replacement before displaying the message. schema: type: boolean default: true - name: Accept-Language in: header description: >- An [HTTP `Accept-Language`](https://tools.ietf.org/html/rfc7231#section-5.3.5) request header which specifies one or more languages with weights. The response will include one string for each combination of group name and string name. This is ignored if `?languages=` query parameter is used. `Accept-Language` is processed in a similar way as the `language` query parameter. schema: type: string responses: '200': description: OK. content: application/hal+json: schema: $ref: '#/components/schemas/activeNotifications' application/json: schema: $ref: '#/components/schemas/activeNotifications' '400': $ref: '#/components/responses/400' '422': $ref: '#/components/responses/422' /notifications: get: summary: Return a collection of notifications description: >- Return a [paginated](https://developer.apiture.com/docs/concepts/pagination) [sortable](https://developer.apiture.com/docs/concepts/sorting) [filterable](https://developer.apiture.com/docs/concepts/filtering) [searchable](https://developer.apiture.com/docs/concepts/searching) collection of notifications. The [links](https://developer.apiture.com/docs/concepts/links) in the response include pagination links. operationId: getNotifications security: - apiKey: [] accessToken: - data/read tags: - Notifications parameters: - name: start in: query description: The zero-based index of the first notification 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 notification 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](https://developer.apiture.com/docs/concepts/sorting), such as `?sortBy=field1,-field2`.' schema: type: string - name: expired in: query description: Filter definitions whose `expired` property matches the given value. schema: type: boolean - name: dismissed in: query description: Filter definitions whose `dismissed` property matches the given value. schema: type: boolean - $ref: '#/components/parameters/typeQueryParam' - $ref: '#/components/parameters/contextNameQueryParam' - $ref: '#/components/parameters/contextUriQueryParam' - $ref: '#/components/parameters/filterQueryParam' - $ref: '#/components/parameters/qQueryParam' x-apiture-traits: sortBy: - type - contextName - expiredAt - dismissedAt filter: dismissed: filter: - eq - ne expired: filter: - eq - ne type: filter: - eq - ne - in - startsWith - endsWith - contains - search name: filter: - eq - ne - in - startsWith - endsWith - contains - search expiredAt: filter: - lt - le - gt - ge dismissedAt: filter: - lt - le - gt - ge responses: '200': description: OK content: application/hal+json: schema: $ref: '#/components/schemas/notifications' application/json: schema: $ref: '#/components/schemas/notifications' '400': $ref: '#/components/responses/400' '422': $ref: '#/components/responses/422' post: summary: Create a new notification description: Create a new notification in the notifications collection. operationId: createNotification security: - apiKey: [] accessToken: - admin/write tags: - Notifications 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: An entity tag which may be passed in the `If-Match` request header for *`PUT`* or *`PATCH`* operations which update the resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/notification' application/json: schema: $ref: '#/components/schemas/notification' '400': $ref: '#/components/responses/400' requestBody: content: application/hal+json: schema: $ref: '#/components/schemas/createNotification' application/json: schema: $ref: '#/components/schemas/createNotification' description: The data necessary to create a new notification. required: true '/notifications/{notificationId}': get: summary: Fetch a representation of this notification description: 'Return a [HAL](https://developer.apiture.com/docs/concepts/hal) representation of this notification resource.' operationId: getNotification security: - apiKey: [] accessToken: - data/read tags: - Notifications parameters: - $ref: '#/components/parameters/notificationIdPathParam' - $ref: '#/components/parameters/ifNoneMatchHeaderParam' responses: '200': description: OK headers: ETag: description: >- The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this notification resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/notification' application/json: schema: $ref: '#/components/schemas/notification' '304': $ref: '#/components/responses/304' '404': $ref: '#/components/responses/404Notification' delete: summary: Delete this notification resource description: Delete this notification resource and any resources that are owned by it. operationId: deleteNotification security: - apiKey: [] accessToken: - admin/delete tags: - Notifications parameters: - $ref: '#/components/parameters/notificationIdPathParam' responses: '204': $ref: '#/components/responses/204Deleted' /: 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 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 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: definitionRefNotFound: description: The referenced notification definition is not found remediation: Pass a reference to an existing notification definition notificationRefNotFound: description: The referenced notification instance is not found remediation: Pass a reference to an existing notification instance indicatorAndNotDismissibleMutuallyExclusive: description: The `indicator` and `notDismissible` properties may not be both true remediation: 'Choose either indicator or notDismissible, not both' dismissNotAllowed: description: Cannot dismiss a notification when the definition is an indicator or is not dismissible remediation: Do not invoke dismissNotification if the definition is an indicator or not dismissible idNotMatchPath: description: 'The `_id` in the request body does not match the {definitionId} path parameter' remediation: Use the representation from the correct notification definition definitionExpired: description: Cannot create new notification instances from an expired notification definition remediation: Use an unexpired notification definition mismatchedContextUriTemplate: description: The request includes a contextUriTemplate that does not match the notification definition remediation: Create a different notification definition if you need a different contextUriTemplate definitionMissingContextUriTemplate: description: The instances contain only context IDs but the definition has no contextUriTemplate remediation: 'Either define a contextUriTemplate in the notification definition, or include full context URIs in the instances' cannotCreateInstancesFromGlobalDefinition: description: Cannot create notification instances for a `global` notification definition remediation: Use a non-global notification definition to create user-specific notification instances x-apiture-traits: - api: title: Notifications basePath: notifications applied: true links: - getApi - getApiDoc - getDefinitions - createDefinition - createGlobalDefinition - getNotifications - getActiveNotifications - security: baseScope: data applied: true - resource: name: notification applied: true excludeMethods: - put - post - patch - resource: name: definition applied: true components: schemas: notificationDefinition: title: Notification Definition description: Representation of a notification definition resource. x-apiture-links: - rel: 'apiture:expire' operationId: expireDefinition - rel: 'apiture:createNotifications' operationId: createNotifications example: _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'https://api.apiture.com/schemas/notifications/notificationDefinition/v1.0.0/profile.json' type: cdMaturingSoon contextName: account indicator: true notDismissible: false priority: medium expired: false expiresAt: '2020-04-18T12:26:36.375Z' updatedAt: '2020-04-16T12:00:22.100Z' message: text: 'This CD account is maturing on {maturityDate}. Now is a good time to review your account maturity settings.' imageUri: 'https://cdn.assets.3rdpartybank.com/icons/en/notifications/cdMaturingSoon.png' values: maturityDate: '2020-04-09' _links: self: href: /notifications/definitions/0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:expire': href: /expiredDefinitions?definition=0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:createNotifications': href: /notifications/definitions/0399abed-fd3d-4830-a88b-30f38b8a365c/notifications x-apiture-composition: - $ref: '#/components/schemas/summaryNotificationDefinition' - properties: - createdAt - updatedAt - expired 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: description: >- A programmatic name for the kind of notification this defines, such as `cdMaturingSoon` or `cdInGracePeriod`. Clients may elect to respond differently or specially to different well-known notification types. type: string pattern: '^[a-z][a-zA-Z0-9_$]{1,31}$' example: announcement default: announcement maxLength: 32 message: description: >- The default message text template for notification instances. This may be overridden for web or mobile client types with the `webMessage` or `mobileMessage` properties. A definition must defined either the `message` property or both `webMessage` or `mobileMessage` properties. allOf: - $ref: '#/components/schemas/notificationMessage' webMessage: description: >- The message text template for this notification for web application clients, when using [`GET /activeNotifications?clientType=web`](#op-activeNotifications. If this is not defined, notifications use `message`. allOf: - $ref: '#/components/schemas/notificationMessage' mobileMessage: description: >- The message text template for this notification for mobile application clients, when using [`GET /activeNotifications?clientType=mobile`](#op-activeNotifications. If this is not defined, notifications use `message`. allOf: - $ref: '#/components/schemas/notificationMessage' values: description: >- An optional map of name/value variables to insert into the formatted message. For example, the for message text `We have increased the rate of your CD from {oldApy}% to {newApy}%.`, the `values` should define `oldApy` and `newApy`:
`{ "oldApy": "1.750", "newApy": "1.800"}`. These `values` are defaults for instances which do not override `values`. x-apiture-key: variableName additionalProperties: $ref: '#/components/schemas/attributeValue' priority: description: The priority of this notification. allOf: - $ref: '#/components/schemas/notificationPriority' default: medium indicator: description: >- If `true`, each notification instantiated from this definition is a visual indicator (a.k.a. badge) rather than a dismissible visual message, and the [`dismissNotification`](#op-dismissNotification) operation is not allowed. This may not be `true` if `notDismissible` is true. type: boolean default: false notDismissible: description: >- If `true`, each notification instantiated from this definition does not have a UI control to dismiss it, and the [`dismissNotification`](#op-dismissNotification) operation is not allowed. This may not be `true` if `indicator` is true. type: boolean expiresAt: description: >- The notification definition's expiration timestamp in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTF format: `YYYY-MM-DDThh:mm:ss.sssZ`. When the definition expires, all active notifications also expire. type: string format: date-time contextName: description: >- A programmatic name of the context for this notification. This could be `global` for a global notification directed at all users, or an `account` if the notification applies to a banking account, or `user` if the notification applies to a user. type: string pattern: '^[a-z][a-zA-Z0-9_$]{1,31}$' maxLength: 32 contextUriTemplate: description: >- An optional URI template for expanding simple identifiers in contexts to full URIs. For example, the value `/accounts/accounts/{id}` will convert the simple id value `30f38b8a365c` to the URI `/accounts/accounts/30f38b8a365c`. This string must have the substring `{id}` in it. type: string maxLength: 2048 contextUri: description: >- The URI of a resource that defines the content of this notification, such as the global resource URI, `https://api.apiture.com/domains/notifications/global`. For non-global notifications, instances supply their own `contextUri` explicitly or by injecting a `contextId` into the definition's `contextUriTemplate`. type: string format: uri maxLength: 2048 _id: description: The unique identifier for this notification definition resource. This is an immutable opaque string. type: string readOnly: true maxLength: 128 expired: description: '`true` if this notification definition''s expiration date-time has passed.' type: boolean readOnly: true createdAt: description: >- The the notification definition's creation date-time. This is an [RFC 3369](https://tools.ietf.org/html/rfc3339) formatted date-time string, `YYYY-MM-DDThh:mm:ss.sssZ`. This is a derived field and is immutable. type: string format: date-time readOnly: true updatedAt: description: >- The notification definition's last update date-time. This is an [RFC 3369](https://tools.ietf.org/html/rfc3339) formatted date-time string, `YYYY-MM-DDThh:mm:ss.sssZ`. This is a derived field and is immutable. type: string format: date-time readOnly: true type: object x-apiture-flattened: true createNotificationDefinition: title: Create Notification Definition description: >- Representation used to create a new notification definition. The `message` property must be defined or both `webMessage` or `mobileMessage` properties must be defined. required: - contextName example: _profile: 'https://api.apiture.com/schemas/notifications/createNotificationDefinition/v1.0.0/profile.json' type: cdMaturingSoon contextName: account indicator: true priority: medium message: text: 'We have increased the rate of your CD from {oldApy}% to {newApy}%.' imageUri: 'https://cdn.assets.3rdpartybank.com/icons/es/notifications/cdRateIncreased.png' variants: es: text: 'Hemos aumentado la velocidad de su CD de {oldApy}% a {newApy}%.' imageUri: 'https://cdn.assets.3rdpartybank.com/icons/es/notifications/cdRateIncreased.png' fr: text: 'Nous avons augment\u00e9 le taux de votre CD de {oldApy}% \00e0 {newApy}%.' imageUri: 'https://cdn.assets.3rdpartybank.com/icons/fr/notifications/cdRateIncreased.png' values: oldApy: '1.750' newApy: 1.8.0 x-apiture-composition: - $ref: '#/components/schemas/abstractRequest' - $ref: '#/components/schemas/notificationDefinitionFields' 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 type: description: >- A programmatic name for the kind of notification this defines, such as `cdMaturingSoon` or `cdInGracePeriod`. Clients may elect to respond differently or specially to different well-known notification types. type: string pattern: '^[a-z][a-zA-Z0-9_$]{1,31}$' example: announcement default: announcement maxLength: 32 message: description: >- The default message text template for notification instances. This may be overridden for web or mobile client types with the `webMessage` or `mobileMessage` properties. A definition must defined either the `message` property or both `webMessage` or `mobileMessage` properties. allOf: - $ref: '#/components/schemas/notificationMessage' webMessage: description: >- The message text template for this notification for web application clients, when using [`GET /activeNotifications?clientType=web`](#op-activeNotifications. If this is not defined, notifications use `message`. allOf: - $ref: '#/components/schemas/notificationMessage' mobileMessage: description: >- The message text template for this notification for mobile application clients, when using [`GET /activeNotifications?clientType=mobile`](#op-activeNotifications. If this is not defined, notifications use `message`. allOf: - $ref: '#/components/schemas/notificationMessage' values: description: >- An optional map of name/value variables to insert into the formatted message. For example, the for message text `We have increased the rate of your CD from {oldApy}% to {newApy}%.`, the `values` should define `oldApy` and `newApy`:
`{ "oldApy": "1.750", "newApy": "1.800"}`. These `values` are defaults for instances which do not override `values`. x-apiture-key: variableName additionalProperties: $ref: '#/components/schemas/attributeValue' priority: description: The priority of this notification. allOf: - $ref: '#/components/schemas/notificationPriority' default: medium indicator: description: >- If `true`, each notification instantiated from this definition is a visual indicator (a.k.a. badge) rather than a dismissible visual message, and the [`dismissNotification`](#op-dismissNotification) operation is not allowed. This may not be `true` if `notDismissible` is true. type: boolean default: false notDismissible: description: >- If `true`, each notification instantiated from this definition does not have a UI control to dismiss it, and the [`dismissNotification`](#op-dismissNotification) operation is not allowed. This may not be `true` if `indicator` is true. type: boolean expiresAt: description: >- The notification definition's expiration timestamp in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTF format: `YYYY-MM-DDThh:mm:ss.sssZ`. When the definition expires, all active notifications also expire. type: string format: date-time contextName: description: >- A programmatic name of the context for this notification. This could be `global` for a global notification directed at all users, or an `account` if the notification applies to a banking account, or `user` if the notification applies to a user. type: string pattern: '^[a-z][a-zA-Z0-9_$]{1,31}$' maxLength: 32 contextUriTemplate: description: >- An optional URI template for expanding simple identifiers in contexts to full URIs. For example, the value `/accounts/accounts/{id}` will convert the simple id value `30f38b8a365c` to the URI `/accounts/accounts/30f38b8a365c`. This string must have the substring `{id}` in it. type: string maxLength: 2048 contextUri: description: >- The URI of a resource that defines the content of this notification, such as the global resource URI, `https://api.apiture.com/domains/notifications/global`. For non-global notifications, instances supply their own `contextUri` explicitly or by injecting a `contextId` into the definition's `contextUriTemplate`. type: string format: uri maxLength: 2048 type: object x-apiture-flattened: true createGlobalNotificationDefinition: title: Create Global Notification Definition description: >- Representation used to create a new global notification definition. The `message` property must be defined or both `webMessage` or `mobileMessage` properties must be defined. example: _profile: 'https://api.apiture.com/schemas/notifications/createGlobalNotificationDefinition/v1.0.0/profile.json' priority: high message: text: >- The bank branch at {address} will be closed until September 17 due to Hurricane Heathcliff. See [our announcement](http://www.3rdpartybank.com/announcements/heathcliff) for more information. imageUri: 'https://cdn.assets.3rdpartybank.com/icons/en/hurricane-flag.png' variants: es: text: >- La sucursal bancaria en {address} estar\u00e1 cerrada hasta el 17 de septiembre debido al hurac\u00e1n Heathcliff. Consulte [nuestro anuncio](http://www.3rdpartybank.com/announcements/heathcliff) para obtener m\u00e1s informaci\u00f3n. imageUri: 'https://cdn.assets.3rdpartybank.com/icons/es/hurricane-flag.png' values: address: 123 N. Main St. Wilmington x-apiture-composition: - $ref: '#/components/schemas/abstractRequest' - $ref: '#/components/schemas/sharedNotificationDefinitionFields' 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 type: description: >- A programmatic name for the kind of notification this defines, such as `cdMaturingSoon` or `cdInGracePeriod`. Clients may elect to respond differently or specially to different well-known notification types. type: string pattern: '^[a-z][a-zA-Z0-9_$]{1,31}$' example: announcement default: announcement maxLength: 32 message: description: >- The default message text template for notification instances. This may be overridden for web or mobile client types with the `webMessage` or `mobileMessage` properties. A definition must defined either the `message` property or both `webMessage` or `mobileMessage` properties. allOf: - $ref: '#/components/schemas/notificationMessage' webMessage: description: >- The message text template for this notification for web application clients, when using [`GET /activeNotifications?clientType=web`](#op-activeNotifications. If this is not defined, notifications use `message`. allOf: - $ref: '#/components/schemas/notificationMessage' mobileMessage: description: >- The message text template for this notification for mobile application clients, when using [`GET /activeNotifications?clientType=mobile`](#op-activeNotifications. If this is not defined, notifications use `message`. allOf: - $ref: '#/components/schemas/notificationMessage' values: description: >- An optional map of name/value variables to insert into the formatted message. For example, the for message text `We have increased the rate of your CD from {oldApy}% to {newApy}%.`, the `values` should define `oldApy` and `newApy`:
`{ "oldApy": "1.750", "newApy": "1.800"}`. These `values` are defaults for instances which do not override `values`. x-apiture-key: variableName additionalProperties: $ref: '#/components/schemas/attributeValue' priority: description: The priority of this notification. allOf: - $ref: '#/components/schemas/notificationPriority' default: medium indicator: description: >- If `true`, each notification instantiated from this definition is a visual indicator (a.k.a. badge) rather than a dismissible visual message, and the [`dismissNotification`](#op-dismissNotification) operation is not allowed. This may not be `true` if `notDismissible` is true. type: boolean default: false notDismissible: description: >- If `true`, each notification instantiated from this definition does not have a UI control to dismiss it, and the [`dismissNotification`](#op-dismissNotification) operation is not allowed. This may not be `true` if `indicator` is true. type: boolean expiresAt: description: >- The notification definition's expiration timestamp in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTF format: `YYYY-MM-DDThh:mm:ss.sssZ`. When the definition expires, all active notifications also expire. type: string format: date-time type: object x-apiture-flattened: true sharedNotificationDefinitionFields: title: Notification Definition Fields x-apiture-fragment: true description: Common fields used to build notification definition schemas. properties: type: description: >- A programmatic name for the kind of notification this defines, such as `cdMaturingSoon` or `cdInGracePeriod`. Clients may elect to respond differently or specially to different well-known notification types. type: string pattern: '^[a-z][a-zA-Z0-9_$]{1,31}$' example: announcement default: announcement maxLength: 32 message: description: >- The default message text template for notification instances. This may be overridden for web or mobile client types with the `webMessage` or `mobileMessage` properties. A definition must defined either the `message` property or both `webMessage` or `mobileMessage` properties. allOf: - $ref: '#/components/schemas/notificationMessage' webMessage: description: >- The message text template for this notification for web application clients, when using [`GET /activeNotifications?clientType=web`](#op-activeNotifications. If this is not defined, notifications use `message`. allOf: - $ref: '#/components/schemas/notificationMessage' mobileMessage: description: >- The message text template for this notification for mobile application clients, when using [`GET /activeNotifications?clientType=mobile`](#op-activeNotifications. If this is not defined, notifications use `message`. allOf: - $ref: '#/components/schemas/notificationMessage' values: description: >- An optional map of name/value variables to insert into the formatted message. For example, the for message text `We have increased the rate of your CD from {oldApy}% to {newApy}%.`, the `values` should define `oldApy` and `newApy`:
`{ "oldApy": "1.750", "newApy": "1.800"}`. These `values` are defaults for instances which do not override `values`. x-apiture-key: variableName additionalProperties: $ref: '#/components/schemas/attributeValue' priority: description: The priority of this notification. allOf: - $ref: '#/components/schemas/notificationPriority' default: medium indicator: description: >- If `true`, each notification instantiated from this definition is a visual indicator (a.k.a. badge) rather than a dismissible visual message, and the [`dismissNotification`](#op-dismissNotification) operation is not allowed. This may not be `true` if `notDismissible` is true. type: boolean default: false notDismissible: description: >- If `true`, each notification instantiated from this definition does not have a UI control to dismiss it, and the [`dismissNotification`](#op-dismissNotification) operation is not allowed. This may not be `true` if `indicator` is true. type: boolean expiresAt: description: >- The notification definition's expiration timestamp in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTF format: `YYYY-MM-DDThh:mm:ss.sssZ`. When the definition expires, all active notifications also expire. type: string format: date-time type: object x-apiture-flattened: true summaryNotificationDefinition: title: Notification Definition Summary description: >- Summary representation of a definition resource in notification definitions collections. This representation normally does not contain any `_embedded` objects. If needed, call the `GET` operation on the item's `self` link to get `_embedded` objects. example: _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'https://api.apiture.com/schemas/notifications/summaryNotificationDefinition/v1.0.0/profile.json' type: cdMaturingSoon contextName: account indicator: true notDismissible: false expired: false expiresAt: '2020-04-18T12:15:21.375Z' message: text: 'This CD account is maturing on {maturityDate}. Now is a good time to review your account maturity settings.' imageUri: 'https://cdn.assets.3rdpartybank.com/icons/en/notifications/cdMaturingSoon.png' values: maturityDate: '2020-04-09' _links: self: href: /notifications/definitions/0399abed-fd3d-4830-a88b-30f38b8a365c x-apiture-composition: - $ref: '#/components/schemas/abstractResource' - $ref: '#/components/schemas/notificationDefinitionFields' - properties: - _id - expired 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: description: >- A programmatic name for the kind of notification this defines, such as `cdMaturingSoon` or `cdInGracePeriod`. Clients may elect to respond differently or specially to different well-known notification types. type: string pattern: '^[a-z][a-zA-Z0-9_$]{1,31}$' example: announcement default: announcement maxLength: 32 message: description: >- The default message text template for notification instances. This may be overridden for web or mobile client types with the `webMessage` or `mobileMessage` properties. A definition must defined either the `message` property or both `webMessage` or `mobileMessage` properties. allOf: - $ref: '#/components/schemas/notificationMessage' webMessage: description: >- The message text template for this notification for web application clients, when using [`GET /activeNotifications?clientType=web`](#op-activeNotifications. If this is not defined, notifications use `message`. allOf: - $ref: '#/components/schemas/notificationMessage' mobileMessage: description: >- The message text template for this notification for mobile application clients, when using [`GET /activeNotifications?clientType=mobile`](#op-activeNotifications. If this is not defined, notifications use `message`. allOf: - $ref: '#/components/schemas/notificationMessage' values: description: >- An optional map of name/value variables to insert into the formatted message. For example, the for message text `We have increased the rate of your CD from {oldApy}% to {newApy}%.`, the `values` should define `oldApy` and `newApy`:
`{ "oldApy": "1.750", "newApy": "1.800"}`. These `values` are defaults for instances which do not override `values`. x-apiture-key: variableName additionalProperties: $ref: '#/components/schemas/attributeValue' priority: description: The priority of this notification. allOf: - $ref: '#/components/schemas/notificationPriority' default: medium indicator: description: >- If `true`, each notification instantiated from this definition is a visual indicator (a.k.a. badge) rather than a dismissible visual message, and the [`dismissNotification`](#op-dismissNotification) operation is not allowed. This may not be `true` if `notDismissible` is true. type: boolean default: false notDismissible: description: >- If `true`, each notification instantiated from this definition does not have a UI control to dismiss it, and the [`dismissNotification`](#op-dismissNotification) operation is not allowed. This may not be `true` if `indicator` is true. type: boolean expiresAt: description: >- The notification definition's expiration timestamp in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTF format: `YYYY-MM-DDThh:mm:ss.sssZ`. When the definition expires, all active notifications also expire. type: string format: date-time contextName: description: >- A programmatic name of the context for this notification. This could be `global` for a global notification directed at all users, or an `account` if the notification applies to a banking account, or `user` if the notification applies to a user. type: string pattern: '^[a-z][a-zA-Z0-9_$]{1,31}$' maxLength: 32 contextUriTemplate: description: >- An optional URI template for expanding simple identifiers in contexts to full URIs. For example, the value `/accounts/accounts/{id}` will convert the simple id value `30f38b8a365c` to the URI `/accounts/accounts/30f38b8a365c`. This string must have the substring `{id}` in it. type: string maxLength: 2048 contextUri: description: >- The URI of a resource that defines the content of this notification, such as the global resource URI, `https://api.apiture.com/domains/notifications/global`. For non-global notifications, instances supply their own `contextUri` explicitly or by injecting a `contextId` into the definition's `contextUriTemplate`. type: string format: uri maxLength: 2048 _id: description: The unique identifier for this notification definition resource. This is an immutable opaque string. type: string readOnly: true maxLength: 128 expired: description: '`true` if this notification definition''s expiration date-time has passed.' type: boolean readOnly: true type: object x-apiture-flattened: true notificationDefinitions: title: Notification Definition Collection description: >- Collection of notification definitions. The items in the collection are ordered in the `_embedded.items` array; the `name` is `definitions`. The top-level `_links` object may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`). x-apiture-links: - rel: 'apiture:expireDefinition' operationId: expireDefinition example: _profile: 'https://api.apiture.com/schemas/notifications/notificationDefinitions/v1.0.0/profile.json' name: definitions start: 10 limit: 10 count: 67 _links: self: href: /notifications/definitions?start=10&limit=10 first: href: /notifications/definitions?start=0&limit=10 next: href: /notifications/definitions?start=20&limit=10 collection: href: /notifications/definitions _embedded: items: _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'https://api.apiture.com/schemas/notifications/summaryNotificationDefinition/v1.0.0/profile.json' type: cdMaturingSoon contextName: account indicator: true notDismissible: false priority: medium message: text: 'This CD account is maturing on {maturityDate}. Now is a good time to review your account maturity settings.' imageUri: 'https://cdn.assets.3rdpartybank.com/icons/en/notifications/cdMaturingSoon.png' values: maturityDate: '2020-04-09' _links: self: href: /notifications/definitions/0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:expire': href: /expiredDefinitions?definition=0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:createNotifications': href: /notifications/definitions/0399abed-fd3d-4830-a88b-30f38b8a365c/notifications 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 definition items. type: array items: $ref: '#/components/schemas/summaryNotificationDefinition' _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 instances: title: Notification Instances description: |- Collection of instances to create and add to a notification definition. Each instance contains properties to create an notification instance from this definition, each with their own context, user, and optional expiration date-time and optional values to inject into the message The request also contains a `contextUriTemplate` to map a context ID to a URI, so that thousands of contexts can be expressed in a more concise notation, consisting of just the IDs instead of thousands of URIs. Thus, the caller does not have to build full URIs. Message bodies are limited to 20,000 instances per call. If a caller need to create more notifications, it should send multiple requests. example: _profile: 'https://api.apiture.com/schemas/notifications/instances/v1.0.0/profile.json' contextUriTemplate: '/accounts/accounts/{id}' instances: - contextId: 0399abed-fd3d-4830-a88b-30f38b8a365c userIds: - 82535922-335f-4c95-8000-c663a50aec9c - 7131b08f-2c47-4c23-a4ad-fb31d895acb3 - 9cdbae90-a120-4a71-8314-d0f6051c86fa expiresAt: '2020-05-08T14:00:00.00Z' - contextId: 4c1e7436-14cb-4434-a46e-9d7b4e3f02ea userIds: - 1cbdd896-0730-4a7d-af68-1834de0cfe84 - c433df56-b9ef-44ed-bcb8-52bbfb4df5f8 expiresAt: '2020-05-10T14:00:00.00Z' values: oldApy: '1.750' newApy: 1.8.0 x-apiture-composition: - $ref: '#/components/schemas/abstractRequest' - properties: - contextUriTemplate - instances 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 contextUriTemplate: description: >- An optional URI template for expanding simple `contextId` in each of the `instances` items to URIs. If used, this string must have the substring `{id}` in it, It can be just a partial URI path or a compete URI. For example, for the template `https://api.3rdparty.bank/accounts/accounts/{id}` the 'contextId' value `30f38b8a365c` maps to the URI `https://api.3rdparty.bank/accounts/accounts/30f38b8a365c`. type: string example: '/accounts/accounts/{id}' pattern: '.*{id}.*' maxLength: 2048 instances: description: >- An array containing a page of notification instance items. Due to request body size limits, call this multiple times to create more than 20,000 notification instances. type: array maxItems: 20000 items: $ref: '#/components/schemas/instance' type: object x-apiture-flattened: true instance: title: Notification Instance description: >- Values for creating notification instances for a definition. Each instance must contain either a `contextId` or a `contextUri`. Using `userIds`, one `instance` item create multiple notification instances. required: - userIds properties: contextId: description: 'The `_id` of a resource, such as the ID of an account. The containing `instances` resource must define the `contextUriTemplate`.' type: string example: d545e39f-c64f-49c1-9777-2ee1ff75e61f maxLength: 48 contextUri: description: The URI of a resource. This may be a partial URI or a full URI. type: string format: uri example: /accounts/accounts/d545e39f-c64f-49c1-9777-2ee1ff75e61f maxLength: 2048 userIds: description: A notification is created for each user identified by these `userIds`. Each unique item is the `_id` of a User resource. type: array minLength: 1 uniqueItems: true items: description: The `_id` of a use resource. type: string maxLength: 48 example: - 82535922-335f-4c95-8000-c663a50aec9c values: description: >- An optional map of name/value variables to insert into the formatted message. For example, the for message tex `We have increased the rate of your CD from {oldApy}% to {newApy}%.`, the values should define `oldApy` and `newApy`:
`{ "oldApy": "1.750", "newApy": "1.800"}`. If omitted, the instance uses the `values` of the notification definition. x-apiture-key: variableName additionalProperties: $ref: '#/components/schemas/attributeValue' expiresAt: description: >- The notification's expiration timestamp in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTF format: `YYYY-MM-DDThh:mm:ss.sssZ`. If omitted, the instance uses the `expiresAt` of the notification definition. type: string format: date-time example: contextId: 0399abed-fd3d-4830-a88b-30f38b8a365c contextUri: /accounts/account/17434982-0419-4047-9855-389dac6970f7 userIds: - 82535922-335f-4c95-8000-c663a50aec9c - 191c5118-b6d5-4cc7-92bd-3eede737513e type: object x-apiture-flattened: true notification: title: Notification description: >- Representation of a notification resource. The embedded `_embedded.definition` notification definition contains the notification's `type`, `contextName`, `priority` and other properties (these properties are shared with all notifications defined by that definition.) The `_embedded.definition` is always included in the [`getNotification`](#op-getNotification) response as well as in the notifications in the [`getActiveNotifications`](#op-getActiveNotifications) response. **Note**: This representation does not contain the `message` property; use [`getActiveNotifications`](#op-getActiveNotifications) to obtain renderable [active notifications](#schema-activeNotification). example: _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'https://api.apiture.com/schemas/notifications/notification/v1.0.0/profile.json' dismissed: true dismissedAt: '2020-04-02T11:01:31.375Z' expired: false expiresAt: '2020-04-T21:00:00.000' _links: self: href: /notifications/notifications/0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:dismiss': href: /dismissedNotifications?notification=0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:expire': href: /expiredNotifications?notification=0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:definition': href: /notifications/definitions/00b68bc7-497c-4ce5-b8bd-47c6a8f33c22 _embedded: definition: _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'https://api.apiture.com/schemas/notifications/notificationDefinition/v1.0.0/profile.json' type: cdMaturingSoon contextName: account indicator: true priority: medium message: text: 'This CD account is maturing on {maturityDate}. Now is a good time to review your account maturity settings.' imageUri: 'https://cdn.assets.3rdpartybank.com/icons/en/notifications/cdMaturingSoon.png' values: maturityDate: '2020-04-09' _links: self: href: /notifications/definitions/0399abed-fd3d-4830-a88b-30f38b8a365c x-apiture-links: - rel: 'apiture:dismiss' operationId: dismissNotification - rel: 'apiture:expire' operationId: expireNotification - rel: 'apiture:context' method: GET title: Context description: The target resource or context associate with this notification. - rel: 'apiture:definition' description: The definition used to create this notification. operationId: getDefinition x-apiture-composition: - $ref: '#/components/schemas/summaryNotification' - properties: - values - expiresAt - dismissedAt - _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: description: Embedded objects readOnly: true allOf: - $ref: '#/components/schemas/notificationEmbeddedObjects' _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' contextUri: description: >- The URI of a resource that defines the content of this notification, such as an account, a user, or the global resource URI, `https://api.apiture.com/domains/notifications/global`. The URI need not have the `https://hostname` portion but must either start with `https://{hostname}/` _or_ be the full resource path starting with a `/`. type: string maxLength: 2048 format: uri example: /accounts/accounts/0a4511d1-1b63-4640-af0c-d4cdd6c88d37 _id: description: The unique identifier for this notification resource. This is an immutable opaque string. type: string maxLength: 48 readOnly: true dismissed: description: '`true` if this the user has dismissed this notification.' type: boolean readOnly: true notDismissible: description: '`true` if this the notification definition is `notDismissible`.' type: boolean readOnly: true expired: description: '`true` if this notification''s expiration date-time has passed.' type: boolean readOnly: true values: description: >- An optional map of name/value variables to insert into the formatted message. For example, the for message tex `We have increased the rate of your CD from {oldApy}% to {newApy}%.`, the values should define `oldApy` and `newApy`:
`{ "oldApy": "1.750", "newApy": "1.800"}`. If omitted, the instance uses the `values` of the notification definition. readOnly: true x-apiture-key: variableName additionalProperties: $ref: '#/components/schemas/attributeValue' expiresAt: description: >- The notification's expiration timestamp1 in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTF format: `YYYY-MM-DDThh:mm:ss.sssZ`. If omitted, the instance uses the `expiresAt` of the notification definition. readOnly: true type: string format: date-time dismissedAt: description: The date/time the user dismissed this notification. type: string readOnly: true format: date-time type: object x-apiture-flattened: true activeNotification: title: Active Notification description: Representation of an active notification resource for a client type (web or mobile) and user language(s) preference. example: _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'https://api.apiture.com/schemas/notifications/activeNotification/v1.0.0/profile.json' dismissed: false dismissedAt: '2020-04-02T11:01:31.375Z' expired: false expiresAt: '2020-04-T21:00:00.000' message: text: 'This CD account is maturing on {maturityDate}. Now is a good time to review your account maturity settings.' imageUri: 'https://cdn.assets.3rdpartybank.com/icons/en/notifications/cdMaturingSoon.png' _links: self: href: /notifications/notifications/0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:dismiss': href: /dismissedNotifications?notification=0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:definition': href: /notifications/definitions/00b68bc7-497c-4ce5-b8bd-47c6a8f33c22 _embedded: definition: _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'https://api.apiture.com/schemas/notifications/notificationDefinition/v1.0.0/profile.json' type: cdMaturingSoon contextName: account indicator: true priority: medium message: text: This CD account is maturing on 2020-04-09. Now is a good time to review your account maturity settings. imageUri: 'https://cdn.assets.3rdpartybank.com/icons/en/notifications/cdMaturingSoon.png' values: maturityDate: '2020-04-09' _links: self: href: /notifications/definitions/0399abed-fd3d-4830-a88b-30f38b8a365c x-apiture-links: - rel: 'apiture:dismiss' operationId: dismissNotification - rel: 'apiture:definition' description: The definition used to create this notification. operationId: getDefinition x-apiture-composition: - $ref: '#/components/schemas/summaryNotification' - properties: - message - _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: description: Embedded objects allOf: - $ref: '#/components/schemas/notificationEmbeddedObjects' _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' contextUri: description: >- The URI of a resource that defines the content of this notification, such as an account, a user, or the global resource URI, `https://api.apiture.com/domains/notifications/global`. The URI need not have the `https://hostname` portion but must either start with `https://{hostname}/` _or_ be the full resource path starting with a `/`. type: string maxLength: 2048 format: uri example: /accounts/accounts/0a4511d1-1b63-4640-af0c-d4cdd6c88d37 _id: description: The unique identifier for this notification resource. This is an immutable opaque string. type: string maxLength: 48 readOnly: true dismissed: description: '`true` if this the user has dismissed this notification.' type: boolean readOnly: true notDismissible: description: '`true` if this the notification definition is `notDismissible`.' type: boolean readOnly: true expired: description: '`true` if this notification''s expiration date-time has passed.' type: boolean readOnly: true message: description: >- The message text for this notification, derived from the notification definition's `message` or `webMessage` or `mobileMessage`, as per the `clientType` and `languages` query parameter on [`getActiveNotifications`](#op-getActiveNotifications). The [`getActiveNotifications`](#op-getActiveNotifications) operation also replaces variables in the message text template with the values in the `values` object. readOnly: true allOf: - $ref: '#/components/schemas/notificationMessage' type: object x-apiture-flattened: true notificationEmbeddedObjects: title: Notification Embedded Objects description: Nested objects for a notification instance. type: object properties: definition: description: The notification definition for this notification. type: object allOf: - $ref: '#/components/schemas/notificationDefinition' x-apiture-flattened: true notificationPriority: title: Notification Priority description: The priority of a notification. type: string maxLength: 8 x-apiture-enum: notificationPriority enum: - low - medium - high x-apiture-flattened: true notificationDefinitionFields: title: Notification Definition Fields x-apiture-fragment: true description: Common fields of the notification definition resource used to build other model schemas. x-apiture-composition: - $ref: '#/components/schemas/sharedNotificationDefinitionFields' - properties: - contextName - contextUriTemplate - contextUri properties: type: description: >- A programmatic name for the kind of notification this defines, such as `cdMaturingSoon` or `cdInGracePeriod`. Clients may elect to respond differently or specially to different well-known notification types. type: string pattern: '^[a-z][a-zA-Z0-9_$]{1,31}$' example: announcement default: announcement maxLength: 32 message: description: >- The default message text template for notification instances. This may be overridden for web or mobile client types with the `webMessage` or `mobileMessage` properties. A definition must defined either the `message` property or both `webMessage` or `mobileMessage` properties. allOf: - $ref: '#/components/schemas/notificationMessage' webMessage: description: >- The message text template for this notification for web application clients, when using [`GET /activeNotifications?clientType=web`](#op-activeNotifications. If this is not defined, notifications use `message`. allOf: - $ref: '#/components/schemas/notificationMessage' mobileMessage: description: >- The message text template for this notification for mobile application clients, when using [`GET /activeNotifications?clientType=mobile`](#op-activeNotifications. If this is not defined, notifications use `message`. allOf: - $ref: '#/components/schemas/notificationMessage' values: description: >- An optional map of name/value variables to insert into the formatted message. For example, the for message text `We have increased the rate of your CD from {oldApy}% to {newApy}%.`, the `values` should define `oldApy` and `newApy`:
`{ "oldApy": "1.750", "newApy": "1.800"}`. These `values` are defaults for instances which do not override `values`. x-apiture-key: variableName additionalProperties: $ref: '#/components/schemas/attributeValue' priority: description: The priority of this notification. allOf: - $ref: '#/components/schemas/notificationPriority' default: medium indicator: description: >- If `true`, each notification instantiated from this definition is a visual indicator (a.k.a. badge) rather than a dismissible visual message, and the [`dismissNotification`](#op-dismissNotification) operation is not allowed. This may not be `true` if `notDismissible` is true. type: boolean default: false notDismissible: description: >- If `true`, each notification instantiated from this definition does not have a UI control to dismiss it, and the [`dismissNotification`](#op-dismissNotification) operation is not allowed. This may not be `true` if `indicator` is true. type: boolean expiresAt: description: >- The notification definition's expiration timestamp in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTF format: `YYYY-MM-DDThh:mm:ss.sssZ`. When the definition expires, all active notifications also expire. type: string format: date-time contextName: description: >- A programmatic name of the context for this notification. This could be `global` for a global notification directed at all users, or an `account` if the notification applies to a banking account, or `user` if the notification applies to a user. type: string pattern: '^[a-z][a-zA-Z0-9_$]{1,31}$' maxLength: 32 contextUriTemplate: description: >- An optional URI template for expanding simple identifiers in contexts to full URIs. For example, the value `/accounts/accounts/{id}` will convert the simple id value `30f38b8a365c` to the URI `/accounts/accounts/30f38b8a365c`. This string must have the substring `{id}` in it. type: string maxLength: 2048 contextUri: description: >- The URI of a resource that defines the content of this notification, such as the global resource URI, `https://api.apiture.com/domains/notifications/global`. For non-global notifications, instances supply their own `contextUri` explicitly or by injecting a `contextId` into the definition's `contextUriTemplate`. type: string format: uri maxLength: 2048 type: object x-apiture-flattened: true notificationFields: title: Notification Fields x-apiture-fragment: true description: Common fields of the notification resource used to build other model schemas. properties: contextUri: description: >- The URI of a resource that defines the content of this notification, such as an account, a user, or the global resource URI, `https://api.apiture.com/domains/notifications/global`. The URI need not have the `https://hostname` portion but must either start with `https://{hostname}/` _or_ be the full resource path starting with a `/`. type: string maxLength: 2048 format: uri example: /accounts/accounts/0a4511d1-1b63-4640-af0c-d4cdd6c88d37 type: object x-apiture-flattened: true notificationMessage: title: Notification Message description: 'The presentation elements of a notification message: the text, image icon URL, and language variants for the text and image.' example: text: 'We have increased the rate of your CD from {oldApy}% to {newApy}%.' imageUri: 'https://cdn.assets.3rdpartybank.com/icons/en/notifications/cdRateIncreased.png' variants: es: text: 'Hemos aumentado la velocidad de su CD de {oldApy}% a {newApy}%.' imageUri: 'https://cdn.assets.3rdpartybank.com/icons/es/notifications/cdRateIncreased.png' fr: text: 'Nous avons augment\u00e9 le taux de votre CD de {oldApy}% \00e0 {newApy}%.' imageUri: 'https://cdn.assets.3rdpartybank.com/icons/fr/notifications/cdRateIncreased.png' x-apiture-composition: - $ref: '#/components/schemas/simpleMessage' - properties: - variants properties: text: description: >- A notification message in [Github Flavored Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/). The text may contain variable references (identifiers in braces such as {oldApy}) which are replaced by corresponding `values` from the notification instance or definition. In the example, the `values` must define the variables `oldApy` and `newApy`. type: string maxLength: 4096 minLength: 1 format: markdown example: 'We have increased the rate of your CD from {oldApy}% to {newApy}%.' imageUri: description: The URL of an icon or visual representation of this notification or notification definition. type: string format: uri maxLength: 2048 variants: description: >- The language-specific variants of this message text. The keys in this object are [RFC 7231](https://tools.ietf.org/html/rfc7231#section-3.1.3.1) language codes. x-apiture-key: languageCode type: object additionalProperties: $ref: '#/components/schemas/simpleMessage' type: object x-apiture-flattened: true simpleMessage: title: Notification Message description: The message and optional image (icon) URI for a notification message. required: - text properties: text: description: >- A notification message in [Github Flavored Markdown](https://help.github.com/articles/basic-writing-and-formatting-syntax/). The text may contain variable references (identifiers in braces such as {oldApy}) which are replaced by corresponding `values` from the notification instance or definition. In the example, the `values` must define the variables `oldApy` and `newApy`. type: string maxLength: 4096 minLength: 1 format: markdown example: 'We have increased the rate of your CD from {oldApy}% to {newApy}%.' imageUri: description: The URL of an icon or visual representation of this notification or notification definition. type: string format: uri maxLength: 2048 example: text: 'We have increased the rate of your CD from {oldApy}% to {newApy}%.' imageUri: 'https://cdn.assets.3rdpartybank.com/icons/en/notifications/cdRateIncreased.png' type: object x-apiture-flattened: true createNotification: title: Create Notification description: Representation used to create a new notification for a user from a notification definition and a specific notification context. required: - definitionId - userId - contextUri example: _profile: 'https://api.apiture.com/schemas/notifications/createNotification/v1.0.0/profile.json' definitionId: 41cf829b-879d-4334-9085-7ac18333ce47 userId: 80ebfabf-7a26-48a9-96c2-86f4dca8706f contextUri: /accounts/account/ba611f3a-ab1b-4ad7-aaf6-56a240123818 x-apiture-composition: - $ref: '#/components/schemas/abstractRequest' - $ref: '#/components/schemas/notificationFields' - properties: - definitionId - userId 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 contextUri: description: >- The URI of a resource that defines the content of this notification, such as an account, a user, or the global resource URI, `https://api.apiture.com/domains/notifications/global`. The URI need not have the `https://hostname` portion but must either start with `https://{hostname}/` _or_ be the full resource path starting with a `/`. type: string maxLength: 2048 format: uri example: /accounts/accounts/0a4511d1-1b63-4640-af0c-d4cdd6c88d37 definitionId: description: >- The `_id` of an active notification definition. The properties of the definition will be used to set some of the properties of this new notification. type: string maxLength: 48 userId: description: The ID of a digital banking user who owns and can view and dismiss this notification. type: string maxLength: 48 type: object x-apiture-flattened: true summaryNotification: title: Notification Summary description: >- Summary representation of a notification resource in notifications collections. This representation normally does not contain any `_embedded` objects. If needed, call the `GET` operation on the item's `self` link to get `_embedded` objects. example: _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'https://api.apiture.com/schemas/notifications/summaryNotification/v1.0.0/profile.jsons' dismissed: false expired: false dismissedAt: '2020-04-02T11:01:31.375Z' expiresAt: '2020-04-18T12:15:21.375Z' _links: self: href: /notifications/notifications/0399abed-fd3d-4830-a88b-30f38b8a365c x-apiture-composition: - $ref: '#/components/schemas/abstractResource' - $ref: '#/components/schemas/notificationFields' - properties: - _id - dismissed - notDismissible - expired 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' contextUri: description: >- The URI of a resource that defines the content of this notification, such as an account, a user, or the global resource URI, `https://api.apiture.com/domains/notifications/global`. The URI need not have the `https://hostname` portion but must either start with `https://{hostname}/` _or_ be the full resource path starting with a `/`. type: string maxLength: 2048 format: uri example: /accounts/accounts/0a4511d1-1b63-4640-af0c-d4cdd6c88d37 _id: description: The unique identifier for this notification resource. This is an immutable opaque string. type: string maxLength: 48 readOnly: true dismissed: description: '`true` if this the user has dismissed this notification.' type: boolean readOnly: true notDismissible: description: '`true` if this the notification definition is `notDismissible`.' type: boolean readOnly: true expired: description: '`true` if this notification''s expiration date-time has passed.' type: boolean readOnly: true type: object x-apiture-flattened: true activeNotifications: title: Active Notifications description: >- A list of active notifications for a user, in high to low priority order. These are notifications for a context, a client type (web, mobile), and one or more language preferences. type: object x-apiture-composition: - $ref: '#/components/schemas/abstractResource' - 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: description: Embedded objects. allOf: - $ref: '#/components/schemas/embeddedActiveNotifications' _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' x-apiture-flattened: true embeddedActiveNotifications: title: Embedded Active Notifications description: The list of active notifications for a user's context. type: object properties: items: description: 'An array of active notifications, in high to low priority order.' type: array items: $ref: '#/components/schemas/activeNotification' x-apiture-flattened: true notifications: title: Notification Collection description: >- Collection of notifications. The items in the collection are ordered in the `_embedded.items` array; the `name` is `notifications`. The top-level `_links` object may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`). example: _profile: 'https://api.apiture.com/schemas/notifications/notifications/v1.0.0/profile.json' name: notifications start: 10 limit: 10 count: 67 _links: self: href: /notifications/notifications?start=10&limit=10 first: href: /notifications/notifications?start=0&limit=10 next: href: /notifications/notifications?start=20&limit=10 collection: href: /notifications/notifications _embedded: items: anyOf: - _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'https://api.apiture.com/schemas/notifications/summaryNotification/v1.0.0/profile.json' _links: self: href: /notifications/notifications/0399abed-fd3d-4830-a88b-30f38b8a365c - _id: d62c0701-0d74-4836-83f9-ebf3709442ea _profile: 'https://api.apiture.com/schemas/notifications/summaryNotification/v1.0.0/profile.json' _links: self: href: /notifications/notifications/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 notification items. type: array items: $ref: '#/components/schemas/summaryNotification' _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 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 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 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 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 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 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 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 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 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 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. The request body or 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' 422NotificationDefinition: description: >- Unprocessable Entity. The request body or 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. x-apiture-errors: - indicatorAndNotDismissibleMutuallyExclusive - idNotMatchPath content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 400ExpireNotificationDefinition: description: Bad Request. The definition parameter was malformed or does not refer to an existing or accessible definition. x-apiture-errors: - definitionRefNotFound content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 404NotificationDefinition: description: >- Not Found. There is no such definition resource at the specified `{definitionId}`. 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' 400DismissNotification: description: Bad Request. The notification parameter was malformed or does not refer to an existing or accessible notification. x-apiture-errors: - notificationRefNotFound content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 409DismissNotificationConflict: description: >- Conflict. The request to dismiss the notification is not allowed. The `_error` field in the response will contain details about the request error. x-apiture-error: - dismissNotAllowed content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 409InstancesConflict: description: >- Conflict. The definition has expired, or the `createNotifications` request uses a `contextUriTemplate` that does not match the notification definition's existing `contextUriTemplate`, or instances contain only a `contextId` and the request or definition has no `contextUriTemplate`, or a request was made to create notification instance for a global notification definition. x-apiture-errors: - definitionExpired - mismatchedContextUriTemplate - definitionMissingContextUriTemplate - cannotCreateInstancesFromGlobalDefinition content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 400ExpireNotification: description: Bad Request. The notification parameter was malformed or does not refer to an existing or accessible notification. x-apiture-errors: - notificationRefNotFound content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 409ExpireNotificationConflict: description: >- Conflict. The request to expire the notification is not allowed. 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' 404Notification: description: >- Not Found. There is no such notification resource at the specified `{notificationId}`. 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' 422CreateNotification: description: >- Unprocessable Entity. The request body or 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' 204Deleted: description: No Content. The resource was deleted successfully. parameters: definitionQueryParam: name: definition required: true in: query description: >- A string which uniquely identifies a definition which is to added to the selected definitions resource set. This may be the unique definitionId or the URI of the definition. schema: type: string definitionIdPathParam: name: definitionId description: The unique identifier of this definition. This is an opaque string. in: path required: true schema: type: string filterQueryParam: name: filter in: query description: 'Optional filter criteria. See [filtering](https://developer.apiture.com/docs/concepts/filtering).' schema: type: string qQueryParam: name: q in: query description: 'Optional search string. See [searching](https://developer.apiture.com/docs/concepts/searching).' schema: type: string dismissedQueryParam: name: dismissed description: Return only notifications whose `dismissed` matches the query parameter value. in: query schema: type: boolean expiredQueryParam: name: dismissed description: Return only objects whose `dismissed` matches the query parameter value. in: query schema: type: boolean typeQueryParam: name: type description: >- Return only notifications whose `type` matches the one of query parameter values. The array item delimiter is the `|` pipe character.
Examples:
`?type=cdMaturingSoon`
`?type=cdMaturingSoon|cdInGracePeriod` in: query style: pipeDelimited schema: type: array items: type: string definitionTypeQueryParam: name: type description: >- Return only notification definitions whose `type` matches the one of query parameter values. The array item delimiter is the `|` pipe character.
Examples:
`?type=cdMaturingSoon`
`?type=cdMaturingSoon|cdInGracePeriod` in: query style: pipeDelimited schema: type: array items: type: string definitionContextNameQueryParam: name: contextName description: >- Return only notification definitions whose `contextName` matches the one of query parameter values. The array item delimiter is the `|` pipe character.
Examples:
`?contextName=account`
`?contextName=user|global` in: query style: pipeDelimited schema: type: array items: type: string contextNameQueryParam: name: contextName description: >- Return only notifications whose `contextName` matches the one of query parameter values. The array item delimiter is the `|` pipe character.
Examples:
`?contextName=account`
`?contextName=user|global` in: query style: pipeDelimited schema: type: array items: type: string contextUriQueryParam: name: contextUri in: query description: >- Return only notifications whose `contextUri` matches the query parameter value. If the value begins with `/`, only the path portion of the URi is matched.
Examples:
`?contextUri=/accounts/accounts/c6082333-be32-4171-b0c5-d161bcdbd6db` schema: type: string notificationQueryParam: name: notification required: true in: query description: A string which uniquely identifies a notification. This may be the unique `notificationId` or the URI of the notification. schema: type: string contextQueryParam: name: context description: >- A string which uniquely identifies a notification context resource by context name or context URI. The array item delimiter is the `|` pipe character.
Examples:
`?context=/accounts/accounts/c6082333-be32-4171-b0c5-d161bcdbd6db`
`?context=account`
`?context=global|user` in: query required: true style: pipeDelimited schema: type: array items: type: string notificationIdPathParam: name: notificationId description: The unique identifier of this notification. This is an opaque string. in: path required: true schema: type: string ifMatchHeaderParam: name: If-Match description: 'The entity tag that was returned in the `ETag` response. If passed, 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 requestBodies: notificationDefinition: content: application/hal+json: schema: $ref: '#/components/schemas/notificationDefinition' application/json: schema: $ref: '#/components/schemas/notificationDefinition' required: true 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 and `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: data/read: 'Read access to non-account, non-profile data.' data/write: 'Write (update) access to non-account, non-profile data.' admin/write: 'Admin write (update) access to non-account, non-profile data.' admin/read: 'Admin Read access to non-account, non-profile data.' admin/delete: 'Admin access to non-account, non-profile data.' admin/full: 'Full admin access to non-account, non-profile data.'