openapi: 3.0.0
servers:
- url: 'https://api.devbank.apiture.com/consents'
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 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.
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 (`POST /consents`) 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 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 for a user with
the `GET /neededConsents` operation.
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}`)
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`
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`.
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.
## 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.
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` |
## 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.
version: 0.7.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: Consent
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:
- Consent
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.
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.
operationId: createConsent
tags:
- Consent
responses:
'200':
description: OK. A new consent was created.
headers:
Location:
description: >-
The URI of the 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 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
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
'/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:
- Consent
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:
- Consent
security:
- apiKey: []
accessToken:
- profile/write
parameters:
- $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 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'
requestBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/consent'
application/json:
schema:
$ref: '#/components/schemas/consent'
required: true
/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:
- Consent
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
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'
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
/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
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'
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
/givenConsents:
post:
operationId: giveConsent
summary: Give a consent
description: >-
Indicate that a user has given consent to a document. This marks the 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, context, and user. 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, or when an account application expires. changes the `state` property of the matching consents to
`rescinded`. The client must pass the `type`, `context`, and `user` in order to find matching consents; if the `document` is also specified,
it must also match.
The response is the collection of updated 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.
required: true
schema:
type: string
format: uri
- name: user
in: query
description: Rescind all matching consents for the user with this user ID.
required: true
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'
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'
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'
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
/:
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:
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
- 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
x-apiture-annotated-at: '2020-08-12T16:17:11.307Z'
components:
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.
Links
Response and request bodies using this consent
schema may contain
the following links:
x-apiture-version: 1.1.0
x-apiture-links:
- rel: self
operationId: getConsent
- rel: 'apiture:rescind'
operationId: rescindConsents
- 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`).
Links
Response and request bodies using this consents
schema may contain
the following links:
Rel | Summary | Method |
self | This filtered page of results | GET |
collection | The raw collection without
filters/sorting | GET |
next | Fetch the next page of results | GET |
prev | Fetch the previous page of results | GET |
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:
anyOf:
- _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. 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 set of names of allowed consent types, with 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
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: '{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.
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
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: '{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
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
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
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
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
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: /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
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'
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
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: /auth/oauth2/authorize
tokenUrl: /auth/oauth2/token
scopes:
banking/read: Read access to consents
banking/write: Write (update) access to consents
banking/full: Full access to consents