swagger: '2.0' info: title: Accounts description: >- The Accounts API manages banking accounts for bank customers. Accounts are instances of a banking _product_ (see the Products API). The product defines the type, rate, terms, attributes, and capabilities of accounts attached to the product. Accounts may be either _personal_ accounts or _organization_ accounts (accounts for businesses, institutions, non-profits, etc.) A user can list their existing accounts and see the balances of those accounts (based on entitlements) and may have permission to change the acount name and label and description. Each account has a _primary user_, which is a bank user (via the Users service). The primary user has full management and entitlements for the account, receives mailings such as statements or tax documents. For retail (personal) accounts, the primary user is the account owner. Other users may be authorized to perform actions on the account, such as list balances, debits, or credits. Because the account number is sensitive data, it is not included by default in account representations. The masked account number is returned in the `accountNumbers` object. To also receive the full account number when fetching an account, include the `?unmasked=true` option. When linking an external account, the full account number should be in the `accountNumbers.full` property in the request. The `accountNumbers.full` property is included with the 201 response of creating an account. version: 0.5.0 contact: name: Apiture url: 'https://developer.aptiture.com' email: api@apiture.com termsOfService: 'TODO: Terms of Service is TBD; need input from Legal team.' schemes: - https basePath: /accounts consumes: - application/hal+json - application/json produces: - application/hal+json - application/json tags: - name: API description: The Accounts API - name: Account description: Bank Accounts - name: External Account description: External Bank Accounts paths: /externalAccounts: get: summary: Return a collection of external accounts description: >- Return a[ paginated](http://docs.apiture.com/docs/concepts#pagination)[ sortable](http://docs.apiture.com/docs/concepts#sorting)[ filterable](http://docs.apiture.com/docs/concepts#filtering)[ searchable](http://docs.apiture.com/docs/concepts#searchable) collection of external accounts. The [links](http://docs.apiture.com/docs/concepts#links) in the response include pagination links. operationId: getExternalAccounts x-apiture-implemented: true tags: - External Account parameters: - name: start in: query description: >- The zero-based index of the first external account item to include in this page. The default 0 denotes the beginning of the collection. type: integer format: int64 default: 0 - name: limit in: query description: >- The maximum number of external account representations to return in this page. type: integer format: int32 default: 100 - name: sortBy in: query type: string description: >- Optional sort criteria. See [sort criteria format](http://docs.apiture.com/docs/concepts#sorting), such as `?sortBy=field1,-field2`. - $ref: '#/parameters/filterQueryParam' - $ref: '#/parameters/qQueryParam' responses: '200': description: OK schema: $ref: '#/definitions/externalAccounts' '400': $ref: '#/responses/400' '422': $ref: '#/responses/422' post: summary: Create a new external account description: Create a new external account. A successful operation returns the full accountNumber. operationId: createExternalAccount x-apiture-implemented: true tags: - External Account parameters: - name: externalAccount in: body description: The data necessary to create a new external account. required: true schema: $ref: '#/definitions/createExternalAccount' responses: '201': description: Created schema: $ref: '#/definitions/externalAccount' 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` type: string format: uri ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update the resource. type: string '400': $ref: '#/responses/400' '409': description: >- Conflict. An external account with the key account details already exists for the user, such as an attempt to change the state from `active` to `pending`, or to change the name to a name that is already in use by another external account that the user or organization holds. schema: $ref: '#/definitions/errorResponse' x-apiture-errors: - invalidAccountState '/externalAccounts/{externalAccountId}': get: summary: Fetch a representation of this external account description: >- Return a [HAL](http://docs.apiture.com/docs/concepts#hal) representation of this external account resource. operationId: getExternalAccount x-apiture-implemented: true tags: - External Account parameters: - $ref: '#/parameters/externalAccountIdPathParam' - $ref: '#/parameters/ifNoneMatchHeaderParam' - $ref: '#/parameters/unmaskedQueryParam' responses: '200': description: OK schema: $ref: '#/definitions/externalAccount' headers: ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this external account resource. type: string '304': $ref: '#/responses/304' '404': $ref: '#/responses/404ExternalAccount' patch: summary: Update this external account description: >- Perform a partial update of this external account. Fields which are omitted from the request are not updated. Nested `_embedded` and `_links` are ignored if included. Bank users may only update the `routingNumber` and `accountNumbers.full` and `institutionName` and `type` if the external account is still `pending`. If `accountNumbers.full` is patched, then the full account number is included in the response. This operation does not change the `state` property. To change the `state` of the account, use the `POST` operations `activateAccount`, `deactivateAccount`, `freezeAccount`, `closeAccount`, `removeAccount`, which are available in the `_links` on an account instance. operationId: patchExternalAccount x-apiture-implemented: true tags: - External Account parameters: - $ref: '#/parameters/externalAccountIdPathParam' - name: externalAccount in: body required: true schema: $ref: '#/definitions/updateExternalAccount' - $ref: '#/parameters/ifMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/externalAccount' headers: ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this external account resource. type: string '400': description: >- Bad Request. The request body or one or more of the query parameters was not well formed. The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' x-apiture-errors: - malformedRequestBody - malformedAccountUri - cannotPatchState '404': $ref: '#/responses/404ExternalAccount' '409': description: >- Conflict. the request attempted to change the state in an incompatible way, such as an attempt to change the state from `active` to `pending` or to change the name to a name that is already in use by another external account that the user or organization holds. x-apiture-errors: - invalidAccountState '412': $ref: '#/responses/412' '422': $ref: '#/responses/422' '428': $ref: '#/responses/428' delete: summary: Delete this external account resource description: >- Delete this external account resource and any resources that are owned by it. Note that only `pending` accounts may be deleted. Once an account has been activated, it cannot be deleted, only inactiviated or removed from use. operationId: deleteExternalAccount x-apiture-implemented: true tags: - External Account parameters: - $ref: '#/parameters/externalAccountIdPathParam' responses: '204': $ref: '#/responses/204Deleted' '404': $ref: '#/responses/404ExternalAccount' '409': description: >- Conflict. the request attempted to change the state in an incompatible way, such as an attempt to change the state from `active` to `pending` or to change the name to a name that is already in use by another external account that the user or organization holds. x-apiture-errors: - invalidAccountState /accounts: get: summary: Return a collection of accounts description: >- Return a[ paginated](http://docs.apiture.com/docs/concepts#pagination)[ sortable](http://docs.apiture.com/docs/concepts#sorting)[ filterable](http://docs.apiture.com/docs/concepts#filtering)[ searchable](http://docs.apiture.com/docs/concepts#searchable) collection of accounts. The [links](http://docs.apiture.com/docs/concepts#links) in the response include pagination links. operationId: getAccounts x-apiture-implemented: true tags: - Account parameters: - name: start in: query description: >- The zero-based index of the first account item to include in this page. The default 0 denotes the beginning of the collection. type: integer format: int64 default: 0 - name: limit in: query description: >- The maximum number of account representations to return in this page. type: integer format: int32 default: 100 - name: sortBy in: query type: string description: >- Optional sort criteria. See [sort criteria format](http://docs.apiture.com/docs/concepts#sorting), such as `?sortBy=field1,-field2`. - $ref: '#/parameters/filterQueryParam' - $ref: '#/parameters/qQueryParam' responses: '200': description: OK schema: $ref: '#/definitions/accounts' '400': $ref: '#/responses/400' '422': $ref: '#/responses/422' post: summary: Create a new account. description: >- Create a new banking account. The request body must contain a link to an appoved account application which has not been used yet. The application also refers to a specific banking product with a type and subtype; the new account will adopt the terms and attributes of that banking product. IF a name is not included in the request, the product name will be used to provide a unique name for this user. The account will be created in the `pending` state (which allows deletion of the account). A successful operation returns the full account number. operationId: createAccount x-apiture-implemented: true tags: - Account parameters: - name: account in: body description: The data necessary to create a new account. required: true schema: $ref: '#/definitions/createAccount' responses: '201': description: Created schema: $ref: '#/definitions/accountNumbers' 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` type: string format: uri ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update the resource. type: string '400': description: >- Bad Request. The request body or one or more of the query parameters was not well formed. The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' x-apiture-errors: - malformedRequestBody - malformedAccountUri - productUriNotSupplied - contactUriNotSupplied '/accounts/{accountId}': get: summary: Fetch a representation of this account description: >- Return a [HAL](http://docs.apiture.com/docs/concepts#hal) representation of this account resource. operationId: getAccount x-apiture-implemented: true tags: - Account parameters: - $ref: '#/parameters/accountIdPathParam' - $ref: '#/parameters/ifNoneMatchHeaderParam' - $ref: '#/parameters/unmaskedQueryParam' responses: '200': description: OK schema: $ref: '#/definitions/account' headers: ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this account resource. type: string '304': $ref: '#/responses/304' '404': $ref: '#/responses/404Account' patch: summary: Update this account description: >- Perform a partial updates of this account. Fields which are omitted from the request are not updated. Nested `_embedded` objects are ignored if included. This operation does not change the `state` property. To change the `state` of the account, use the `POST` operations `activateAccount`, `deactivateAccount`, `freezeAccount`, `closeAccount`, `removeAccount`, which are available in the `_links` on an account instance. operationId: patchAccount x-apiture-implemented: true tags: - Account parameters: - $ref: '#/parameters/accountIdPathParam' - name: account in: body required: true schema: $ref: '#/definitions/updateAccount' - $ref: '#/parameters/ifMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/account' headers: ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this account resource. type: string '400': $ref: '#/responses/400' '404': $ref: '#/responses/404Account' '409': description: >- Conflict. the request attempted to change the state in an incompatible way, such as an attempt to change the state from `active` to `pending` or to change the name to a name that is already in use by another external account that the user or organization holds. x-apiture-errors: - invalidAccountState '412': $ref: '#/responses/412' '422': $ref: '#/responses/422' '428': $ref: '#/responses/428' delete: summary: Delete this account resource description: >- Delete this account resource and any resources that are owned by it. Note that only `pending` accounts may be deleted. Once an account has been activated, it cannot be deleted, only inactiviated or closed. operationId: deleteAccount x-apiture-implemented: true tags: - Account parameters: - $ref: '#/parameters/accountIdPathParam' responses: '204': $ref: '#/responses/204Deleted' '409': description: >- Conflict. the request attempted to change the state in an incompatible way, such as an attempt to change the state from `active` to `pending` or to change the name to a name that is already in use by another external account that the user or organization holds. x-apiture-errors: - invalidAccountState /: get: summary: Top-level resources and operations in this API description: >- Return links to the top-level resources and operations in this API. This API returns the following links: * **`apiture:accounts`** : links to the collection of accounts held at this financial institution. * **`apiture:externalAccounts`** : links to the collection of external accounts held at other financial institutions. operationId: getApi x-apiture-implemented: true responses: '200': description: OK schema: $ref: '#/definitions/root' examples: application/hal+json: id: accounts name: User Bank Accounts apiVersion: 0.3.0 _profile: 'https://api.apiture.com/schemas/apiRoot/v.0.1.0/profile.json' _links: 'apiture:accounts': href: /accounts/accounts 'apiture:externalProducts': href: /accounts/externalAccounts tags: - API /apiDoc: get: summary: Return API definition document description: Return the OpenAPI document that describes this API. operationId: getApiDoc x-apiture-implemented: true produces: - application/json - application/openapi+json;version=2.0 - application/openapi+yaml;version=2.0 responses: '200': description: OK schema: type: object tags: - API /activeAccounts: post: summary: Activate an account description: >- Activate an account that is eligible to be activated. Only accounts which are `pending` or `inactive` or `frozen` may be activated. This operation is invoked from the `apiture:activate` link on an account, which only exists if the action is allowed. This changes the `state` to `active`. operationId: activateAccount tags: - Account parameters: - $ref: '#/parameters/accountQueryParam' - $ref: '#/parameters/ifMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/account' '400': $ref: '#/responses/400AccountUri' '409': $ref: '#/responses/409AccountConflict' '422': $ref: '#/responses/422' '428': $ref: '#/responses/428' /inactiveAccounts: post: summary: Deactivate an account description: >- Deactivate an account that is eligible to be deactivated. Only accounts which are `pending` or `active` may be deactivated. This operation is invoked from the `apiture:deactivate` link on an account; the link only exists if the action is allowed. This changes the `state` to `inactive`. operationId: deactivateAccount tags: - Account parameters: - $ref: '#/parameters/accountQueryParam' - $ref: '#/parameters/ifMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/account' '400': $ref: '#/responses/400AccountUri' '409': $ref: '#/responses/409AccountConflict' '422': $ref: '#/responses/422' '428': $ref: '#/responses/428' /frozenAccounts: post: summary: Freeze an account description: >- Freze an account that is eligible to be frozen. Only accounts which are `active` or `inactive` may be frozen. This operation is invoked from the `apiture:freeze` link on an account; the link only exists if the action is allowed. This changes the `state` to `frozen`. operationId: freezeAccount tags: - Account parameters: - $ref: '#/parameters/accountQueryParam' - $ref: '#/parameters/ifMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/account' '400': $ref: '#/responses/400AccountUri' '409': $ref: '#/responses/409AccountConflict' '422': $ref: '#/responses/422' '428': $ref: '#/responses/428' /closedAccounts: post: summary: Close an account tags: - Account description: >- Close an account that is eligible to be closed. Only accounts which are `active` or `inactive` or `frozen` may be closed. This operation is invoked from the `apiture:close` link on an account; the link only exists if the action is allowed. This changes the `state` to `closed`. Closing an account will append the text "` (Closed YYYY-MM-DDThh:mm:ssZ)`" to the name, so that the previous name may be used for other accounts. operationId: closeAccount parameters: - $ref: '#/parameters/accountQueryParam' - $ref: '#/parameters/ifMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/account' '400': $ref: '#/responses/400AccountUri' '409': $ref: '#/responses/409AccountConflict' '422': $ref: '#/responses/422' '428': $ref: '#/responses/428' parameters: filterQueryParam: name: filter in: query description: >- Optional filter criteria. See [filtering](http://docs.apiture.com/docs/concepts#filtering). type: string qQueryParam: name: q in: query description: >- Optional search string. See [searching](http://docs.apiture.com/docs/concepts#text-searching). type: string externalAccountIdPathParam: name: externalAccountId description: The unique identifier of this external account. This is an opaque string. in: path type: string required: true accountIdPathParam: name: accountId description: The unique identifier of this account. This is an opaque string. in: path type: string required: true accountQueryParam: name: account description: >- A server-supplied value which identifies the account instance. type: string in: query required: true 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 type: string ifNoneMatchHeaderParam: name: If-None-Match description: >- The entity tag that was returned in the `ETag` response. If the resource's current entity tag matches, the `GET` will return 304 (Not Modified) and no response body, else the resource representation will be returned. in: header type: string unmaskedQueryParam: name: unmasked description: >- When requesting an account, the full account number is not included in the response by default, for security reasons. Include this query parameter, with a value of `true`, to request that the response body includes the full account number. Such requests are auditable. type: boolean in: query required: false default: false responses: '304': description: >- Not Modified. The resource has not been modified since it was last fetched. '400': description: >- Bad Request. The request body or one or more of the query parameters was not well formed. The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' x-apiture-errors: - malformedRequestBody - malformedAccountUri '400AccountUri': description: >- Bad Request. The `account` or `accountUri` parameter was malformed or does not refer to an account. schema: $ref: '#/definitions/errorResponse' x-apiture-errors: - malformedAccountUri '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. schema: $ref: '#/definitions/errorResponse' '422': description: >- Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' '428': description: >- Precondition Required. The request did not include the required `if-Match` header. Resubmit with the operation, supplying the value of the `ETag` and the most recent state of the resource. schema: $ref: '#/definitions/errorResponse' 404ExternalAccount: description: >- Not Found. There is no such external account resource at the specified `{externalAccountId}` The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' x-apiture-errors: - invalidAccountId - invalidUnmaskedQueryParam 404Account: description: >- Not Found. There is no such account resource at the specified `{accountId}` The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' x-apiture-errors: - invalidAccountId - invalidUnmaskedQueryParam 204Deleted: description: No Content. The resource was deleted successfully. 409AccountConflict: description: >- Conflict. The request to change the state of the account is not allowed. For example, one cannot change the state of a `closed` account, or change a non-`pending` account to `pending`. The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' definitions: accountNumbers: title: Account Numbers description: Different representations of an account number. properties: masked: description: >- A partial account number that does not contain all the digits of the full account number. This masked number appears in statements or in user experience presentation. It is sufficient for a user to differentiate this account from other accounts they hold, but is not sufficient for initiating transfers, etc. The first character is the mask character and is repeated; this does not indicate that the full account number is the same as the mask length. This value is derived and immutable.

**TODO** Move this model schema to common-fin-models where it can be used in accountverifications and payments APIs type: string minLength: 9 maxLength: 32 readOnly: true example: '*************3210' full: description: >- The full account number. This value only appears when `?unmasked=true` is passed on the `GET` request. Not included in the summary representation of the account that is included in account collection responses. type: string minLength: 9 maxLength: 32 example: '9876543210' summaryExternalAccountFields: title: Fields in External Account Sumamry Representations description: >- Fields of the representation of an external account summary resource. properties: name: description: The user-assigned name of this external account type: string maxLength: 128 example: 3rdParty Bank checking description: description: The user-assigned description of this external account. type: string maxLength: 4096 example: My primary checking account at 3rdParty Bank institutionName: description: 'The name of the financial institution. TODO: is 128 sufficient?' type: string minLength: 2 maxLength: 128 example: 3rd Party Bank primaryUserName: description: >- The primary user or owner of the external account. **Note**: This can't be passed via a link to a user or contact, as this identity need not exist in our Users service. **TODO**: Should this be an object with title, first/middle/last name, suffix? (Can we reuse a Name model from User resource, Contact resource?) **TODO**: is 128 sufficient? type: string maxLength: 128 example: Lucille Wellphunded title: description: >- The name of the account holder. This is derived from the contact resource. type: string maxLength: 512 example: John Smith accountTitle: description: >- The name of the account holder. This is derived from the contact resource. **Note**: This property is deprecated. Use `title` instead. This property will be removed in the next release of this service. type: string maxLength: 512 example: John Smith type: description: >- The type of account. This is the name of an external product type associated with this external account. (The product type is defined in the Products API.) type: string routingNumber: description: >- The account routing number which identifies the financial institution. The full routing number and full account number are required to fully identify the account. type: string minLength: 9 maxLength: 32 example: '021000021' state: description: >- The state of the external account. This field is immutable and derived. * **`pending`** : A new external account that has not been verified * **`verifying`** : A new account that is being verified. This state only applies to _external_ accounts. * **`failed`** : A external account which has failed account verification. * **`active`** : An account which is active and available for use and for making new transactions. * **`inactive`** : An account which is marked inactive and not available for new transactions. Inactive accounts may be changed back to active. * **`frozen`** : An account which is frozen and not eligible for new transactions. This is typically the result of suspicious activity or fraud detection. The user must contact their financial institution to unfreeze the account (by changing the state back to `active`) or the financial institution may opt to close the account. * **`closed`** : An account that is closed and removed from use Closed accounts are not eligble for transactions or to become active. Such accounts are retained for historical purposes because some transactions may refer to it. Users do not see closed accounts when they view their acocunts. To change the state of an account, `POST` the account URI to the corresponding resource endpoints, using the corresponding link on the account resource. To activate an account, use the `apiture:activate` link to `POST` to `/accounts/activeAccounts`. To deactivate an account, use the `apiture:deactivate` link to `POST` to `/accounts/inactiveAccounts`. To freeze an account, use the `apiture:freeze` link to `POST` to `/accounts/frozenAccounts`. To close an account, use the `apiture:close` link to `POST` to `/accounts/closedAccounts`. type: string enum: - pending - verifying - failed - active - inactive - frozen - closed example: active externalAccountFields: title: Fields in External Account Representations description: >- Fields of an external account resource. allOf: - $ref: '#/definitions/summaryExternalAccountFields' - type: object properties: accountNumbers: allOf: - $ref: '#/definitions/externalAccountNumbers' externalAccountNumbers: title: External Account Numbers description: >- The account numbers necessary to link an external account. type: object properties: masked: description: >- A partial account number that does not contain all the digits of the full account number. This masked number appears in statements or in user experience presentation. It is sufficient for a user to differentiate this account from other accounts they hold, but is not sufficient for initiating transfers, etc. The first character is the mask character and is repeated; this does not indicate that the full account number is the same as the mask length. This value is included when accounts are embedded in collections or other resources. This value is derived and immutable.

**TODO** Move this model schema to common-fin-models where it can be used in other APIs type: string minLength: 9 maxLength: 32 example: '*************3210' readOnly: true full: description: >- The full account number. This value only appears when `?unmasked=true` is passed on the `GET` request for an account. Not included in the summary representation of the account that is included in account collection responses. Pass in this value when linking an external account. This field can be updated whenever the account is still in the pending state. type: string minLength: 9 maxLength: 32 example: '9876543210' createExternalAccountNumbers: title: Create External Account Numbers description: >- The account numbers necessary to link an external account. type: object required: - full properties: full: description: >- The full account number. Pass in this value when linking an external account. This field can be updated whenever the account is still in the pending state. type: string minLength: 9 maxLength: 32 example: '9876543210' summaryExternalAccount: title: External Account Summary description: >- Summary representation of an external account resource in external accounts 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. allOf: - $ref: '#/definitions/abstractResource' - $ref: '#/definitions/summaryExternalAccountFields' - type: object properties: _id: description: >- The unique identifier for this external account resource. This is an immutable opaque string. type: string verifiedAt: description: >- The date-time when the external account was most recently verified. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) format, UTC. type: string format: date-time example: '2018-01-20T18:13:33.375Z' createdAt: description: >- The date-time when the external account was created. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339)format, UTC. This is derived and immutable. type: string format: date-time example: '2018-01-20T05:54:52.375Z' accountNumbers: allOf: - $ref: '#/definitions/externalAccountNumbers' attributes: $ref: '#/definitions/attributes' example: _id: '0399abed-fd3d-4830-a88b-30f38b8a365c' _profile: 'https://api.apiture.com/schemas/externalAccount/v1.0.0/profile.json' _links: self: href: /accounts/externalAccounts/0399abed-fd3d-4830-a88b-30f38b8a365c name: My account at 3rdParty Bank type: savings state: active verifiedAt: '2018-01-20T18:13:33.375Z' createdAt: '2018-01-20T05:54:52.375Z' routingNumber: '021000021' accountNumbers: masked: '*********3210' institutionName: '3rd Party Bank' primaryUserName: Lana Michaels createExternalAccount: title: Create External Account description: >- Representation used to create a new external account. The request should include a *`apiture:productType`* link to a product type. TODO: We need an attribute in the Products API to identify the type is for an external account. allOf: - $ref: '#/definitions/summaryExternalAccountFields' - $ref: '#/definitions/abstractResource' - type: object properties: accountNumbers: allOf: - $ref: '#/definitions/createExternalAccountNumbers' required: - name - type - accountNumbers - routingNumber - institutionName example: _profile: 'https://api.apiture.com/schemas/externalAccount/v1.0.0/profile.json' name: My account at 3rdParty Bank institutionName: '3rd Party Bank' primaryUserName: Lana Michaels type: savings routingNumber: '021000021' accountNumbers: full: '9876543210' _links: 'apiture:contact': href: /contacts/contacts/00007276-8b25-4e97-ac82-e1e17a2ff7c2 'apiture:productType': href: /products/productTypes/a93c19ba-f96d-4b30-8dd7-92b2d6ffcb0b updateExternalAccount: title: Update External Account description: >- Representation used to update or patch an external account. allOf: - $ref: '#/definitions/summaryExternalAccount' - $ref: '#/definitions/externalAccountFields' - type: object properties: accountNumbers: description: >- Different representations of the account number. allOf: - $ref: '#/definitions/externalAccountNumbers' example: _id: '0399abed-fd3d-4830-a88b-30f38b8a365c' _profile: 'https://api.apiture.com/schemas/externalAccount/v1.0.0/profile.json' name: My primary savings account at 3rdParty Bank type: savings state: active routingNumber: '021000021' institutionName: '3rd Party Bank' primaryUserName: Lana Michaels externalAccount: title: External Account description: >- Representation of an external account resource, a banking account held by another financial institution. The `_links` on an external account may include the following, depending on the state of the account: *`self`* - The link to the external account. *`apiture:productType`* - The link to the external account's product type. *`apiture:activate`* - Activate the account (POST) *`apiture:deactivate`* - Deactivate the account (POST) *`apiture:freeze`* - Freeze the account (POST) *`apiture:close`* - Close the account (POST) allOf: - $ref: '#/definitions/updateExternalAccount' example: _id: '0399abed-fd3d-4830-a88b-30f38b8a365c' _profile: 'https://api.apiture.com/schemas/externalAccount/v1.0.0/profile.json' _links: self: href: /accounts/externalAccounts/0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:productType': href: /products/productTypes/0a8a1349-d652-4d5e-accc-047ec815d78a title: Premier Personal Savings profile: 'https://api.apiture.com/schemas/product/v1.0.0/profile.json' 'apiture:deactivate': href: /accounts/inactiveAccounts?account=0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:freeze': href: /accounts/frozenAccounts?account=0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:close': href: /accounts/closedAccounts?account=0399abed-fd3d-4830-a88b-30f38b8a365c _embedded: productType: _id: '0a8a1349-d652-4d5e-accc-047ec815d78a' _profile: 'https://api.apiture.com/schemas/productType/v1.0.0/profile.json' name: savings label: Personal Savings name: My account at 3rdParty Bank type: savings state: active primaryUserName: Lucille Wellphunded verifiedAt: '2018-01-20T18:13:33.375Z' createdAt: '2018-01-20T05:54:52.375Z' institutionName: 3rdParty Bank routingNumber: '021000021' accountNumbers: masked: '*************3210' externalAccounts: title: External Account Collection description: >- Collection of external accounts. The items in the collection are ordered in the `_embedded` object with name `items`. The top-level `_links` object may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`.) allOf: - $ref: '#/definitions/collection' - type: object properties: _embedded: type: object properties: items: description: An array containing a page of external account items. type: array items: $ref: '#/definitions/summaryExternalAccount' example: _profile: 'https://api.apiture.com/schemas/collection/externalAccount/v1.0.0/profile.json' start: 10 limit: 10 count: 67 name: external accounts _links: self: href: /accounts/externalAccounts?start=10&limit=10 first: href: /accounts/externalAccounts?start=0&limit=10 next: href: /accounts/externalAccounts?start=20&limit=10 collection: href: /accounts/externalAccounts _embedded: items: - _id: '0399abed-fd3d-4830-a88b-30f38b8a365c' name: My account at 3rdParty Bank _profile: >- https://api.apiture.com/schemas/externalAccount/v1.0.0/profile.json type: savings state: active primaryUserName: Lucille Wellphunded institutionName: 3rdParty Bank verifiedAt: '2018-01-20T18:13:33.375Z' createdAt: '2018-01-20T05:54:52.375Z' routingNumber: '021000021' accountNumbers: masked: '*************3210' _links: self: href: >- /accounts/externalAccounts/0399abed-fd3d-4830-a88b-30f38b8a365c accountFields: title: Account Fields description: Fields of the account representations. properties: name: description: The user-assigned name of this account. type: string maxLength: 128 minLength: 1 description: description: The user-assigned description of this account. type: string maxLength: 4096 minLength: 1 summaryAccount: title: Account Summary description: >- Summary representation of an account resource in accounts 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. allOf: - $ref: '#/definitions/abstractResource' - $ref: '#/definitions/accountFields' - type: object properties: _id: description: >- The unique identifier for this account resource. This is an immutable opaque string. type: string state: description: >- The state of the account. This field is immutable and derived. * **`pending`** : A new account that has not been verified * **`active`** : An account which is active and available for use and for making new transactions. * **`inactive`** : An account which is marked inactive and not available for new transactions. Inactive accounts may be changed back to active. * **`frozen`** : An account which is frozen and not eligible for new transactions. This is typically the result of suspicious activity or fraud detection. The user must contact their financial institution to unfreeze the account (by changing the state back to `active`) or the financial institution may opt to close the account. * **`closed`** : An account that is closed and removed from use Closed accounts are not eligble for transactions or to become active. Such accounts are retained for historical purposes because some transactions may refer to it. Users do not see closed accounts when they view their acocunts. To change the state of an account, `POST` the account URI to the corresponding resource endpoints, using the corresponding link on the account resource. To activate an account, use the `apiture:activate` link to `POST` to `/accounts/activeAccounts`. To deactivate an account, use the `apiture:deactivate` link to `POST` to `/accounts/inactiveAccounts`. To freeze an account, use the `apiture:freeze` link to `POST` to `/accounts/frozenAccounts`. To close an account, use the `apiture:close` link to `POST` to `/accounts/closedAccounts`. type: string enum: - pending - active - inactive - frozen - closed example: active title: description: >- The name of the account holder. This is derived from the contact resource. type: string maxLength: 512 example: John Smith accountTitle: description: >- The name of the account holder. This is derived from the contact resource. **Note**: This property is deprecated. Use `title` instead. This property will be removed in the next release of this service. type: string maxLength: 512 accountNumbers: description: >- Different representations of the account number. allOf: - $ref: '#/definitions/accountNumbers' balance: description: The account balance. readOnly: true allOf: - $ref: '#/definitions/balance' rate: description: >- The account's rate of return (for deposit account) or interest rate (for debut accounts). readOnly: true allOf: - $ref: '#/definitions/rate' attributes: $ref: '#/definitions/attributes' example: _id: '0399abed-fd3d-4830-a88b-30f38b8a365c' _profile: 'https://api.apiture.com/schemas/account/v1.0.0/profile.json' _links: self: href: /accounts/accounts/0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:product': href: /products/products/0aba4bae-f18b-4c12-af99-5f8dbd682ae3 name: My basic savings account state: active balance: current: '3450.30' available: '3450.30' currency: USD rate: value: '1.40' type: apr createAccount: title: Create Account description: >- Representation used to create a new account. The request should contain a link to an approved account application; the account type and product are extracted from that application resource, as are additional associations to people or organizations that should be attached to the account (such as co-owner, a business, etc.) allOf: - $ref: '#/definitions/accountFields' - $ref: '#/definitions/abstractResource' - type: object example: _profile: 'https://api.apiture.com/schemas/account/v1.0.0/profile.json' name: My savings account _links: 'apiture:contact': href: /contacts/contacts/00007276-8b25-4e97-ac82-e1e17a2ff7c2 'apiture:application': href: /accountApplications/applications/2f23b9fe-532f-4e82-943e-b079ea55aebc updateAccount: title: Update Account description: Representation used to update or patch an account. allOf: - $ref: '#/definitions/summaryAccount' - type: object example: _id: '0399abed-fd3d-4830-a88b-30f38b8a365c' _profile: 'https://api.apiture.com/schemas/account/v1.0.0/profile.json' name: My basic savings account account: title: Account description: >- Representation of an account resource. A banking account, which is an instance of a banking product The `_links` on an external account may include the following, depending on the state of the account: *`self`* - The link to the external account. *`apiture:productType`* - The link to the external account's product type. *`apiture:activate`* - Activate the account (POST) *`apiture:deactivate`* - Deactivate the account (POST) *`apiture:freeze`* - Freeze the account (POST) *`apiture:close`* - Close the account (POST) allOf: - $ref: '#/definitions/updateAccount' - type: object properties: productName: description: >- The name of the banking product that this account is an instance of. This is derived from the product resource. type: string maxLength: 128 minLength: 1 readOnly: true type: description: >- The name of the banking product type. This is derived from the _product_ resource. The `subtype` is more specific; `type` is a broad account category. type: string maxLength: 128 minLength: 1 readOnly: true subtype: description: >- The name of the banking product sub type. This is derived from the _product_ resource. This is more specific than the `type`. type: string maxLength: 128 minLength: 1 readOnly: true example: _id: '0399abed-fd3d-4830-a88b-30f38b8a365c' _profile: 'https://api.apiture.com/schemas/account/v1.0.0/profile.json' _links: self: href: /accounts/accounts/0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:product': href: /products/products/0aba4bae-f18b-4c12-af99-5f8dbd682ae3 'apiture:deactivate': href: /accounts/inactiveAccounts?account=0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:freeze': href: /accounts/frozenAccounts?account=0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:close': href: /accounts/closedAccounts?account=0399abed-fd3d-4830-a88b-30f38b8a365c _embedded: product: _id: '0aba4bae-f18b-4c12-af99-5f8dbd682ae3' _profile: 'https://api.apiture.com/schemas/product/v1.0.0/profile.json' name: My basic savings account productName: Basic Personal Savings title: John Smith type: Personal Savings subtype: Basic Personal Savings state: active accountNumbers: masked: '*************2298' balance: current: '3450.30' available: '3450.30' currency: USD accounts: title: Account Collection description: >- Collection of accounts. The items in the collection are ordered in the `_embedded` object with name `items`. The top-level `_links` object may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`.) allOf: - $ref: '#/definitions/collection' - type: object properties: _embedded: type: object properties: items: description: An array containing a page of account items. type: array items: $ref: '#/definitions/summaryAccount' example: _profile: 'https://api.apiture.com/schemas/collection/account/v1.0.0/profile.json' start: 10 limit: 10 count: 67 name: accounts _links: self: href: /accounts/accounts?start=10&limit=10 first: href: /accounts/accounts?start=0&limit=10 next: href: /accounts/accounts?start=20&limit=10 collection: href: /accounts/accounts _embedded: items: - _id: '0399abed-fd3d-4830-a88b-30f38b8a365c' _profile: 'https://api.apiture.com/schemas/account/v1.0.0/profile.json' name: My basic savings account title: John Smith state: active balance: current: '3450.30' available: '3450.30' currency: USD accountNumbers: masked: '*************3210' _links: self: href: /accounts/accounts/0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:product': href: /products/products/0aba4bae-f18b-4c12-af99-5f8dbd682ae3 abstractResource: title: Abstract Resource description: >- An augmented [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`. properties: _links: $ref: '#/definitions/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](http://docs.apiture.com/docs/concepts#resource-profile) 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: '#/definitions/error' example: _profile: 'https://api.apiture.com/schemas/example/v1.0.0/profile.json' _links: self: href: '{uri of current resource}' collection: title: Collection description: A collection of resources. allOf: - $ref: '#/definitions/abstractResource' - type: object properties: count: description: The total number of items in the collection. 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 root: title: API Root description: >- A HAL response, with hypermedia `_links` for the top-level resources and operations in API. example: id: apiName name: API name apiVersion: 0.0.1-SNAPSHOT _profile: 'https://api.apiture.com/schemas/apiRoot/v1.0.0/profile.json' _links: {} allOf: - $ref: '#/definitions/abstractResource' - type: object properties: _id: type: string description: This API's unique ID. name: type: string description: This API's name. apiVersion: type: string description: This API's version. errorResponse: title: Error Response description: >- Describes an error response, typically returned on 4xx or 5xx errors from API operations. The `_error` object contains the error details. allOf: - $ref: '#/definitions/abstractResource' example: _profile: 'https://api.apiture.com/schemas/error/v1.0.0/.json' _error: _id: '2eae46e1-575c-4d69-8a8f-0a7b0115a4b3' _profile: 'https://api.apiture.com/schemas/error/v1.0.0/profile.json' message: The value for deposit must be greater than 0. statusCode: 422 type: positiveNumberRequired attributes: value: -125.50 remediation: Provide a value which is greater than 0 occurredAt: '2018-01-25T05:50:52.375Z' _links: describedby: href: 'http://docs.apiture.com/errors/positiveNumberRequired' _embedded: errors: [] error: title: Error description: >- An error description. Nested source errors are contained in the `_embedded` object with the key `"errors"`; this is an array of nested error objects. For example, an API which validates its request body may find multiple errors in the request, which may be detailed here. The `_links` may contain a `describedby` link which refers to a web page with details about the error. The `attributes` field An optional map of name/value pairs which provide structured data about the error. For example, if the error is a value out of range, the attributes may specify the range values `min` and `max`. This allows clients to present error messages as they see fit (the API does not assume the client/presentation tier). required: - message properties: message: type: string description: A localized message string describing the error condition. _id: type: string 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. 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: Data attribute associated with the error, such as values or constraints. allOf: - $ref: '#/definitions/attributes' remediation: type: string description: An optional localized string which provides hints for how the user or client can resolve the error. _embedded: description: Optional embedded array of errors. This field may not exist if the error does not have nested errors. type: object properties: items: description: An array of error objects. type: array items: $ref: '#/definitions/errorResponse' example: _id: '2eae46e1-575c-4d69-8a8f-0a7b0115a4b3' _profile: 'https://api.apiture.com/schemas/error/v1.0.0/profile.json' message: The value for deposit must be greater than 0. statusCode: 422 type: positiveNumberRequired attributes: value: -125.50 remediation: Provide a value which is greater than 0 occurredAt: '2018-01-25T05:50:52.375Z' _links: describedby: href: 'http://docs.apiture.com/errors/positiveNumberRequired' _embedded: errors: [] attributes: title: Attributes description: >- An optional map of name/value pairs which contains additional dynamic data about the resource. type: object links: title: Links description: >- An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations. type: object additionalProperties: $ref: '#/definitions/link' link: title: Link description: >- Describes a hypermedia link within a `_links` object in HAL representations. In Apiture APIs, links are [HAL links](https://tools.ietf.org/html/draft-kelly-json-hal-08#section-5), but Apiture APIs do not use the `name` or `hreflang` properties of HAL. Apiture links _may_ include a `method` property. required: - href properties: href: type: string format: uri description: >- The URI or URI template for the resource/operation this link refers to. type: type: string description: The media type for the resource. templated: type: boolean description: >- If true, the link's href is a [URI template](https://tools.ietf.org/html/rfc6570). title: type: string description: An optional human-readable localized title for the link. deprecation: type: string format: uri description: >- If present, the containing link is deprecated and the value is a URI which provides human-readable text information about the deprecation. profile: type: string format: uri description: >- The URI of a profile document, a JSON document which describes the target resource/operation. balance: description: >- The balance of the account. This is derived data and not mutable through the API. Balances may be negative, indicating a deficit or loan balance. properties: current: description: >- The string representation of the current account balance. This is an exact decimal representation of the numeric balance value. The current balance does not include pending transactions. type: string readOnly: true example: '3450.30' value: description: >- The current balance. **Note**: This property is deprecated. Use `balance.current` instead. This property will be removed in the next release of this service. type: string readOnly: true example: '3450.30' available: description: >- The string representation of the exact decimal available balance. For deposit accounts, this reflects the amount that may be used for withdrawals or transfers. This field does not apply to debit accounts such as loans. type: string readOnly: true example: '3450.30' currency: description: >- The [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217) for this balance. type: string readOnly: true example: current: '3450.30' available: '3450.30' currency: USD rate: description: >- The interest rate of the account. For deposit accounts, this is the rate of return; for loan accounts, this is the interest rate charged on balances. properties: value: description: >- The rate, expressed as an decimal perscentage in order to represent the rate exactly. type: string readOnly: true example: '1.40' type: description: The interest rate type. type: string readOnly: true allOf: - $ref: '#/definitions/interestRateType' example: value: '1.40' type: apr interestRateType: description: >- The rate type. Rate types are: * **`apr`** - annual percentage rate * **`apy`** - annual percentage yield type: string enum: - apr - apy example: apr x-apiture-errors: accountAccessDenied: description: The credentials supplied in the request are insufficient to grant access remediation: Check the supplied credentials for validity accessDenied: description: The credentials supplied in the request are insufficient to grant access remediation: Check the supplied credentials for validity invalidAccountId: description: No Accounts were found for the specified accountId remediation: Check to make sure that the supplied accountId corresponds to an apiture account resource productUriNotSupplied: description: A link to the product was not supplied for the account remediation: Include a link to a valid apiture product in the _links object of your request contactUriNotSupplied: description: A link to the contact was not supplied for the account remediation: Include a link to a valid apiture contact in the _links object of your request invalidContactId: description: No contact was found for the specified contactId remediation: Check to make sure that the supplied contactId corresponds to an apiture contact resource invalidProductId: description: No Products were found for the specified productId remediation: Check to make sure that the supplied productId corresponds to an apiture product resource invalidUnmaskedQueryParam: description: Only the values of false or true can be supplied with the unmasked query parameter remediation: Resubmit the operation without the query parameter or check the documentation for valid query params attributes: properties: validUnmaskedValues: ['false', 'true'] malformedAccountUri: description: The supplied accountUri was malformed remediation: Check to make sure that the supplied accountUri corresponds to an apiture account resource attributes: properties: exampleAccountUris: [ '/accounts/accounts/0399abed-fd3d-4830-a88b-30f38b8a365c', '/accounts/externalAccounts/0aba4bae-f18b-4c12-af99-5f8dbd682ae3', ] malformedRequestBody: description: The supplied request body was malformed remediation: Check to make sure that your request body exists and that it does not contain syntax errors cannotPatchState: description: The state field cannot be updated via PATCH remediation: Resubmit the operation and leave state out of the request body invalidAccountState: description: Actions on accounts may only be performed if they are in one of the required states remediation: Check the state of your Account and the applicable allowed state transitions in the Accounts API documentation attributes: properties: currentState: 'pending' requestedState: 'active' requiredStates: ['pending', 'active', 'inactive', 'frozen'] internalError: description: An unexpected interal server error occurred. remediation: Retry the operation again x-apiture-traits: - api: title: Accounts basePath: accounts links: [getApi, getApiDoc, getAccounts, getExternalAccounts, createExternalAccount, createAccount] - resource: name: account description: 'A banking account, which is an instance of a banking product.' excludeMethods: - put - delete - resource: name: external account description: A banking account held by another financial institution. excludeMethods: - put