swagger: '2.0' info: title: Approvals description: >- This API manages state-transition based approvals for Financial Institutions. Approval milestones are useful in confirming that part or all of a process is complete. Examples of approvals may include Identity Verification Document approval or Account Application approval. Approval States may be one of the following: * **`open`** Created but pending input subject to approval * **`submitted`** Pending review by approver * **`approved`** Approval granted * **`rejected`** Approval denied * **`waived`** Approval forgiven * **`returned`** Approver returns approval for modification * **`canceled`** Approval request withdrawn Allowed state transitions are: * `open` -> `submitted` * `open` -> `waived` * `submitted` -> `approved` * `submitted` -> `rejected` * `submitted` -> `waived` * `submitted` -> `returned` * `returned` -> `submitted` * `open` -> `canceled` * `submitted` -> `canceled` * `returned` -> `canceled` An approval may only be deleted if its `state` is `open` or `canceled`. In order to change the state, use `POST` to the `href` in the corresponding links (`apiture:approve`, `apiture:submit`, `apiture:reject`, etc.) in the approval resource as described fully in the _Approval_ schema. All approval resources contain an approval type, a resource that is also managed in this API. Approval types provide financial institutions the ability to track, reconcile and group specific approvals. In addition, metadata regarding specific types of approvals can be stored on the approval type. Approval types may only be deleted if they are not in use by any existing approvals. Some examples of approval types may be specific documents releated to new account opening that need to be manually approved, account applications or transfer requests. The _target_ of the approval, which may be any resource, is not required but may be provided on the `POST` operation that creates the approval. This may be done in the `_links` with the link relation `apiture:target`. Alternatively, the content to be approved may be embedded within the `attributes` on the approval request. It will also be conveyed in the approval representation in the `GET` operation on the instance and the summary representation in the `/approvals` collection. Some `target` examples may include an account application or a document. Additional data related to an approval or approval type may be stored in the resource's attributes. Attributes can be modified through `PATCH` and are _*not*_ copied from the approval type to the approval. version: 0.3.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: /approvals consumes: - application/hal+json - application/json produces: - application/hal+json - application/json tags: - name: API description: Endpoints which describe this API. paths: /approvals: get: summary: Return a collection of approvals description: >- Return a[ paginated](http://doc.apiture.com/api/concepts/pagination)[ sortable](http://doc.apiture.com/api/concepts/sorting)[ filterable](http://doc.apiture.com/api/concepts/filtering)[ searchable](http://doc.apiture.com/api/concepts/searchable) collection of approvals. The [links](http://doc.apiture.com/api/concepts/links) in the response include pagination links. operationId: getApprovals x-apiture-implemented: true x-apiture-traits: link: rel: approvals title: List Approvals tags: - Approval parameters: - name: start in: query description: >- The zero-based index of the first approval 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 approval 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/api/concepts/sorting#criteria), such as `?sortBy=field1,-field2`. - $ref: '#/parameters/filterQueryParam' - $ref: '#/parameters/qQueryParam' responses: '200': description: OK schema: $ref: '#/definitions/approvals' '400': $ref: '#/responses/400' '401': $ref: '#/responses/401' '422': $ref: '#/responses/422' post: summary: Create a new approval description: 'Create a new approval in the approvals collection. The link to an Approval Type resource is required in order to create a new Approval resource. This link should be passed in the _links in the request with an `apiture:approvalType` key. The optional target of an approval may be passed on Approval create in either the `_links` with the link relation `apiture:target` or in `attributes`.' operationId: createApproval x-apiture-implemented: true tags: - Approval parameters: - name: approval in: body description: The data necessary to create a new approval. required: true schema: $ref: '#/definitions/createApproval' responses: '201': description: Created schema: $ref: '#/definitions/approval' 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' '401': $ref: '#/responses/401' '/approvals/{approvalId}': get: summary: Fetch a representation of this approval description: >- Return a [HAL](http://docs.apiture.com/api/concepts/hal) representation of this approval resource. operationId: getApproval x-apiture-implemented: true tags: - Approval parameters: - $ref: '#/parameters/approvalIdPathParam' - $ref: '#/parameters/ifNoneMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/approval' 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 approval resource. type: string '304': $ref: '#/responses/304' '401': $ref: '#/responses/401' '404': $ref: '#/responses/404Approval' put: summary: Update this approval description: Perform a complete replacement of this approval. operationId: updateApproval x-apiture-implemented: true tags: - Approval parameters: - $ref: '#/parameters/approvalIdPathParam' - name: approval in: body required: true schema: $ref: '#/definitions/updateApproval' - $ref: '#/parameters/ifMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/approval' 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 approval resource. type: string '400': $ref: '#/responses/400' '401': $ref: '#/responses/401' '404': $ref: '#/responses/404Approval' '412': $ref: '#/responses/412' '422': $ref: '#/responses/422' '428': $ref: '#/responses/428' patch: summary: Update this approval description: >- Perform a partial update of this approval. Fields which are omitted are not updated. Nested `_embedded` and `_links` are ignored if included. operationId: patchApproval x-apiture-implemented: true tags: - Approval parameters: - $ref: '#/parameters/approvalIdPathParam' - name: approval in: body required: true schema: $ref: '#/definitions/updateApproval' - $ref: '#/parameters/ifMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/approval' 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 approval resource. type: string '400': $ref: '#/responses/400' '401': $ref: '#/responses/401' '404': $ref: '#/responses/404Approval' '412': $ref: '#/responses/412' '422': $ref: '#/responses/422' '428': $ref: '#/responses/428' delete: summary: Delete this approval resource description: Delete this approval resource and any resources that are owned by it. an Approval may only be deleted if its state is `open` or `canceled`. operationId: deleteApproval x-apiture-implemented: true tags: - Approval parameters: - $ref: '#/parameters/approvalIdPathParam' responses: '204': $ref: '#/responses/204Deleted' '401': $ref: '#/responses/401' /approvedApprovals: post: summary: Approve an approval description: Approve an approval.

Only product types which are `submitted` may be `approved`.

This operation is invoked from the `apiture:approve` link on a product type when it is eligible to be approved.

This changes the `state` to `approved`. operationId: approveApproval x-apiture-implemented: true tags: - Approval parameters: - $ref: '#/parameters/approvalQueryParam' - name: approvalUri description: >- The URI of an existing approval which is eligible to be approved. Note: This parameter is **deprecated** and will be removed in the next version. Use `?approval=` instead. type: string in: query - $ref: '#/parameters/ifMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/approval' '400': description: >- Bad Request. The `approval` or `approvalUri` parameter was malformed or does not refer to an approval. '401': $ref: '#/responses/401' '409': $ref: '#/responses/409ApprovalConflict' '422': $ref: '#/responses/422' '428': $ref: '#/responses/428' /rejectedApprovals: post: summary: Reject an approval description: Reject an approval.

Only product types which are `submitted` may be `rejected`.

This operation is invoked from the `apiture:reject` link on a product type when it is eligible to be rejected.

This changes the `state` to `rejected`. operationId: rejectApproval x-apiture-implemented: true tags: - Approval parameters: - $ref: '#/parameters/approvalQueryParam' - name: approvalUri description: >- The URI of an existing approval which is eligible to be rejected. Note: This parameter is **deprecated** and will be removed in the next version. Use `?approval=` instead. type: string in: query - $ref: '#/parameters/ifMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/approval' '400': description: >- Bad Request. The `approval` or `approvalUri` was malformed or does not refer to an approval. '401': $ref: '#/responses/401' '409': $ref: '#/responses/409ApprovalConflict' '422': $ref: '#/responses/422' '428': $ref: '#/responses/428' /waivedApprovals: post: summary: Waive an approval description: Waive an approval.

Only product types which are `open` or `submitted` may be `waived`.

This operation is invoked from the `apiture:waive` link on a product type when it is eligible to be waived.

This changes the `state` to `waived`. operationId: waiveApproval x-apiture-implemented: true tags: - Approval parameters: - $ref: '#/parameters/approvalQueryParam' - name: approvalUri description: >- The URI of an existing approval which is eligible to be waived. Note: This parameter is **deprecated** and will be removed in the next version. Use `?approval=` instead. type: string in: query required: true - $ref: '#/parameters/ifMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/approval' '400': description: >- Bad Request. The 'approval` or `approvalUri` was malformed or does not refer to an approval. '401': $ref: '#/responses/401' '409': $ref: '#/responses/409ApprovalConflict' '422': $ref: '#/responses/422' '428': $ref: '#/responses/428' /submittedApprovals: post: summary: Submit an approval description: Submit an approval.

Only product types which are `open` or `returned` may be `submitted`.

This operation is invoked from the `apiture:submit` link on a product type when it is eligible to be submitted.

This changes the `state` to `submitted`. operationId: submitApproval x-apiture-implemented: true tags: - Approval parameters: - $ref: '#/parameters/approvalQueryParam' - name: approvalUri description: >- The URI of an existing approval which is eligible to be submitted. Note: This parameter is **deprecated** and will be removed in the next version. Use `?approval=` instead. type: string in: query required: true - $ref: '#/parameters/ifMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/approval' '400': description: >- Bad Request. The `approval` or `approvalUri` was malformed or does not refer to an approval. '401': $ref: '#/responses/401' '409': $ref: '#/responses/409ApprovalConflict' '422': $ref: '#/responses/422' '428': $ref: '#/responses/428' /returnedApprovals: post: summary: Return an approval description: Return an approval.

Only product types which are `submitted` may be `returned`.

This operation is invoked from the `apiture:return` link on a product type when it is eligible to be returned.

This changes the `state` to `returned`. operationId: returnApproval x-apiture-implemented: true tags: - Approval parameters: - $ref: '#/parameters/approvalQueryParam' - name: approvalUri description: >- The URI of an existing approval which is eligible to be returned. Note: This parameter is **deprecated** and will be removed in the next version. Use `?approval=` instead. type: string in: query required: true - $ref: '#/parameters/ifMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/approval' '400': description: >- Bad Request. The `approval` or `approvalUri` was malformed or does not refer to an approval. '401': $ref: '#/responses/401' '409': $ref: '#/responses/409ApprovalConflict' '422': $ref: '#/responses/422' '428': $ref: '#/responses/428' /canceledApprovals: post: summary: Cancel an approval description: Cancel an approval.

Only product types which are `open`, `submitted` or `returned` may be `canceled`.

This operation is invoked from the `apiture:cancel` link on a product type when it is eligible to be cenceled.

This changes the `state` to `canceled`. operationId: cancelApproval x-apiture-implemented: true tags: - Approval parameters: - $ref: '#/parameters/approvalQueryParam' - name: approvalUri description: >- The URI of an existing approval which is eligible to be canceled. Note: This parameter is **deprecated** and will be removed in the next version. Use `?approval=` instead. type: string in: query required: true - $ref: '#/parameters/ifMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/approval' '400': description: >- Bad Request. The `approval` or `approvalUri` was malformed or does not refer to an approval. '401': $ref: '#/responses/401' '409': $ref: '#/responses/409ApprovalConflict' '422': $ref: '#/responses/422' '428': $ref: '#/responses/428' /approvalTypes: get: summary: Return a collection of approval types description: >- Return a[ paginated](http://doc.apiture.com/api/concepts/pagination)[ sortable](http://doc.apiture.com/api/concepts/sorting)[ filterable](http://doc.apiture.com/api/concepts/filtering)[ searchable](http://doc.apiture.com/api/concepts/searchable) collection of approvals. The [links](http://doc.apiture.com/api/concepts/links) in the response include pagination links. operationId: getApprovalTypes x-apiture-implemented: true x-apiture-traits: link: rel: approvalTypes title: List Approval Types tags: - Approval Type parameters: - name: start in: query description: >- The zero-based index of the first approval type 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 approval type 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/api/concepts/sorting#criteria), such as `?sortBy=field1,-field2`. - $ref: '#/parameters/filterQueryParam' - $ref: '#/parameters/qQueryParam' responses: '200': description: OK schema: $ref: '#/definitions/approvalTypes' '400': $ref: '#/responses/400' '401': $ref: '#/responses/401' '422': $ref: '#/responses/422' post: summary: Create a new approval type description: 'Create a new approval type in the approval types collection. ' operationId: createApprovalType x-apiture-implemented: true tags: - Approval Type parameters: - name: approvalType in: body description: The data necessary to create a new approval type. required: true schema: $ref: '#/definitions/createApprovalType' responses: '201': description: Created schema: $ref: '#/definitions/approvalType' 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 '409': $ref: '#/responses/409ApprovalTypeConflict' '400': $ref: '#/responses/400' '401': $ref: '#/responses/401' '/approvalTypes/{approvalTypeId}': get: summary: Fetch a representation of this approval type description: >- Return a [HAL](http://docs.apiture.com/api/concepts/hal) representation of this approval type resource. operationId: getApprovalType x-apiture-implemented: true tags: - Approval Type parameters: - $ref: '#/parameters/approvalTypeIdPathParam' - $ref: '#/parameters/ifNoneMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/approvalType' 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 approval type resource. type: string '304': $ref: '#/responses/304' '401': $ref: '#/responses/401' '404': $ref: '#/responses/404ApprovalType' put: summary: Update this approval type description: Perform a complete replacement of this approval type. operationId: updateApprovalType x-apiture-implemented: true tags: - Approval Type parameters: - $ref: '#/parameters/approvalTypeIdPathParam' - name: approvalType in: body required: true schema: $ref: '#/definitions/updateApprovalType' - $ref: '#/parameters/ifMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/approvalType' 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 approval type resource. type: string '400': $ref: '#/responses/400' '401': $ref: '#/responses/401' '404': $ref: '#/responses/404ApprovalType' '412': $ref: '#/responses/412' '422': $ref: '#/responses/422' '428': $ref: '#/responses/428' patch: summary: Update this approval type description: >- Perform a partial update of this approval type. Fields which are omitted are not updated. Nested `_embedded` and `_links` are ignored if included. operationId: patchApprovalType x-apiture-implemented: true tags: - Approval Type parameters: - $ref: '#/parameters/approvalTypeIdPathParam' - name: approval in: body required: true schema: $ref: '#/definitions/patchApprovalType' - $ref: '#/parameters/ifMatchHeaderParam' responses: '200': description: OK schema: $ref: '#/definitions/approvalType' 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 approval type resource. type: string '400': $ref: '#/responses/400' '401': $ref: '#/responses/401' '404': $ref: '#/responses/404ApprovalType' '412': $ref: '#/responses/412' '422': $ref: '#/responses/422' '428': $ref: '#/responses/428' delete: summary: Delete this approval type resource description: Delete this approval type resource and any resources that are owned by it. Deleting an Approval Type is only allowed if it is not in use by any existing Approvals. operationId: deleteApprovalType x-apiture-implemented: true tags: - Approval Type parameters: - $ref: '#/parameters/approvalTypeIdPathParam' responses: '204': $ref: '#/responses/204Deleted' '401': $ref: '#/responses/401' '409': $ref: '#/responses/409ApprovalTypeConflict' /: get: summary: Top-level resources and operations in this API description: Return links to the top-level resources and operations in this API. operationId: getApi x-apiture-implemented: true responses: '200': description: OK schema: $ref: '#/definitions/root' 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 parameters: approvalIdPathParam: name: approvalId description: The unique identifier of this approval. This is an opaque string. in: path type: string required: true approvalQueryParam: name: approval description: A server-generated key which identifies an existing approval resource. type: string in: query required: true approvalTypeIdPathParam: name: approvalTypeId description: The unique identifier of this approval type. This is an opaque string. in: path type: string required: true filterQueryParam: name: filter in: query description: >- Optional filter criteria. See [filtering](http://docs.apiture.com/api/concepts/filtering#criteria). type: string qQueryParam: name: q in: query description: >- Optional search string. See [searching](http://docs.apiture.com/api/concepts/searching). 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 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 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 '401': description: >- Unauthorized. The request has not been applied because it lacks valid authentication credentials for the target resource. schema: $ref: '#/definitions/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. 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' 404Approval: description: >- Not Found. There is no such approval resource at the specified `{approvalId}`. The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' x-apiture-errors: - invalidApprovalId 404ApprovalType: description: >- Not Found. There is no such approval type resource at the specified `{approvalTypeId}`. The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' x-apiture-errors: - invalidApprovalTypeId 409ApprovalConflict: description: >- Conflict. There is a conflict between the request and the current state of the resource. It may be one of the following: * The `state` of an Approval resource may only be changed in accordance with the state transitions described in this specification. schema: $ref: '#/definitions/errorResponse' x-apiture-errors: - approveApprovalInvalidState - deleteApprovalInvalidState - cancelApprovalInvalidState - rejectApprovalInvalidState - returnApprovalInvalidState - submitApprovalInvalidState - waiveApprovalInvalidState 409ApprovalTypeConflict: description: >- Conflict. There is a conflict between the request and the current state of the resource. It may be one of the following: * The `name` and `domain` of the Approval Type must be a unique combination within the FI Approval Type Resources. * The Approval Type is in use and cannot be deleted. schema: $ref: '#/definitions/errorResponse' x-apiture-errors: - nameAndDomainMustBeUnique - approvalTypeInUse 204Deleted: description: No Content. The resource was deleted successfully. definitions: approvalFields: title: Approval Fields description: >- Common fields of the approval resource used to build other model schemas. properties: label: description: The approval's common name. If ommitted on create request, this will default to the label of the Approval Type. type: string description: description: The approval's description. If ommitted on create request, this will default to the description of the Approval Type. type: string state: description: >- The approval's state. * **`open`** Created but pending input subject to approval * **`submitted`** Pending review by approver * **`approved`** Approval granted * **`rejected`** Approval denied * **`waived`** Approval forgiven * **`returned`** Approver returns approval for modification * **`canceled`** Approval request withdrawn This is an immutable and derived property. It's value can only be changed by using the corresponding `POST` operations, `submitApproval`, `approveApproval`, `rejectApproval`, `waiveApproval`, `returnApproval`, and `cancelApproval`. type: string enum: - open - submitted - approved - rejected - waived - returned - canceled default: open done: description: Inferred done flag. If `done` is true, the approval is in a terminal state and may no longer be acted upon. Done states include `canceled`, `approved`, `waived` or `rejected`. type: boolean typeName: description: The name of the Approval Type. This field is immutable and derived from the name of the Approval Type. type: string reviewedBy: description: The id of the User that reviewed the approval. type: string reviewedAt: description: The date-time when the approval was reviewed. type: string format: date-time example: state: active done: true label: Government Issued ID typeName: governmentId description: A document that identifies a user reviewedBy: /users/users/0399abed-fd3d-4830-a88b-30f38b8a365c reviewedAt: '2018-04-17T10:12:58.375Z' createApproval: title: Create Approval description: >- Representation used to create a new approval. A link to an `apiture:approvalType` is required to perform this operation. An optional `apiture:target` link may also be specified to represent the target resource for the approval. The target can be any resource, for example, an account application or a document. allOf: - $ref: '#/definitions/abstractResource' - $ref: '#/definitions/approvalFields' - type: object properties: attributes: type: object description: >- An optional map of name/value pairs which provide additional metadata about the approval. example: _profile: 'http://api.apiture.com/schemas/basePath/approval/v1.0.0/profile.json' summaryApproval: title: Approval Summary description: >- Summary representation of an approval resource in approvals 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/approvalFields' - type: object properties: _id: description: >- The unique identifier for this approval resource. This is an immutable opaque string. type: string example: _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'http://api.apiture.com/schemas/approvals/approvals/v1.0.0/profile.json' _links: self: href: /approvals/approvals/0399abed-fd3d-4830-a88b-30f38b8a365c updateApproval: title: Update Approval description: >- Representation used to update or patch an approval. The `state` field is immutable and not updated by this operation, but by the `state transition` POST operations such as `approve` or `reject` (ex. `apiture:approve` and `apiture:reject`). allOf: - $ref: '#/definitions/summaryApproval' - type: object properties: attributes: type: object description: >- An optional map of name/value pairs which provide additional metadata about the approval. example: _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'http://api.apiture.com/schemas/approvals/approvals/v1.0.0/profile.json' approval: title: Approval description: >- An approval represents the _review_ of some process, activity or resource, such as a document or an application. The state of the approval is recorded in its `state` property. The target of the approval is in the link named `apiture:target`; see the _Create Approval_ schema and `createApproval` operation. Links on an approval convey which state transitions are available. These links are: * **`apiture:approve`** -- mark the review request as approved * **`apiture:reject`** -- to reject the approval request * **`apiture:waive`** -- to waive the approval requirements. For example, rather than requiring a specific identity verification document to be approved, waiving the requirement means the document does not have to be provided. * **`apiture:return`** -- to return the request so the client can update the request or resource, then resubmit the request for approval * **`apiture:submit`** -- to submit a new request for appoval, or resubmit a request after it has been returned * **`apiture:cancel`** -- to cancel the request for review/approval The client should use `POST` to invoke these operations, using the `href` on the named link object. No request body is used on these operations. The absence of a link indicates that the particular state transition is not available at that time or that the caller is not authorized to make the change. For example, a user may lack permissions to approve a wire transfer they submitted. allOf: - $ref: '#/definitions/updateApproval' - type: object properties: createdAt: description: The date-time when the approval was created. type: string format: date-time updatedAt: description: The date-time when the approval was updated type: string format: date-time _embedded: description: The objects which participate in this association type: object properties: approvalType: description: The role for this association allOf: - $ref: '#/definitions/summaryApprovalType' example: _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'http://api.apiture.com/schemas/approvals/approvals/v0.1.0/profile.json' createdAt: '2018-04-17T10:04:46.375Z' updatedAt: '2018-04-17T10:12:58.375Z' _links: self: href: /approvals/approvals/0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:approvalType': href: /approvals/approvalTypes/e4f09b4d-eba6-46da-86d3-ba28595067cd 'apiture:target': href: /vault/files/e4f09b4d-eba6-46da-86d3-hjr434fuhe _embedded: approvalType: _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: >- http://api.apiture.com/schemas/approvals/approvalTypes/v0.1.0/profile.json _links: self: href: /approvals/approvalTypes/0399abed-fd3d-4830-a88b-30f38b8a365c name: governmentId label: Government Issued ID description: A document that identifies a user approvals: title: Approval Collection description: >- Collection of approvals. The items in the collection are ordered in the `_embedded.items` array; the `name` is `approvals`. 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 approval items. type: array items: $ref: '#/definitions/summaryApproval' example: _profile: 'http://api.apiture.com/schemas/basePath/approvals/v0.1.0/profile.json' start: 10 limit: 10 count: 67 name: approvals _links: self: href: /basePath/approvals?start=10&limit=10 first: href: /basePath/approvals?start=0&limit=10 next: href: /basePath/approvals?start=20&limit=10 collection: href: /basePath/approvals _embedded: items: - _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: >- http://api.apiture.com/schemas/approvals/approvals/v0.1.0/profile.json _links: self: href: /approvals/approvals/0399abed-fd3d-4830-a88b-30f38b8a365c state: active done: true label: Government Issued ID description: A document that identifies a user reviewedBy: /users/users/0399abed-fd3d-4830-a88b-30f38b8a365c reviewedAt: '2018-04-17T10:12:58.375Z' approvalTypeFields: title: Approval Type Fields description: >- Common fields of the approval resource used to build other model schemas. properties: name: description: The approval's name. type: string label: description: The approval's common name. type: string description: description: The approval's description. type: string domain: description: A namespace for grouping related resources, to keep them separate from other resources. For example, a department or bank branch may define a domain, and all Approval Type instances they define will use that domain, so that they can avoid conflicting with Approval Type names in other domains. An API or service may define a domain for Approval Types that it defines. The combination of domain and name must be unique within the set of all resources of this type. It is a best practice to define domains with URIs. type: string example: name: governmentId label: Government Issued ID description: A document that identifies a user domain: http://api.apiture.com/domains/approvals/documentRequirement approvalTypes: title: Approval Types Collection description: >- Collection of approval types. The items in the collection are ordered in the `_embedded.items` array; the `name` is `approvals`. 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 approval type items. type: array items: $ref: '#/definitions/summaryApprovalType' example: _profile: 'http://api.apiture.com/schemas/basePath/approvalTypes/v0.1.0/profile.json' start: 10 limit: 10 count: 67 name: approvalTypes _links: self: href: /basePath/approvalTypes?start=10&limit=10 first: href: /basePath/approvalTypes?start=0&limit=10 next: href: /basePath/approvalTypes?start=20&limit=10 collection: href: /basePath/approvalTypes _embedded: items: - _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: >- http://api.apiture.com/schemas/approvals/approvalTypes/v0.1.0/profile.json _links: self: href: /approvals/approvalTypes/0399abed-fd3d-4830-a88b-30f38b8a365c name: governmentId label: Government Issued ID description: A document that identifies a user createApprovalType: title: Create Approval Type description: >- Representation used to create a new approval type. required: - name allOf: - $ref: '#/definitions/abstractResource' - $ref: '#/definitions/approvalTypeFields' - type: object properties: attributes: type: object description: >- An optional map of name/value pairs which provide additional metadata about the approval type. example: _profile: 'http://api.apiture.com/schemas/basePath/approvalTypes/v1.0.0/profile.json' approvalType: title: Approval Type description: >- All Approval resources contain an Approval Type, a resource that is also managed in this API. Approval Types provide Financial Institutions the ability to track, reconcile and group specific Approvals. In addition, metadata regarding specific types of Approvals can be stored on the Approval Type. Approval Types may onle be deleted if they are not in use by any existing Approvals. Some examples of Approval Types may be specific documents releated to New Account Opening that need to be manually approved, Account Applications or Transfer requests. allOf: - $ref: '#/definitions/updateApprovalType' - type: object properties: createdAt: description: The date-time when the approval was created. type: string format: date-time updatedAt: description: The date-time when the approval was updated type: string format: date-time updateApprovalType: title: Update Approval Type required: - name description: >- Representation used to update or patch an approval type. allOf: - $ref: '#/definitions/summaryApprovalType' - type: object properties: attributes: type: object description: >- An optional map of name/value pairs which provide additional metadata about the approval type. example: _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'http://api.apiture.com/schemas/approvals/approvalTypes/v1.0.0/profile.json' patchApprovalType: title: Update Approval Type description: >- Representation used to update or patch an approval type. allOf: - $ref: '#/definitions/summaryApprovalType' - type: object properties: attributes: type: object description: >- An optional map of name/value pairs which provide additional metadata about the approval type. example: _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'http://api.apiture.com/schemas/approvals/approvalTypes/v1.0.0/profile.json' summaryApprovalType: title: Approval Type Summary description: >- Summary representation of an approval type resource in approvals 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/approvalTypeFields' - type: object properties: _id: description: >- The unique identifier for this approval resource. This is an immutable opaque string. type: string example: _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'http://api.apiture.com/schemas/approvals/approvalTypes/v1.0.0/profile.json' _links: self: href: /approvals/approvalTypes/0399abed-fd3d-4830-a88b-30f38b8a365c 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`. example: _profile: 'http://api.apiture.com/schemas/example/v1.0.0/profile.json' _links: self: href: '{uri of current resource}' apiture:approvalType: href: '/approvals/approvalType/0399abed-fd3d-4830-a88b-30f38b8a365c' apiture:target: href: /vault/files/e4f09b4d-eba6-46da-86d3-hjr434fuhe 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://doc.apiture.com/api/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' 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/root/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: 'http://api.apiture.com/schemas/error/v1.0.0/profile.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.5 remediation: Provide a value which is greater than 0 occurredAt: 2018-01-25T05:50:52.375Z _links: describedby: href: 'http://doc.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 ISO 8601 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.5 remediation: Provide a value which is greater than 0 occurredAt: '2018-01-25T05:50:52.375Z' _links: describedby: href: 'http://doc.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. collection: x-apiture-version: '1.0.0' title: Collection description: >- A collection of resources. This is an abstract model schema which is extended to define specific resource collections. allOf: - $ref: '#/definitions/abstractResource' - type: object properties: count: description: 'The number of items in the full 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 x-apiture-errors: approvalAccessDenied: description: The credentials supplied in the request are insufficient to grant access remediation: Check the supplied credentials for validity approvalTypeAccessDenied: description: The credentials supplied in the request are insufficient to grant access remediation: Check the supplied credentials for validity invalidApprovalId: description: No approvals were found for the specified approvalId remediation: Check to make sure that the supplied approvalId corresponds to an apiture approval resource invalidApprovalTypeId: description: No approvalTypes were found for the specified approvalTypeId remediation: Check to make sure that the supplied approvalTypeId corresponds to an apiture approvalType resource 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 ifMatchHeaderMissing: description: The "If-Match" header was not supplied remediation: Verify you are supplying an "If-Match" header in the request ifMatchHeaderDoesntMatch: description: This "If-Match" header does not match the current resource state remediation: Try getting the latest version of the resource and re-submitting your request deleteApprovalInvalidState: description: Approvals may only be deleted if they are in an open or canceled state remediation: Check the state of your Approval and the applicable allowed state transitions in the Approvals API documentation attributes: properties: requiredStates: ['canceled', 'open'] approveApprovalInvalidState: description: Approvals may only be approved if they are in a submitted state remediation: Check the state of your Approval and the applicable allowed state transitions in the Approvals API documentation attributes: properties: requestedState: 'approved' requiredStates: ['submitted'] cancelApprovalInvalidState: description: Approvals may only be canceled if they are in a submitted, open or returned state remediation: Check the state of your Approval and the applicable allowed state transitions in the Approvals API documentation attributes: properties: requestedState: 'canceled' requiredStates: ['submitted', 'open', 'returned'] rejectApprovalInvalidState: description: Approvals may only be rejected if they are in a submitted state remediation: Check the state of your Approval and the applicable allowed state transitions in the Approvals API documentation attributes: properties: requestedState: 'rejected' requiredStates: ['submitted'] returnApprovalInvalidState: description: Approvals may only be returned if they are in a submitted state remediation: Check the state of your Approval and the applicable allowed state transitions in the Approvals API documentation attributes: properties: requestedState: 'returned' requiredStates: ['submitted'] submitApprovalInvalidState: description: Approvals may only be submitted if they are in an open or returned state remediation: Check the state of your Approval and the applicable allowed state transitions in the Approvals API documentation attributes: properties: requestedState: 'submitted' requiredStates: ['open', 'returned'] waiveApprovalInvalidState: description: Approvals may only be waived if they are in an open or submitted state remediation: Check the state of your Approval and the applicable allowed state transitions in the Approvals API documentation attributes: properties: requestedState: 'waived' requiredStates: ['open', 'submitted'] nameAndDomainMustBeUnique: description: The combination of name and domain must be unique across ApprovalTypes remediation: Check the existing ApprovalTypes for an existing resource that matches the name and domain on your request approvalTypeInUse: description: Approval Types may only be deleted if they are not being used by an Approval remediation: Check to see if any Approval resources are linked to the supplied Approval Type x-apiture-traits: - api: title: Approvals basePath: approvals links: [getApprovals, createApproval, getApprovalTypes, createApprovalType, getApi, getApiDoc] - resource: name: approval description: >- An Approval record represents a blocking action that must be acknowledged in order to progress in the current process. simpleModelSchema: true - resource: name: approval type description: >- An Approval Type record contains information specific to the type of Approval being requested. All Aprovals will have Approval Types. simpleModelSchema: true