openapi: 3.0.0 info: title: Consents description: > The Consents API tracks a user's consent of financial institution policies and documents such as banking product terms and conditions, electronic consent, and privacy policy. ## Target Documents A consent resource holds the URI of a target document (typically, a PDF document). Each [consent](#schema-consent) also has a `type`, such as `privacyPolicy` or `productTermsAndConditions` or `electronicConsent`, which indicates the target document's purpose and hence what kind of consent this is. (See [`consentTypeNames`](#schema-consentTypeNames).) The consent also holds the document's media type, specific document revision identification string, and the time stamp that the document was last revised (modified). If the document is later revised, any previously given consents for any revision of that document become `stale`; this indicates the user should review and consent to the _revised_ document. ## Contexts A consent may be associated with a _context_ in which an application or service is requesting the consent; the context is represented as the URI of some resource. For example, two different banking products (DDA1, DDA2) at a financial institution may share the same terms and conditions document, D0. If the user is opening an account of type DDA1, the client can create a consent for D0 using the product URI for DDA1 as the context. When the user opens a new account for product DDA2, the client can create a new consent for D0 using product DDA2's URI as the context. Because the contexts of the two consents are different, the two consents are independent of each other, indicating that the user must consent to the terms and conditions each time they open an account, even if they have consented to the same document earlier. The context is optional. For example, for the financial institution's privacy policy, there is no specific context. ## Life Cycle When a banking application or service (the requester) wishes a user to agree to or consent to a document, it [creates a new consent resource](#op-createConsent) to track the request and the user's response. The user can consent to a document to indicate that they agree to the terms described in the document. This is typically done when the user checks an "I agree" checkbox or other user experience. To record the consent given by the user, the client application which serves as the controller issues a [`POST` to the `apiture:give` link](#op-giveConsent) on a consent resource. This sets the `state` to `given` and records the date and time on the consent. When a user gives consent to a document, _all_ consent resources which match the target document, context URI, and user ID are also marked as `given`, although the action can be scoped to just a specific instance. A client can [check for pending or stale consents](#op-getNeededConsents) for a user. Consents are not directly mutable (the `PUT` and `PATCH` verbs are not supported), but other operations described below may update a consent resource to indicate a user has given or revoked consent, that a consent is stale, or that a requester has rescinded a request for consent. If the user wishes to undo or _revoke_ a specific consent, the client application should `POST` to the `apiture:revoke` link on a consent resource ([`/revokedConsents?consent={consentId}`](#op-revokeConsent)) to reset the consent back to the `pending` state. If the requester no longer requires the user's consent, it can rescind the request with [`POST /rescindedConsents?type={type}&document={documentUri}&context={contextUri}&user=user`](#op-rescindConsents). This sets the `state` to `rescinded` on the first matching consent. For example, if the user is removed as a joint owner of an account of type DDA2, rescinding the `productTermsAndConditions` consents matches and removes only the first matching consent for DDA2. (The user may be an owner of other accounts on product DDA2, and their consent must be tracked and possibly requested again if the terms and conditions for DDA2 change.) ## Document revisions If the document is revised (for example, the financial institution has updated their privacy policy), a client can mark a document as revised via [`POST /revisedDocuments`](#op-reviseDocument). All consents associated with the older revisions of the document are marked `stale`. A _stale_ consent indicates that the user should consent to the revised document. The client applications should notify the user that the document has changed (such as via email or or via notification at their next login) and present the revised document to the user for them to accept. # Error Types Error responses in this API may have one of the `type` values described below. See [Errors](https://developer.apiture.com/docs/concepts/errors) for more information on error responses and error types.

consentRefNotFound

**Description**: No consent was found that matches the ?consent= query parameter.
**Remediation**: Use the links in a consent resource, or provide a valid consent ID.

consentTypeNameInUse

**Description**: An update to the consent type names omits one or more types that are in use.
**Remediation**: Include all in-use type names. The `attributes` object in the error may have the following properties: | Property | Type | Description | |----------|------|-------------| | typeNames | [undefined] | The list of type names that are in use but missing from the request.
Example: `productTermsAndConditions` |

invalidConsentType

**Description**: The specified consent type does not match existing consent type names.
**Remediation**: Supply a consent type from the consent type names in the `/consentTypeNames` resource.

invalidContextUri

**Description**: The consent context URI was not well formed.
**Remediation**: Pass a valid URI.

invalidDocumentRevision

**Description**: The time stamp on the revised document predates the existing time stamp.
**Remediation**: Revised documents must have newer time stamps.

invalidDocumentUri

**Description**: The document URI was not well formed.
**Remediation**: Pass a valid URI. version: 0.9.0 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: Consents description: User Consent of a Policy or Other Document - name: Consent Actions description: Actions on Consent Resources - name: Documents description: Manage Documents Subject to Consent - name: Consent Type Name description: Allowed Consent Types - name: API description: The Consents API paths: /consents: get: summary: Return a collection of consents description: >- Return a [paginated](http://developer.apiture.com/docs/concepts/pagination) [sortable](http://developer.apiture.com/docs/concepts/sorting) [filterable](http://developer.apiture.com/docs/concepts/filtering) [searchable](http://developer.apiture.com/docs/concepts/searching) collection of consents. The [links](http://developer.apiture.com/docs/concepts/links) in the response include pagination links. operationId: getConsents tags: - Consents x-apiture-traits: sortBy: - type - userId - document.revisedAt itemSchema: consent filters: state: filter: - eq - ne - contains - search type: filter: - eq - ne - contains - search userId: filter: - eq - ne - contains - search contextUri: filter: - eq - ne - contains - search secondaryContextUri: filter: - eq - ne - contains - search parameters: - name: type in: query description: >- Subset the response to those with this `type` value. Use `|` to separate multiple values. For example, `?type=termsAndCondition` matches only items whose `type` is `termsAndCondition` `?type=privacyPolicy|electronicConsent` matches items whose type is `privacyPolicy` or `electronicConsent`. This is combined with an implicit and with other filters if they are used. See [filtering](https://developer.apiture.com/docs/concepts/filtering). schema: type: string - name: state in: query description: >- Subset the response to those with this `state` value. Use `|` to separate multiple values. For example, `?type=given|stale` matches only items whose `state` is `given` or `stale`. This is combined with an implicit and with other filters if they are used. See [filtering](https://developer.apiture.com/docs/concepts/filtering). schema: type: string - name: userId in: query description: >- Subset the response to those with this `userId` value. Use `|` to separate multiple values. This is for administrative use; bank users can only see their own consents. schema: type: string - name: contextUri in: query description: Subset the response to those with this `contextUri` value. Use `|` to separate multiple values. schema: type: string - name: secondaryContextUri in: query description: Subset the response to those with this `secondaryContextUri` value. schema: type: string - name: start in: query description: The zero-based index of the first consent 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 consent representations to return in this page. schema: type: integer format: int32 default: 100 - name: sortBy in: query description: >- Optional sort criteria. See [sort criteria format](http://developer.apiture.com/docs/concepts/sorting), such as `?sortBy=field1,-field2`.
This collection may be sorted by following properties:
• `type`
• `userId`
• `document.revisedAt` schema: type: string - name: filter in: query description: >- Optional filter criteria. See [filtering](http://developer.apiture.com/docs/concepts/filtering).
This collection may be filtered by following properties and functions:
• Property `state` using functions `eq`, `ne`, `contains`, `search`
• Property `type` using functions `eq`, `ne`, `contains`, `search`
• Property `userId` using functions `eq`, `ne`, `contains`, `search`
• Property `contextUri` using functions `eq`, `ne`, `contains`, `search`
• Property `secondaryContextUri` using functions `eq`, `ne`, `contains`, `search` schema: type: string - $ref: '#/components/parameters/qQueryParam' responses: '200': description: OK content: application/hal+json: schema: $ref: '#/components/schemas/consents' application/json: schema: $ref: '#/components/schemas/consents' '400': $ref: '#/components/responses/400' '422': $ref: '#/components/responses/422' security: - apiKey: [] accessToken: - profile/read post: summary: Create a new consent description: Create a new consent resource or locate an existing consent. operationId: createConsent tags: - Consents requestBody: content: application/hal+json: schema: $ref: '#/components/schemas/createConsent' application/json: schema: $ref: '#/components/schemas/createConsent' description: The data necessary to create a new consent. required: true responses: '200': description: OK. An existing consent resource for the document and user was found and the `contextUri` of this request added to that resource. headers: Location: description: >- The URI of the existing consent resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with `scheme://host` schema: type: string format: uri ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for operations which update the resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/consent' application/json: schema: $ref: '#/components/schemas/consent' '201': description: Created headers: Location: description: >- The URI of the new consent resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with `scheme://host` schema: type: string format: uri ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for operations which update the resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/consent' application/json: schema: $ref: '#/components/schemas/consent' '400': $ref: '#/components/responses/400CreateConsent' security: - apiKey: [] accessToken: - profile/write parameters: [] '/consents/{consentId}': parameters: - $ref: '#/components/parameters/consentIdPathParam' get: summary: Fetch a representation of this consent description: 'Return a [HAL](http://developer.apiture.com/docs/concepts/hal) representation of this consent resource.' operationId: getConsent tags: - Consents parameters: - $ref: '#/components/parameters/ifNoneMatchHeaderParam' responses: '200': description: OK headers: ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for operations which update this consent resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/consent' application/json: schema: $ref: '#/components/schemas/consent' '304': $ref: '#/components/responses/304' '404': $ref: '#/components/responses/404Consent' security: - apiKey: [] accessToken: - profile/read patch: summary: Update this consent description: >- Perform a partial update of this consent. Only the `secondaryContextUri` and `contextUri` are patchable. Fields which are omitted are not updated. Nested `_embedded` and `_links` are ignored if included. operationId: patchConsent tags: - Consents security: - apiKey: [] accessToken: - profile/write parameters: - $ref: '#/components/parameters/ifMatchHeaderParam' requestBody: content: application/hal+json: schema: $ref: '#/components/schemas/consent' application/json: schema: $ref: '#/components/schemas/consent' required: true 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 consent resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/consent' application/json: schema: $ref: '#/components/schemas/consent' '400': $ref: '#/components/responses/400' '404': $ref: '#/components/responses/404Consent' '412': $ref: '#/components/responses/412' '422': $ref: '#/components/responses/422' /neededConsents: get: summary: Get needed consents description: >- Return a list of needed consents (both `pending` and `stale` consents) for a user. If no consents exists for a user ID (including if the user ID is not found), the response is an empty collection. operationId: getNeededConsents tags: - Consents security: - apiKey: [] accessToken: - profile/read parameters: - name: userId description: >- The user ID of the user; This is the `_id` of the User resource. If omitted, the returned list is the needed consents for the currently authenticated user. in: query schema: type: string - name: consolidate description: >- If `true`, two or more duplicate consents in the response body that have the same `type` and `contextUri` are consolidated such that the result contain only one of the duplicates. **Warning**: the client should **not** use `?matching=false` when the user [gives consent](#op-giveConsent) to consents resources in the consolidated response. in: query required: false schema: type: boolean default: false responses: '200': description: OK. content: application/hal+json: schema: $ref: '#/components/schemas/consents' application/json: schema: $ref: '#/components/schemas/consents' /revisedDocuments: post: summary: 'Mark a document as revised, rendering corresponding consents as stale' description: >- Mark a document as revised. All `given` consents related to that document, document type, and the optional context are marked as `stale`, indicating that the user should be presented the document and asked to consent to the terms of the revised document. The newly `stale` consents are listed in the result of `GET /neededConsents`. This operation is restricted to financial institution administrators or service applications. Any `given` consents which already match the document and time stamp (and, optionally, document revision) are not marked stale. operationId: reviseDocument tags: - Documents security: - apiKey: [] accessToken: - admin/write requestBody: content: application/hal+json: schema: $ref: '#/components/schemas/revisedDocument' application/json: schema: $ref: '#/components/schemas/revisedDocument' description: The details of the revised document. required: true responses: '202': description: >- Accepted. The operation was received and accepted. The operation continues to update all matching consents, setting `state` changed to `stale` and changing the `revision` and `documentRevisedAt` to match the values in the request. content: application/hal+json: schema: $ref: '#/components/schemas/revisedDocument' application/json: schema: $ref: '#/components/schemas/revisedDocument' '400': $ref: '#/components/responses/400RevisedDocument' '409': $ref: '#/components/responses/409RevisedDocumentConflict' '412': $ref: '#/components/responses/412' parameters: [] /movedDocuments: post: summary: Change the location of a document description: >- If the financial institution moves a document that is tracked by consents, such as the Terms and Conditions document for a product, use this operation to update the document URI of any consents. operationId: moveDocument tags: - Documents security: - apiKey: [] accessToken: - admin/write requestBody: content: application/hal+json: schema: $ref: '#/components/schemas/movedDocument' application/json: schema: $ref: '#/components/schemas/movedDocument' description: The details of the revised document. required: true responses: '202': description: >- Accepted. The operation was received and accepted. The operation continues to update all matching consents, setting `state` changed to `stale` and changing the `revision` and `documentRevisedAt` to match the values in the request. content: application/hal+json: schema: $ref: '#/components/schemas/movedDocument' application/json: schema: $ref: '#/components/schemas/movedDocument' '400': $ref: '#/components/responses/400MovedDocument' '409': $ref: '#/components/responses/409MovedDocumentConflict' '412': $ref: '#/components/responses/412' parameters: [] /givenConsents: post: operationId: giveConsent summary: Give a consent description: >- Indicate that a user has given consent to a document. This marks the given consent as `given`. If `scope` is matching, _all_ matching needed consents (`pending` or `stale` consents which have the same `type`, `document.uri` and `contextUri`) are marked as `given`. This operation may be invoked by using `POST` on the `apiture:giveConsent` link on a consent resource; there is no query parameter. security: - apiKey: [] accessToken: - profile/write tags: - Consent Actions parameters: - $ref: '#/components/parameters/consentQueryParam' - name: scope description: >- The scope of the given consent. If `instance`, only the consent named in the `?consent=` query parameter is marked as `given`. If `matching`, all needed consent matching the named in the `?consent=` query parameter (`pending` or `stale` consents which have the same `type`, `document.uri` and `contextUri`) are marked as `given`. The default if omitted is `matching`. in: query schema: type: string enum: - instance - matching responses: '200': description: >- OK. The operation succeeded. The consents were updated and their `state` changed to `given`. The response may include an array of additional consents `_embedded.consents` which match the named consent and which were also given. content: application/hal+json: schema: $ref: '#/components/schemas/consent' application/json: schema: $ref: '#/components/schemas/consent' '400': $ref: '#/components/responses/400GiveConsent' '409': $ref: '#/components/responses/409GiveConsentConflict' '412': $ref: '#/components/responses/412' /revokedConsents: post: operationId: revokeConsent summary: Revoke a consent description: >- A user has revoked a previously given consent. This operation updates a consent by adding it to the set of revoked consents. This changes the `state` property of the consent to `revoked`. This operation is available via the `apiture:revoke` link on the consent resource, if and only if the consent is eligible for the revoke operation. The responses is the updated representation of the consent. The `If-Match` request header, if present, must match the current entity tag value of the consent. tags: - Consent Actions security: - apiKey: [] accessToken: - profile/write parameters: - $ref: '#/components/parameters/consentQueryParam' - $ref: '#/components/parameters/ifMatchHeaderParam' responses: '200': description: OK. The operation succeeded. The consent was updated and its `state` changed to `revoked`. headers: ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for operations which update the resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/consent' application/json: schema: $ref: '#/components/schemas/consent' '400': $ref: '#/components/responses/400RevokeConsent' '409': $ref: '#/components/responses/409RevokeConsentConflict' '412': $ref: '#/components/responses/412' /rescindedConsents: post: operationId: rescindConsents summary: Rescind matching consents description: >- Rescind consent requests which match the specified consent type, optional user and context. This action is typically performed by the financial institution to indicate that it no longer requires the user's consent. For example, a service may rescind a consent if a user is removed as an account owner or as an authorized signer, when an account application expires, or when they remove a banking product. Rescinding consent changes the `state` property of the matching consent resources to `rescinded`. The client must pass the at least the document `type` in order to find matching consents. If the optional `document`, `user`, and/or `context` are specified, only consents that match those options and `type` are rescinded. The response is the collection of updated matching consent resources. If no matching consents were found, the consents collection response has an empty `items` array. tags: - Consent Actions security: - apiKey: [] accessToken: - admin/write parameters: - name: type in: query description: Specify the consent `type` to rescind. required: true schema: type: string - name: context in: query description: The URI of the consent context. schema: type: string format: uri - name: user in: query description: Rescind all matching consents for the user with this user ID. schema: type: string format: uri - name: document in: query description: >- The URI of the target document. This is not _required_ but if passed, the `document.uri` must match as well as the other required query parameters. schema: type: string format: uri responses: '200': description: OK. The operation succeeded. The matching consents are updated and their `state` changed to `rescinded`. headers: ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for operations which update the resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/consents' application/json: schema: $ref: '#/components/schemas/consents' '400': $ref: '#/components/responses/400RescindConsent' '412': $ref: '#/components/responses/412' /consentTypeNames: get: summary: Retrieve the set of consent type names description: >- Return the set of reserved consent type names. The `name` property of a consent must be one of these reserved names. This list may be updated by the financial institution via the `updateConsentTypeNames` operation. The default list includes the following names: * `productTermsAndConditions` * `privacyPolicy` * `electronicConsent` operationId: getConsentTypeNames security: - apiKey: [] accessToken: - data/read tags: - Consent Type Name responses: '200': description: OK headers: ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for operations which update the resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/consentTypeNames' application/json: schema: $ref: '#/components/schemas/consentTypeNames' parameters: [] put: summary: Replace the set of consent type names description: >- A financial institution can use this operation to register additional types of consent that they may request from their users. The `type` property of a consent must be one of these reserved names. This operation completely replaces the set of reserved consent type names, so it should include all items from the `getConsentTypeNames` that are in use. This operation is only available to financial institution administrators. operationId: updateConsentTypeNames security: - apiKey: [] accessToken: - admin/write tags: - Consent Type Name parameters: - $ref: '#/components/parameters/ifMatchHeaderParam' requestBody: content: application/hal+json: schema: $ref: '#/components/schemas/consentTypeNames' application/json: schema: $ref: '#/components/schemas/consentTypeNames' description: The set of consent type names required: true responses: '200': description: OK headers: ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for operations which update the resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/consentTypeNames' application/json: schema: $ref: '#/components/schemas/consentTypeNames' '400': $ref: '#/components/responses/400' '409': $ref: '#/components/responses/409ConsentTypeListConflict' /: 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: [] parameters: [] /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 tags: - API security: - apiKey: [] parameters: [] /labels: get: summary: Localized Labels description: >- Return a JSON object which defines labels for enumeration types defined by the schemas defined in this API. The labels in the response may not all match the requested language; some may be in the default language (`en-us`). operationId: getLabels security: - apiKey: [] parameters: - name: Accept-Language in: header description: >- The weighted language tags which indicate the user's preferred natural language for the localized labels in the response, as per [RFC 7231](https://tools.ietf.org/html/rfc7231#section-5.3.5). schema: type: string responses: '200': description: OK content: application/hal+json: schema: $ref: '#/components/schemas/labelGroups' application/json: schema: $ref: '#/components/schemas/labelGroups' tags: - API x-apiture-errors: invalidDocumentRevision: description: The time stamp on the revised document predates the existing time stamp remediation: Revised documents must have newer time stamps consentRefNotFound: description: No consent was found that matches the ?consent= query parameter remediation: 'Use the links in a consent resource, or provide a valid consent ID' consentTypeNameInUse: description: An update to the consent type names omits one or more types that are in use. remediation: Include all in-use type names attributes: properties: typeNames: description: The list of type names that are in use but missing from the request. type: array items: string example: - productTermsAndConditions invalidDocumentUri: description: The document URI was not well formed. remediation: Pass a valid URI. invalidContextUri: description: The consent context URI was not well formed. remediation: Pass a valid URI. invalidConsentType: description: The specified consent type does not match existing consent type names remediation: Supply a consent type from the consent type names in the `/consentTypeNames` resource x-apiture-traits: - api: title: Consents basePath: consents applied: true immutable: true links: - getConsents - createConsent - reviseDocument - rescindConsents - getNeededConsents - getConsentTypeNames - updateConsentTypeNames - getApi - getApiDoc - getLabels - state: state: given name: consent verb: give - state: state: revoked name: consent verb: revoke - state: state: rescinded name: consent verb: rescind - security: baseScope: data applied: true servers: - url: 'https://api.devbank.apiture.com/consents' components: parameters: consentIdPathParam: name: consentId description: The unique identifier of this consent. This is an opaque string. in: path required: true schema: type: string consentQueryParam: name: consent required: true in: query description: >- A string which uniquely identifies a consent which is to added to the given consents resource set. This may be the unique `consentId` or the URI of the consent. 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` returns 304 (Not Modified) and no response body, else the resource representation is returned. in: header schema: type: string ifMatchHeaderParam: name: If-Match description: The entity tag that was returned in the `ETag` response. This must match the current entity tag of the resource. in: header schema: type: string filterQueryParam: name: filter in: query description: 'Optional filter criteria. See [filtering](http://developer.apiture.com/docs/concepts/filtering).' schema: type: string qQueryParam: name: q in: query description: 'Optional search string. See [searching](http://developer.apiture.com/docs/concepts/searching).' schema: type: string 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 contains details about the request error. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' '412': description: >- Precondition Failed. The supplied `If-Match` header value does not match the most recent `ETag` response header value. The resource has changed in the interim. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' '422': description: >- Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The `_error` field in the response contains details about the request error. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 400RescindConsent: description: |- Bad Request. One or more query parameters is not well-formed. This error response may have one of the following `type` values: * [`invalidDocumentUri`](#err-invalidDocumentUri) * [`invalidContextUri`](#err-invalidContextUri) x-apiture-errors: - invalidDocumentUri - invalidContextUri content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 400CreateConsent: description: |- Bad Request. The request body or content was not well formed. This error response may have one of the following `type` values: * [`invalidConsentType`](#err-invalidConsentType) x-apiture-errors: - invalidConsentType content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 404Consent: description: >- Not Found. There is no such consent resource at the specified `{consentId}`. The `_error` field in the response contains details about the request error. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 400RevokeConsent: description: |- Bad Request. The consent parameter was malformed or does not refer to an existing or accessible consent. This error response may have one of the following `type` values: * [`consentRefNotFound`](#err-consentRefNotFound) x-apiture-errors: - consentRefNotFound content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 409RevokeConsentConflict: description: Conflict. The request to revoke the consent is not allowed. The `_error` field in the response contains details about the request error. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 400GiveConsent: description: |- Bad Request. The consent parameter was malformed or does not refer to an existing or accessible consent. This error response may have one of the following `type` values: * [`consentRefNotFound`](#err-consentRefNotFound) x-apiture-errors: - consentRefNotFound content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 409GiveConsentConflict: description: >- Conflict. The request to give the consent is not allowed. The `_error` field in the response contains details about the request error. For example, the consent may have been revoked or rescinded. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 400RevisedDocument: description: |- Bad Request. The request body or content was not well formed. This error response may have one of the following `type` values: * [`invalidDocumentUri`](#err-invalidDocumentUri) * [`invalidDocumentRevision`](#err-invalidDocumentRevision) x-apiture-errors: - invalidDocumentUri - invalidDocumentRevision content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 409RevisedDocumentConflict: description: Conflict. The request contains semantically invalid data. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 400MovedDocument: description: |- Bad Request. The request body or content was not well formed. This error response may have one of the following `type` values: * [`invalidDocumentUri`](#err-invalidDocumentUri) x-apiture-errors: - invalidDocumentUri content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 409MovedDocumentConflict: description: Conflict. The request contains semantically invalid data. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 409ConsentTypeListConflict: description: |- The request does not include consent type names that are in use in existing consent resource. This error response may have one of the following `type` values: * [`consentTypeNameInUse`](#err-consentTypeNameInUse) x-apiture-errors: - consentTypeNameInUse content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' securitySchemes: apiKey: type: apiKey name: API-Key in: header description: >- API Key based authentication. Each thing must pass its private, unique API key, allocated in the developer portal, via the `API-Key: {api-key}` request header. accessToken: type: oauth2 description: >- OAuth2 client access token authentication. The client authenticates against the server at `authorizationUrl`, passing the client's private `clientId` (and optional `clientSecret`) as part of this flow. The client obtains an access token from the server at `tokenUrl`. It then passes the received access token via the `Authorization: Bearer {access-token}` header in subsequent API calls. The authorization process also returns a refresh token which the client should use to renew the access token before it expires. flows: authorizationCode: authorizationUrl: 'https://auth.devbank.apiture.com/auth/oauth2/authorize' tokenUrl: 'https://api.devbank.apiture.com/auth/oauth2/token' scopes: banking/read: Read access to consents banking/write: Write (update) access to consents banking/full: Full access to consents schemas: consentFields: title: Consent Fields (v1.1.0) description: Common fields of the consent resource used to build other model schemas. x-apiture-version: 1.1.0 properties: document: description: Properties of the target document. allOf: - $ref: '#/components/schemas/document' type: description: Describe what kind of consent this is. This value must be one of the type names in the `/consentTypeNames` resource. type: string contextUri: description: >- The URI of a resource that establishes the context in which the financial institution asks for the user's consent. For example, for consent of an account's terms and conditions, the context might be the banking product for that account. type: string format: uri maxLength: 2048 secondaryContextUri: description: >- The URI of a secondary resource associated with this user's consent and the `contextUri`. For example, for consent of an account's terms and conditions, the secondary context might be the account. type: string format: uri maxLength: 2048 userId: description: The user ID of the user who is requested to consent to a document. This is the `_id` of the User resource. type: string type: object x-apiture-flattened: true document: title: Document (v1.0.0) description: Properties of a target document. required: - uri - contentType - revisedAt properties: uri: description: >- The URI of the target document that the user is consenting to. If the document is revised, this consent is marked as `stale`. (Note: This need not be a document in the Apiture vault.) type: string format: uri maxLength: 2048 contentType: description: >- The [media type](https://tools.ietf.org/html/rfc6838) for the document. For text documents, the content type should include the text encoding; if omitted, the encoding type is assumed to be utf-8. example: application/pdf revisionId: description: >- The revision identifier of the document revision the user consented to. If the content management system in which the document is stored does not define revision identifiers or tags, this may be omitted and defaults to the revision time stamp. type: string example: '2019:1.2.0' revisedAt: description: >- The time stamp when the target document was last revised (modified), in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format (`YYYY-MM-DDThh:mm:ss.sssZ`). type: string format: date-time x-apiture-version: 1.0.0 type: object x-apiture-flattened: true createConsent: title: Create Consent (v1.1.0) description: Representation used to create a new consent. required: - document - type - userId x-apiture-version: 1.1.0 example: _profile: 'https://api.apiture.com/schemas/consents/createConsent/v1.1.0/profile.json' document: uri: /vault/files/fd44d565-0086-4caf-8d9f-3b7681809251/content contentType: application/pdf revisionId: '2019:1.02.0' revisedAt: '2019-07-23T08:26:45.375Z' type: productTermsAndConditions userId: 5a5e834c-a7bd-401c contextUri: /products/products/34011fe5-192d-4ffb-be32-e7215e56028a x-apiture-composition: - $ref: '#/components/schemas/abstractResource' - $ref: '#/components/schemas/consentFields' 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' document: description: Properties of the target document. allOf: - $ref: '#/components/schemas/document' type: description: Describe what kind of consent this is. This value must be one of the type names in the `/consentTypeNames` resource. type: string contextUri: description: >- The URI of a resource that establishes the context in which the financial institution asks for the user's consent. For example, for consent of an account's terms and conditions, the context might be the banking product for that account. type: string format: uri maxLength: 2048 secondaryContextUri: description: >- The URI of a secondary resource associated with this user's consent and the `contextUri`. For example, for consent of an account's terms and conditions, the secondary context might be the account. type: string format: uri maxLength: 2048 userId: description: The user ID of the user who is requested to consent to a document. This is the `_id` of the User resource. type: string type: object x-apiture-flattened: true summaryConsent: title: Consent Summary (v1.1.0) description: >- Summary representation of a consent resource in consents 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. x-apiture-version: 1.1.0 example: _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'https://api.apiture.com/schemas/consents/summaryConsent/v1.1.0/profile.json' document: uri: /vault/files/fd44d565-0086-4caf-8d9f-3b7681809251/content contentType: application/pdf revisedAt: '2019-07-23T08:26:45.375Z' type: productTermsAndConditions userId: 5a5e834c-a7bd-401c state: pending contextUri: /products/products/34011fe5-192d-4ffb-be32-e7215e56028a _links: self: href: /consents/consents/0399abed-fd3d-4830-a88b-30f38b8a365c x-apiture-composition: - $ref: '#/components/schemas/abstractResource' - $ref: '#/components/schemas/consentFields' - properties: - _id - state - givenAt - requestRevokedAt - requestRescindedAt 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' document: description: Properties of the target document. allOf: - $ref: '#/components/schemas/document' type: description: Describe what kind of consent this is. This value must be one of the type names in the `/consentTypeNames` resource. type: string contextUri: description: >- The URI of a resource that establishes the context in which the financial institution asks for the user's consent. For example, for consent of an account's terms and conditions, the context might be the banking product for that account. type: string format: uri maxLength: 2048 secondaryContextUri: description: >- The URI of a secondary resource associated with this user's consent and the `contextUri`. For example, for consent of an account's terms and conditions, the secondary context might be the account. type: string format: uri maxLength: 2048 userId: description: The user ID of the user who is requested to consent to a document. This is the `_id` of the User resource. type: string _id: description: The unique identifier for this consent resource. This is an immutable opaque string. readOnly: true type: string state: description: The state of this consent. allOf: - $ref: '#/components/schemas/consentStates' readOnly: true givenAt: description: >- The time stamp when the user last consented to the document, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format (`YYYY-MM-DDThh:mm:ss.sssZ`). This property is not set if `state` is `pending`. type: string format: date-time readOnly: true requestRevokedAt: description: >- The time stamp when the user revoked consent, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format (`YYYY-MM-DDThh:mm:ss.sssZ`). A revoked consent reflects a consent request that the user has previously given but has reversed. Revoking a consent sets the `state` back to `pending` and clears `consentedAt`. type: string format: date-time readOnly: true requestRescindedAt: description: >- The time stamp when the consent _request_ was rescinded by the requester, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format (`YYYY-MM-DDThh:mm:ss.sssZ`). A rescinded consent reflects a consent request that the system or application has issued in the past but no longer requires. For example, if a user is removed as an authorized signer from an account and a consent is pending for that account's terms and conditions, the Accounts service may rescind that consent request. This property is set only if `state` is `rescinded`. type: string format: date-time readOnly: true type: object x-apiture-flattened: true consentStates: title: Consent States (v1.0.0) description: The state of a consent resource. type: string enum: - pending - given - stale - rescinded - revoked x-apiture-version: 1.0.0 x-apiture-flattened: true consent: title: Consent (v1.1.0) description: > Representation of a consent resource. Users consent or acceptance of a policy or other document. Response and request bodies using this consent schema may contain the following links:
RelSummaryMethod
selfFetch a representation of this consentGET
apiture:revokeRevoke a consentPOST
apiture:giveGive a consentPOST
x-apiture-version: 1.1.0 x-apiture-links: - rel: self operationId: getConsent - rel: 'apiture:revoke' operationId: revokeConsent - rel: 'apiture:give' operationId: giveConsent example: _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'https://api.apiture.com/schemas/consents/consent/v1.1.0/profile.json' document: uri: /vault/files/fd44d565-0086-4caf-8d9f-3b7681809251/content contentType: application/pdf revisionId: '2019:1.02.0' revisedAt: '2019-07-23T08:26:45.375Z' state: given givenAt: '2019-07-23T13:27:34.375Z' type: productTermsAndConditions userId: 5a5e834c-a7bd-401c contextUri: /products/products/34011fe5-192d-4ffb-be32-e7215e56028a _links: self: href: /consents/consents/0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:revoke': href: /consents/revokedConsents?consent=0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:rescind': href: /consents/rescindedConsents?consent=0399abed-fd3d-4830-a88b-30f38b8a365c x-apiture-composition: - $ref: '#/components/schemas/summaryConsent' 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' document: description: Properties of the target document. allOf: - $ref: '#/components/schemas/document' type: description: Describe what kind of consent this is. This value must be one of the type names in the `/consentTypeNames` resource. type: string contextUri: description: >- The URI of a resource that establishes the context in which the financial institution asks for the user's consent. For example, for consent of an account's terms and conditions, the context might be the banking product for that account. type: string format: uri maxLength: 2048 secondaryContextUri: description: >- The URI of a secondary resource associated with this user's consent and the `contextUri`. For example, for consent of an account's terms and conditions, the secondary context might be the account. type: string format: uri maxLength: 2048 userId: description: The user ID of the user who is requested to consent to a document. This is the `_id` of the User resource. type: string _id: description: The unique identifier for this consent resource. This is an immutable opaque string. readOnly: true type: string state: description: The state of this consent. allOf: - $ref: '#/components/schemas/consentStates' readOnly: true givenAt: description: >- The time stamp when the user last consented to the document, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format (`YYYY-MM-DDThh:mm:ss.sssZ`). This property is not set if `state` is `pending`. type: string format: date-time readOnly: true requestRevokedAt: description: >- The time stamp when the user revoked consent, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format (`YYYY-MM-DDThh:mm:ss.sssZ`). A revoked consent reflects a consent request that the user has previously given but has reversed. Revoking a consent sets the `state` back to `pending` and clears `consentedAt`. type: string format: date-time readOnly: true requestRescindedAt: description: >- The time stamp when the consent _request_ was rescinded by the requester, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format (`YYYY-MM-DDThh:mm:ss.sssZ`). A rescinded consent reflects a consent request that the system or application has issued in the past but no longer requires. For example, if a user is removed as an authorized signer from an account and a consent is pending for that account's terms and conditions, the Accounts service may rescind that consent request. This property is set only if `state` is `rescinded`. type: string format: date-time readOnly: true type: object x-apiture-flattened: true consents: title: Consent Collection (v1.1.0) description: > Collection of consents. The items in the collection are ordered in the `_embedded.items` array; the `name` is `consents`. The top-level `_links` object may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`). Response and request bodies using this consents schema may contain the following links:
RelSummaryMethod
selfThis filtered page of resultsGET
collectionThe raw collection without filters/sortingGET
nextFetch the next page of resultsGET
prevFetch the previous page of resultsGET
x-apiture-version: 1.1.0 x-apiture-links: - rel: self title: This filtered page of results operationId: getConsents - rel: collection title: The raw collection without filters/sorting operationId: getConsents - rel: next title: Fetch the next page of results operationId: getConsents - rel: prev title: Fetch the previous page of results operationId: getConsents example: _profile: 'https://api.apiture.com/schemas/consents/consents/v1.1.0/profile.json' start: 10 limit: 10 count: 67 name: consents _links: self: href: /consents/consents?start=10&limit=10 first: href: /consents/consents?start=0&limit=10 next: href: /consents/consents?start=20&limit=10 collection: href: /consents/consents _embedded: items: - _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'https://api.apiture.com/schemas/consents/consent/v1.0.0/profile.json' _links: self: href: /consents/consents/0399abed-fd3d-4830-a88b-30f38b8a365c - _id: d62c0701-0d74-4836-83f9-ebf3709442ea _profile: 'https://api.apiture.com/schemas/consents/consent/v1.0.0/profile.json' _links: self: href: /consents/consents/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 consent items. type: array items: $ref: '#/components/schemas/summaryConsent' _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 movedDocument: title: Moved Document (v1.0.0) description: Details about a target document that has been moved or revised. type: object x-apiture-version: 1.0.0 required: - uri - newUri - type example: _profile: 'https://api.apiture.com/schemas/consents/movedDocument/v1.0.0/profile.json' type: productTermsAndConditions contextUri: /products/products/34011fe5-192d-4ffb-be32-e7215e56028a uri: /vault/files/fd44d565-0086-4caf-8d9f-3b7681809251/content newUri: /vault/files/da66d490-2b72-4809-9b97-9b33039371f8/content x-apiture-composition: - $ref: '#/components/schemas/abstractResource' - properties: - uri - newUri - contextUri - type 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' uri: description: The original URI of the target document. type: string format: uri maxLength: 2048 newUri: description: >- The new URI of the target document. All matching consents' `document.uri` is updated updated to this new document URI, but their `state` is not changed. type: string format: uri maxLength: 2048 contextUri: description: >- The URI of a resource that establishes the context in which the financial institution asks for the user's consent. For example, for consent of an account's terms and conditions, the context might be the banking product for that account. type: string format: uri maxLength: 2048 type: description: Describe what kind of consent this is. This value must be one of the type names in the `/consentTypeNames` resource. type: string x-apiture-flattened: true revisedDocument: title: Revised Document (v1.0.1) description: Details about a target document that has been moved or revised. type: object x-apiture-version: 1.0.1 required: - uri - revisedAt - type example: _profile: 'https://api.apiture.com/schemas/consents/revisedDocument/v1.0.1/profile.json' uri: /vault/files/fd44d565-0086-4caf-8d9f-3b7681809251/content revisionId: '2019:1.2.0' contextUri: /products/products/34011fe5-192d-4ffb-be32-e7215e56028a revisedAt: '2019-10-05T10:30:00.000Z' type: productTermsAndConditions newUri: /vault/files/da66d490-2b72-4809-9b97-9b33039371f8/content x-apiture-composition: - $ref: '#/components/schemas/abstractResource' - $ref: '#/components/schemas/document' - properties: - newUri - contextUri - type 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' uri: description: >- The URI of the target document that the user is consenting to. If the document is revised, this consent is marked as `stale`. (Note: This need not be a document in the Apiture vault.) type: string format: uri maxLength: 2048 contentType: description: >- The [media type](https://tools.ietf.org/html/rfc6838) for the document. For text documents, the content type should include the text encoding; if omitted, the encoding type is assumed to be utf-8. example: application/pdf revisionId: description: >- The revision identifier of the document revision the user consented to. If the content management system in which the document is stored does not define revision identifiers or tags, this may be omitted and defaults to the revision time stamp. type: string example: '2019:1.2.0' revisedAt: description: >- The time stamp when the target document was last revised (modified), in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format (`YYYY-MM-DDThh:mm:ss.sssZ`). type: string format: date-time newUri: description: >- The URI of the revised target document, if the document has moved. All matching consents have their `document.uri` updated to this new document URI. type: string format: uri maxLength: 2048 contextUri: description: >- The URI of a resource that establishes the context in which the financial institution asks for the user's consent is requested for a specific document. For example, for consent of an account's terms and conditions, the context might be the banking product for that account. type: string format: uri maxLength: 2048 type: description: Describe what kind of consent this is. This value must be one of the type names in the `/consentTypeNames` resource. type: string x-apiture-flattened: true consentTypeNames: title: Consent Type Names (v1.0.1) description: A list of allowed consent type names and their labels and descriptions. x-apiture-version: 1.0.1 example: _profile: 'https://api.apiture.com/schemas/consents/consentTypeNames/v1.0.1/profile.json' names: productTermsAndConditions: - label: Product Terms and Conditions description: >- The terms and conditions of use for bank accounts of a specific banking product. The user must consent to these terms and conditions in order to open a new account. termsAndConditions: - label: Terms and Conditions description: The terms and conditions associated with a specific bank account. privacyPolicy: - label: Privacy Policy description: >- The financial institution's privacy policy, which covers how the financial institution guards the customer's personal information and how it shares information about customers. electronicConsent: - label: Electronic Consent Agreement description: >- Consenting to this agreement means the user agrees to receive electronically certain information such as statements or notices from the financial institution, and that the user agrees their use of the banking applications means they agree to allow those banking applications to perform banking operations, including transferring money or making payments, on their behalf. x-apiture-composition: - $ref: '#/components/schemas/abstractResource' - properties: - names 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' names: description: An object which maps consent type names to their labels and descriptions. allOf: - $ref: '#/components/schemas/localizedLabels' type: object x-apiture-flattened: true localizedLabels: title: Localized Labels (v1.0.0) description: >- An object that maps a name to an array of labels, descriptions and a language (locale) code for the label and description. The first item in the array should be the default label/description; the remaining items must have a `language`. additionalProperties: type: array items: $ref: '#/components/schemas/localizedLabel' x-apiture-version: 1.0.0 type: object properties: {} x-apiture-flattened: true localizedLabel: title: Localized Label (v1.0.0) description: A localized label and optional description for localizable content defined in this API. type: object properties: label: type: string description: A localized label or title which may be used to decorate UI controls which present a value. example: Limited Liability Corporation description: type: string description: A more detailed localized description of this label. language: type: string description: >- The natural language tag to which this localized label is associated, as per [RFC 7231](https://tools.ietf.org/html/rfc7231#section-3.1.3.1). If empty, this item serves as the _default_ label in case no label matches the caller's language. example: en-us code: type: string description: 'If the localized value is associated with an external standard, this is a lookup code or key or URI for that value.' example: '31' x-apiture-version: 1.0.0 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. This schema was resolved from [`common/root`](https://production.api.apiture.com/schemas/common/root/v2.0.0/model.json). 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 labelGroups: title: Label Groups (v1.0.1) description: >- A set of named groups of labels, each of which contains multiple item labels. The abbreviated example shows two groups, one named `structure` and one named `estimatedAnnualRevenue`. The first has items with names such as `corporation`, `llc` and `soleProprietorship`, with text labels for each in the default and in French. The second has items for estimated revenue *ranges* but no localized labels. For example, the item named `from1to10Million` has the `label` "$1M to $10M" and the range `[1000000.00,10000000.00)`. This schema was resolved from [`common/labelGroups`](https://production.api.apiture.com/schemas/common/labelGroups/v1.0.1/model.json). x-apiture-version: 1.0.1 example: _profile: 'https://api.apiture.com/schemas/common/labelGroups/v1.0.1/profile.json' groups: structure: unknown: label: Unknown code: '0' hidden: true corporation: label: Corporation code: '1' variants: fr: label: Soci\u00e9t\u00e9 partnership: label: Partnership code: '2' variants: fr: label: Partenariat llc: label: Limited Liability Company code: '2' variants: fr: label: Soci\u00e9t\u00e9 \u00e9 Responsabilit\u00e9 Limit\u00e9e nonProfit: label: Non Profit code: '4' variants: fr: label: Non Lucratif financialInstitution: label: Financial Institution code: '8' variants: fr: label: Institution financi\u00e8re soleProprietorship: label: Sole Proprietorship code: '11' variants: fr: label: Entreprise individuelle other: label: Other code: '254' variants: fr: label: Autre estimatedAnnualRevenue: unknown: label: Unknown code: '0' under1Million: label: Under $1M code: '1' range: '[0,1000000.00)' from1to10Million: label: $1M to $10M code: '2' range: '[1000000.00,10000000.00)' from10to100Million: label: $10M to $100M code: '3' range: '[10000000.00,100000000.00)' over100Million: label: 'Over $100,000,000.00' code: '4' range: '[100000000.00,]' other: label: Other code: '254' x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/labelGroups/v1.0.1/model.json' x-apiture-namespace: common x-apiture-composition: - $ref: '#/components/schemas/abstractResource' - properties: - groups 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' groups: description: 'Groups of localized labels. This maps *group names* → [*a group of labels*](#schema-labelgroup) within that group.' x-apiture-key: groupName additionalProperties: $ref: '#/components/schemas/labelGroup' 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. This schema was resolved from [`common/errorResponse`](https://production.api.apiture.com/schemas/common/errorResponse/v2.0.0/model.json). example: _profile: 'https://api.apiture.com/schemas/common/errorResponse/v2.0.0/profile.json' _error: _id: 2eae46e1-575c-4d69-8a8f-0a7b0115a4b3 message: The value for deposit must be greater than 0. statusCode: 422 type: positiveNumberRequired attributes: value: -125.5 remediation: Provide a value which is greater than 0 occurredAt: '2018-01-25T05:50:52.375Z' _links: describedby: href: 'https://api.apiture.com/errors/positiveNumberRequired' _embedded: errors: [] x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/errorResponse/v2.0.0/model.json' x-apiture-namespace: common x-apiture-composition: - $ref: '#/components/schemas/abstractResource' properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' allOf: - $ref: '#/components/schemas/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/components/schemas/error' type: object x-apiture-flattened: true abstractResource: x-apiture-version: 2.0.0 title: Abstract Resource (v2.0.0) description: >- An abstract schema used to define other schemas for request and response bodies. This is a [HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource representation. This model contains hypermedia `_links`, and either optional domain object data with `_profile` and optional `_embedded` objects, or an `_error` object. In responses, if the operation was successful, this object will not include the `_error`, but if the operation was a 4xx or 5xx error, this object will not include `_embedded` or any data fields, only `_error` and optionally `_links`. This schema was resolved from [`common/abstractResource`](https://production.api.apiture.com/schemas/common/abstractResource/v2.0.0/model.json). example: _profile: 'https://production.api.apiture.com/schemas/common/abstractResource/v2.0.0/profile.json' _links: self: href: 'https://api.devbank.apiture.com/applications/application/328f6bf6-d762-422f-a077-ab91ca4d0b6f' 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. This schema was resolved from [`common/collection`](https://production.api.apiture.com/schemas/common/collection/v2.0.0/model.json). 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 labelGroup: title: Label Group (v1.0.0) description: >- A map that defines labels for the items in a group. This is a map from each item *name* → *a [`labelItem`](#schema-labelitem) object*. For example, consider a JSON response that includes a property named `revenueEstimate`; the values for `revenueEstimate` must be one of the items in the group named `estimatedAnnualRevenue`, with options ranging `under1Million`, to `over100Million`. The item name is used as the selected value in an Apiture representation, such as `{ ..., "revenueEstimate" : "from10to100Million" , ...}`, and the item with the name `from10to100Million` defines the presentation labels for that item, as well as other metadata about that choice: this is the range `[10000000.00,100000000.00)`. This allows the client to let the user select a value from a list, such as the following derivde from the labels in the example: * Unknown * Under $1M * $1M to $10M * $10M to $100M * $100M or more Note that the `other` item is hidden from the selection list, as that item is marked as `hidden`. For items which define numeric ranges, a client may instead let the customer *directly* enter their estimated annual revenue as a number, such as 4,500,000.00. The client can then match that number to one of ranges in the items and set the `revenueEstimate` to the corresponding item's name: `{ ..., "revenueEstimate" : "from1to10Million", ... }`. This schema was resolved from [`common/labelGroup`](https://production.api.apiture.com/schemas/common/labelGroup/v1.0.0/model.json). x-apiture-key: labelName x-apiture-version: 1.0.0 additionalProperties: $ref: '#/components/schemas/labelItem' example: unknown: label: Unknown code: '0' hidden: true under1Million: label: Under $1M code: '1' range: '[0,1000000.00)' variants: fr: label: Moins de $1M from1to10Million: label: $1M to $10M code: '2' range: '[1000000.00,10000000.00)' variants: fr: label: $1M \u00e0 $10M from10to100Million: label: $10M to $100M code: '3' range: '[10000000.00,100000000.00)' variants: fr: - label $10M \u00e0 $100M over100Million: label: 'Over $100,000,000.00' code: '4' range: '[100000000.00,]' variants: fr: label: Plus de $10M other: label: Other code: 254 x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/labelGroup/v1.0.0/model.json' x-apiture-namespace: common type: object properties: {} 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`. This schema was resolved from [`common/abstractRequest`](https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/model.json). 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: 'https://api.apiture.com/schemas/common/abstractRequest/v2.0.0/profile.json' _links: self: href: 'https://api.devbank.apiture.com/applications/' 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 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. This schema was resolved from [`common/error`](https://production.api.apiture.com/schemas/common/error/v2.0.0/model.json). 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 labelItem: title: Label Item (v1.0.0) description: >- An item in a [`labelGroup`](#schema-labelgroup), with a set of `variants` which contains different localized labels for the item. Each ([`simpleLabel`](#schema-simpleLabel)) variant defines the presentation text label and optional description for a language. Items may also have a lookup `code` to map to external syststems, a numeric range, and a `hidden` boolean to indicate the item is normally hidden in the UI. This schema was resolved from [`common/labelItem`](https://production.api.apiture.com/schemas/common/labelItem/v1.0.0/model.json). x-apiture-version: 1.0.0 example: over100Million: label: 'Over $100,000,000.00' code: '4' range: '[100000000.00,]' variants: fr: label: Plus de $10M x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/labelItem/v1.0.0/model.json' x-apiture-namespace: common x-apiture-composition: - $ref: '#/components/schemas/simpleLabel' - properties: - variants - code - hidden - range properties: label: type: string description: A label or title which may be used as labels or other UI controls which present a value. example: Board of Directors description: type: string description: A more detailed localized description of a localizable label. variants: description: >- The language-specific variants of this label. 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/simpleLabel' example: en: label: More then $10M es: label: Mas de $10M fr: label: Plus de $10M code: type: string description: 'If the localized value is associated with an external standard or definition, this is a lookup code or key or URI for that value.' example: '3' minLength: 1 hidden: type: boolean description: 'If `true`, this item is normally hidden from the User Interface.' range: description: >- The range of values, if the item describes a bounded numeric value. This is range notation such as `[min,max]`, `(exclusiveMin,max]`, `[min,exclusiveMax)`, or `(exclusiveMin,exclusiveMax)`. For example, `[0,100)` is the range greater than or equal to 0 and less than 100. If the *min* or *max* value are omitted, that end of the range is unbounded. For example, `(,1000.00)` means less than 1000.00 and `[20000.00,]` means 20000.00 or more. The ranges do not overlap or have gaps. type: string pattern: '^[\[\(](-?(0|[1-9][0-9]*)(\.[0-9]+)?)?,(-?(0|[1-9][0-9]*)(\.[0-9]+)?)?[\]\)]$' 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. This schema was resolved from [`common/links`](https://production.api.apiture.com/schemas/common/links/v1.0.0/model.json). type: object x-apiture-key: linkRelationName additionalProperties: $ref: '#/components/schemas/link' x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/links/v1.0.0/model.json' x-apiture-namespace: common properties: {} x-apiture-flattened: true attributes: x-apiture-version: 2.0.0 title: Attributes (v2.0.0) description: |- An optional map of name/value pairs which contains additional dynamic data about the resource. This schema was resolved from [`common/attributes`](https://production.api.apiture.com/schemas/common/attributes/v2.0.0/model.json). 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 simpleLabel: title: Simple Label (v1.0.0) description: |- A text label and optional description. This schema was resolved from [`common/simpleLabel`](https://production.api.apiture.com/schemas/common/simpleLabel/v1.0.0/model.json). x-apiture-version: 1.0.0 type: object required: - label properties: label: type: string description: A label or title which may be used as labels or other UI controls which present a value. example: Board of Directors description: type: string description: A more detailed localized description of a localizable label. x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/simpleLabel/v1.0.0/model.json' x-apiture-namespace: common 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. This schema was resolved from [`common/link`](https://production.api.apiture.com/schemas/common/link/v1.0.0/model.json). 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: 'https://api.devbank.apiture.com/applications/application/328f6bf6-d762-422f-a077-ab91ca4d0b6f' title: Application x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/link/v1.0.0/model.json' x-apiture-namespace: common type: object x-apiture-flattened: true attributeValue: x-apiture-version: 2.0.0 title: Attribute Value (v2.0.0) description: |- The data associated with this attribute. This schema was resolved from [`common/attributeValue`](https://production.api.apiture.com/schemas/common/attributeValue/v2.0.0/model.json). 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 x-apiture-annotated-at: '2020-10-23T17:08:40.419Z'