openapi: 3.0.0 servers: - url: 'https://api.devbank.apiture.com/cards' info: title: Cards description: | Monitor and manage debit cards associated with a bank account. This API defines models and operations for the following resources: * ***Card Requests*** represent customer-initiated requests for new cards or for replacements for lost, stolen, or damaged cards. * ***Cards*** represent physical debit cards issued by the financial institution (FI) to the bank customer. A card is associated with a deposit account. This API provides the following features to customers (the card holder): * List their cards and other cards on accounts, optionally filtered by account * View the details of each card, including its state and associated banking account number * Request a new card for an account * Lock a card so that it may not be used until the customer unlocks it * Unlock a card * Report a card as lost, stolen, or damaged * Close (cancel) a card * Request a replacement card for a lost, stolen, or damaged card * Review the status of their new or replacement card requests Only the card holder (the individual the card is issued to) may access the card control and card replacement operations. This API provides the following features to financial institution administrative users: * Reject a user's card request Additionally, administrative users may perform the following operations on behalf of the customer: * Create new or replacement cards * Activate a new or replacement card * Lock or unlock cards * Close (cancel) a card ## Multi-factor authentication challenges To prevent account takeover attacks, some operations to request cards or to operate on cards require _multi-factor authentication_ (MFA). An MFA _challenge_ is a process to verify the user's identity through one or more additional authentication steps. For example, when the client tries the [`createCardRequest`](#op-createCardRequest) without a valid redeemable `Apiture-Challenge` request header, the operation may fail with a 409 Conflict. The response body, defined by the [`challengeErrorResponse`](#schema-challengeErrorResponse) schema, contains a `challenge` resource which includes one or more _authenticators_. An authenticator may require the user to enter a verification code sent to the user's email account or mobile phone. (The client may let the user choose which authenticators to use, if there are more options than the required minimum.) Next, the client should start least one of the authenticators. The user completes the authenticator(s), for example by entering the verification code. Once the user has completed all the authenticators successfully, the client passes the resource ID of the challenge resource in the `Apiture-Challenge` request header to continue the operation that required MFA. Thus, these operations may require two tries: the first (without the `Apiture-Challenge` header), which fails with a 409 status (the response contains the challenge object), then after completing the challenges' authenticators, a second try, passing in the `Apiture-Challenge` header. # Error Types Error responses in this API may have one of the `type` values described below. See [Errors](https://developer.apiture.com/docs/concepts/errors) for more information on error responses and error types. ## cardRequestRefNotFound **Description**: The request card request resource ID does not identify a card.
**Remediation**: Pass the ID of an existing card request resource. ## cardRefNotFound **Description**: The request card resource ID does not identify a card.
**Remediation**: Pass the ID of an existing card resource. ## invalidAccountLink **Description**: The request contains an invalid reference to an account.
**Remediation**: Pass the URI of a valid account that the current user holds. ## missingApitureChallengeHeader **Description**: The Apiture-Challenge request header was not passed.
**Remediation**: Pass the _id of a valid, verified challenge resource in the Apiture-Challenge request header. ## productDoesNotSupportCards **Description**: The banking product associated with the account does not support card requests.
**Remediation**: Select an account that supports cards. ## challengedExpired **Description**: The challenge resource specified in the Apiture-Challenge request header has expired.
**Remediation**: Obtain a new challenge resource. ## challengedNotVerified **Description**: The challenge resource specified in the Apiture-Challenge request header has not been verified.
**Remediation**: Complete the challenge verification before using a challenge resource. ## challengedAlreadyRedeemed **Description**: The challenge resource specified in the Apiture-Challenge request header has been redeemed the maximum number of times.
**Remediation**: Obtain a new challenge resource. version: 0.15.1 contact: name: Apiture url: 'https://developer.apiture.com' email: api@apiture.com termsOfService: 'https://developer.apiture.com/docs/Apiture-Open-API-License-Agreement.pdf' tags: - name: Card Requests description: Requests to Issue New or Replacement Cards - name: Card Request Actions description: Actions on Card Requests - name: Cards description: Debit Cards Issued by the Financial Institution - name: Card Actions description: Actions on Debit cards - name: API description: The Cards API paths: /cardRequests: get: summary: Return a collection of card requests description: |- Return a [paginated](http://developer.apiture.com/docs/concepts/pagination) [sortable](http://developer.apiture.com/docs/concepts/sorting) [filterable](http://developer.apiture.com/docs/concepts/filtering) [searchable](http://developer.apiture.com/docs/concepts/searching) collection of requests for new or replacement card. The [links](http://developer.apiture.com/docs/concepts/links) in the response include pagination links. For financial institution customers, this collection only returns card requests that the customer has created or which apply to their cards. operationId: getCardRequests tags: - Card Requests x-apiture-traits: sortBy: - state - submittedAt - resolvedAt - updatedAt filters: description: filter: - contains - search resolutionReason: filter: - contains - search state: filter: - eq - ne - in submittedOn: filter: - eq - ne - lt - le - gt - ge - in as: date(submittedAt) resolvedOn: filter: - eq - ne - lt - le - gt - ge - in as: date(resolveAt) modifiedOn: filter: - eq - ne - lt - le - gt - ge - in as: date(updatedAt) updatedAt: filter: - eq - ne - lt - le - gt - ge multiMatch: false updatedBy: filter: - eq - ne - lt - le - gt - ge - startsWith - endsWith - contains - search parameters: - name: start in: query description: The zero-based index of the first card request item to include in this page. The default 0 denotes the beginning of the collection. schema: type: integer format: int64 default: 0 - name: limit in: query description: The maximum number of card request representations to return in this page. schema: type: integer format: int32 default: 100 - name: sortBy in: query description: 'Optional sort criteria. See [sort criteria format](http://developer.apiture.com/docs/concepts/sorting), such as `?sortBy=field1,-field2`.' schema: type: string - $ref: '#/components/parameters/filterQueryParam' - $ref: '#/components/parameters/qQueryParam' - name: state in: query description: >- Filter responses to list only cards in the listed `state` or `|`-separated set of states. Examples: `?state=submitted` , `?state=canceled|completed|rejected` schema: type: string enum: - pending - submitted - canceled - rejected - completed - name: submittedOn in: query description: >- Filter the response to card requests submitted on this date or set of `|`-separated dates. Dates are in [RFC 3339](https://tools.ietf.org/html/rfc3339) YYYY-MM-DD format. Examples: `?submittedDate=2019-06-10` or `?submittedDate=2019-06-10|2019-06-08|2019-06-07` schema: type: string format: date - name: modifiedOn in: query description: >- Filter the response to card requests last modified on this date or set of `|`-separated dates. Dates are in [RFC 3339](https://tools.ietf.org/html/rfc3339) YYYY-MM-DD format. Examples: `?modifiedOn=2019-06-10` or `?modifiedOn=2019-06-10|2019-06-08|2019-06-07` schema: type: string format: date - name: resolvedOn in: query description: >- Filter the response to card requests resolved on this date or set of `|`-separated dates. Dates are in [RFC 3339](https://tools.ietf.org/html/rfc3339) YYYY-MM-DD format. Examples: `?resolvedOn=2019-06-10` or `?resolvedOn=2019-06-10|2019-06-08|2019-06-07` schema: type: string format: date - name: updatedBy in: query description: Filter the response to card requests created by the user named by this user ID. schema: type: string responses: '200': description: OK content: application/hal+json: schema: $ref: '#/components/schemas/cardRequests' application/json: schema: $ref: '#/components/schemas/cardRequests' '400': $ref: '#/components/responses/400' '422': $ref: '#/components/responses/422' security: - apiKey: [] accessToken: - card/read post: summary: Request a new or replacement card description: >- Request a new or replacement card by creating a new card request resource, adding it to the `cardRequests` collection. This operation may require the user to complete an additional multi-factor authentication (MFA) challenge if the financial institution has configured MFA on new or replacement card requests. If the request fails because MFA is required, the response code is 409 and the `_error.type` in the response is `missingApitureChallengeHeader`. The client should complete the MFA challenge and retry the operation with the `Apiture-Challenge` request header as described in [Multi-factor authentication challenges](#MFA) above. operationId: createCardRequest tags: - Card Requests parameters: - $ref: '#/components/parameters/apitureChallengeHeaderParam' responses: '201': description: Created headers: Location: description: >- The URI of the new resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with *`scheme`*`://host` schema: type: string format: uri ETag: description: >- 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. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/cardRequest' application/json: schema: $ref: '#/components/schemas/cardRequest' '400': $ref: '#/components/responses/400' '409': description: >- Conflict. The request is not allowed or requires a valid `Apiture-Challenge` header The error response will contain a challenge object and one or more authenticators for the client to start and complete before retrying. See See [Multi-factor authentication challenges](#MFA) above. This error response may have one of the following `type` values: * [`missingApitureChallengeHeader`](#err-missingApitureChallengeHeader) * [`challengedNotVerified`](#err-challengedNotVerified) * [`challengedExpired`](#err-challengedExpired) * [`challengedAlreadyRedeemed`](#err-challengedAlreadyRedeemed) * [`productDoesNotSupportCards`](#err-productDoesNotSupportCards) x-apiture-errors: - missingApitureChallengeHeader - challengedNotVerified - challengedExpired - challengedAlreadyRedeemed - productDoesNotSupportCards content: application/hal+json: schema: $ref: '#/components/schemas/challengeErrorResponse' application/json: schema: $ref: '#/components/schemas/challengeErrorResponse' security: - apiKey: [] accessToken: - card/write requestBody: content: application/hal+json: schema: $ref: '#/components/schemas/createCardRequest' application/json: schema: $ref: '#/components/schemas/createCardRequest' description: The data necessary to create a new card request resource. required: true '/cardRequests/{cardRequestId}': get: summary: Fetch a representation of this card request description: 'Return a [HAL](http://developer.apiture.com/docs/concepts/hal) representation of this card request resource.' operationId: getCardRequest tags: - Card Requests parameters: - $ref: '#/components/parameters/cardRequestIdPathParam' - $ref: '#/components/parameters/ifNoneMatchHeaderParam' responses: '200': description: OK headers: ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this card request resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/cardRequest' application/json: schema: $ref: '#/components/schemas/cardRequest' '304': $ref: '#/components/responses/304' '404': $ref: '#/components/responses/404CardRequest' security: - apiKey: [] accessToken: - card/read delete: summary: Delete this card request resource description: >- Delete this card request resource and any resources that are owned by it. This effectively cancels the card request request if the request has not been processed. operationId: deleteCardRequest x-apiture-implemented: false tags: - Card Requests parameters: - $ref: '#/components/parameters/cardRequestIdPathParam' responses: '204': $ref: '#/components/responses/204Deleted' security: - apiKey: [] accessToken: - card/delete /shippingCharges: post: summary: Get estimated (expedited) shipping changes description: Get estimated expedited shipping changes for a card. operationId: estimateCardShippingCharges tags: - Card Requests security: - apiKey: [] accessToken: - data/read responses: '200': description: OK. content: application/hal+json: schema: $ref: '#/components/schemas/cardShippingEstimate' application/json: schema: $ref: '#/components/schemas/cardShippingEstimate' '400': $ref: '#/components/responses/400' '422': $ref: '#/components/responses/422CardShippingEstimate' requestBody: content: application/hal+json: schema: $ref: '#/components/schemas/cardShippingEstimateRequest' application/json: schema: $ref: '#/components/schemas/cardShippingEstimateRequest' description: Information required to estimate the shipping. required: true /completedCardRequests: post: operationId: completeCardRequest summary: Complete a card request description: >- Mark a card request as completed when the card has been issued. This changes the `state` property of the card request to `completed`. This operation is available via the `apiture:complete` link on the card request resource, if and only if the card request is eligible for the complete operation. Only the FI admin may invoke this operation. The response is the updated representation of the card request. The `If-Match` request header value must match the current entity tag value of the card request. tags: - Card Requests Actions parameters: - $ref: '#/components/parameters/cardRequestQueryParam' - $ref: '#/components/parameters/ifMatchHeaderParam' responses: '200': description: OK. The operation succeeded. The card request was updated and its `state` changed to `completed`. 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 the resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/cardRequest' application/json: schema: $ref: '#/components/schemas/cardRequest' '400': $ref: '#/components/responses/400CompleteCardRequest' '409': $ref: '#/components/responses/409CompleteCardRequestConflict' '412': $ref: '#/components/responses/412' security: - apiKey: [] accessToken: - admin/write /rejectedCardRequests: post: operationId: rejectCardRequest summary: Reject a card request description: |- Mark a card request as _rejected_. This changes the `state` property of the card request to `rejected`. Only the FI admin may invoke this operation. This operation is available via the `apiture:reject` link on the card request resource, if and only if the card request is eligible for the reject operation. The response is the updated representation of the card request. The `If-Match` request header value, if passed, must match the current entity tag value of the card request. tags: - Card Requests Actions parameters: - $ref: '#/components/parameters/cardRequestQueryParam' - $ref: '#/components/parameters/ifMatchHeaderParam' responses: '200': description: OK. The operation succeeded. The card request was updated and its `state` changed to `rejected`. 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 the resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/cardRequest' application/json: schema: $ref: '#/components/schemas/cardRequest' '400': $ref: '#/components/responses/400RejectCardRequest' '409': $ref: '#/components/responses/409RejectCardRequestConflict' '412': $ref: '#/components/responses/412' security: - apiKey: [] accessToken: - admin/write /canceledCardRequests: post: operationId: cancelCardRequest summary: Cancel a card request description: >- Cancel a card replacement request. This changes the `state` property of the card request to `canceled`. This operation is available via the `apiture:cancel` link on the card request resource, if and only if the card request is eligible for the cancel operation. The response is the updated representation of the card request. The `If-Match` request header value, if passed, must match the current entity tag value of the card request. tags: - Card Requests Actions parameters: - $ref: '#/components/parameters/cardRequestQueryParam' - $ref: '#/components/parameters/ifMatchHeaderParam' responses: '200': description: OK. The operation succeeded. The card request was updated and its `state` changed to `canceled`. 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 the resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/cardRequest' application/json: schema: $ref: '#/components/schemas/cardRequest' '400': $ref: '#/components/responses/400CancelCardRequest' '409': $ref: '#/components/responses/409CancelCardRequestConflict' '412': $ref: '#/components/responses/412' security: - apiKey: [] accessToken: - card/write /cards: get: summary: Return a collection of cards description: |- Return a [paginated](http://developer.apiture.com/docs/concepts/pagination) [sortable](http://developer.apiture.com/docs/concepts/sorting) [filterable](http://developer.apiture.com/docs/concepts/filtering) [searchable](http://developer.apiture.com/docs/concepts/searching) collection of cards for the user's accounts or the subset of those cards that satisfy the filter criteria. [links](http://developer.apiture.com/docs/concepts/links) in the response include pagination links. For an account owner or joint owner of a personal account, the default response includes all cards issued to all primary or joint owners of the account. For authorized signers on business accounts, the default response includes cards for all authorized signers for that account. There is another version of this operation which allows getting a list of cards based on the query constraints passed in the request body; see the `getCardsForAccount` operation. operationId: getCards tags: - Cards x-apiture-traits: sortBy: - accountName - state - replacementState - fulfillmentState - updatedAt filters: account: filter: - eq - ne - in accountName: filter: - eq - ne - lt - le - gt - ge - startsWith - endsWith - contains - search accountCategory: filter: - eq - ne - in accountType: filter: - eq - ne - in state: filter: - eq - ne - in replacementState: filter: - eq - ne - in fulfillmentState: filter: - eq - ne - in updatedAt: filter: - eq - ne - lt - le - gt - ge multiMatch: false modifiedOn: filter: - eq - ne - lt - le - gt - ge - in as: date(updatedAt) issuedOn: filter: - eq - ne - lt - le - gt - ge - in as: date(issuedAt) expiresOn: filter: - eq - ne - lt - le - gt - ge - in as: date(expiresAt) parameters: - name: start in: query description: The zero-based index of the first card item to include in this page. The default 0 denotes the beginning of the collection. schema: type: integer format: int64 default: 0 - name: limit in: query description: The maximum number of card representations to return in this page. schema: type: integer format: int32 default: 100 - name: sortBy in: query description: 'Optional sort criteria. See [sort criteria format](http://developer.apiture.com/docs/concepts/sorting), such as `?sortBy=field1,-field2`.' schema: type: string - $ref: '#/components/parameters/filterQueryParam' - $ref: '#/components/parameters/qQueryParam' - $ref: '#/components/parameters/unmaskedQueryParam' - name: mine description: 'If `true`, limit the response to only cards issued to the user making the request.' in: query schema: type: boolean default: false - name: account in: query description: >- Filter cards to only those for the account with the account ID named in this query parameter. (By default, the list is pre-filtered to only accounts that the user has access to; this further narrows that list. FI admins can use this to view cards for a user.) This can match exactly one account ID, or a set of `|`-separated IDs This parameter is mutually exclusive with `?accountName=`. Examples: `?account=a223db933809` or `?account=a223db933809|fd89d651283b`. style: pipeDelimited schema: type: array items: type: string - name: accountName in: query description: >- Filter cards to those whose account name matches this value. This can match exactly one account name, or a set of `|`-separated names. This parameter is mutually exclusive with `?account=`. Examples: `?accountName=My%20Basic%20Savings` or `?accountName=My%20Basic%20Savings|My%20Joint%02Savings`. style: pipeDelimited schema: type: array items: type: string - name: state in: query description: >- Filter cards on the state of the card. This can match exactly one state, or a set of `|`-separated states. Examples: `?state=requested` , `?state=lost|stolen|damaged`. schema: type: string items: type: string enum: - requested - issued - active - locked - lost - stolen - damaged - closed - name: fulfillmentState in: query description: >- Filter the response to card by the state of their replacement states. This can match exactly one state, or a set of `|`-separated states. Examples: `?fulfillmentState=requested` , `?fulfillmentState=ordered|reordered` style: pipeDelimited schema: type: array items: type: string enum: - none - requested - ordered - issued - shipped - rejected - name: modifiedOn in: query description: >- Filter the response to cards last modified on this date or set of `|`-separated dates. Dates are in [RFC 3339](https://tools.ietf.org/html/rfc3339) YYYY-MM-DD format. Examples: `?modifiedOn=2019-06-10` , `?modifiedOn=2019-06-10|2019-06-08|2019-06-07` style: pipeDelimited schema: type: array items: type: string format: date - name: issuedOn in: query description: >- Filter the response to cards issued on this date or set of `|`-separated dates. Dates are in [RFC 3339](https://tools.ietf.org/html/rfc3339) YYYY-MM-DD format. Examples: `?issuedOn=2019-06-10` , `?issuedOn=2019-06-10|2019-06-08|2019-06-07` style: pipeDelimited schema: type: array items: type: string format: date - name: updatedBy in: query description: Filter the response to card requests created by the user named by this user ID. schema: type: string responses: '200': description: OK content: application/hal+json: schema: $ref: '#/components/schemas/cards' application/json: schema: $ref: '#/components/schemas/cards' '400': $ref: '#/components/responses/400' '422': $ref: '#/components/responses/422' security: - apiKey: [] accessToken: - card/read post: summary: Create a new card description: >- Create a new card resource that represents a physical debit card. The URI to the associated account should be passed in the request in the link named `apiture:account'. Only administrative applications can create cards. operationId: createCard x-apiture-implemented: false tags: - Cards responses: '201': description: Created headers: Location: description: >- The URI of the new resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with *`scheme`*`://host` schema: type: string format: uri ETag: description: >- 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. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/card' application/json: schema: $ref: '#/components/schemas/card' '400': $ref: '#/components/responses/400' '409': description: |- Conflict. The request is not allowed for the selected account or banking product. This error response may have one of the following `type` values: * [`productDoesNotSupportCards`](#err-productDoesNotSupportCards) x-apiture-errors: - productDoesNotSupportCards content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' security: - apiKey: [] accessToken: - admin/write requestBody: content: application/hal+json: schema: $ref: '#/components/schemas/createCard' application/json: schema: $ref: '#/components/schemas/createCard' description: The data necessary to create a new card. required: true '/cards/{cardId}': get: summary: Fetch a representation of this card description: 'Return a [HAL](http://developer.apiture.com/docs/concepts/hal) representation of this card resource.' operationId: getCard tags: - Cards parameters: - $ref: '#/components/parameters/cardIdPathParam' - $ref: '#/components/parameters/ifNoneMatchHeaderParam' - $ref: '#/components/parameters/unmaskedQueryParam' responses: '200': description: OK headers: ETag: description: >- The `ETag` response header specifies an entity tag which must be provided in an `If-Match` request header for *`PUT`* or *`PATCH`* operations which update this card resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/card' application/json: schema: $ref: '#/components/schemas/card' '304': $ref: '#/components/responses/304' '404': $ref: '#/components/responses/404Card' security: - apiKey: [] accessToken: - card/read /issuerParameters: post: summary: Generate card issuer parameters description: >- Generate parameters for integrating with the card issuer. The client may embed a secure application component. This operation fetches parameters to allow this integration, based on the current user and optionally a card. There is no request body for this operation. operationId: createCardIssuerParameters parameters: - name: card in: query description: >- The optional resource identifier of an existing card. This is the card's `_id` property, **not** the card/account number. Use this to request parameters for the card issuer integration to change the card's PIN. schema: type: string - name: issuer in: query required: true description: 'The name of the card issuer, such as `marqueta`. This determines which issue parameters are returned to the client.' schema: type: string tags: - Card Requests responses: '201': description: Created. The response contains the parameters to integrate with the card issuer components. content: application/hal+json: schema: $ref: '#/components/schemas/cardIssuerParameters' application/json: schema: $ref: '#/components/schemas/cardIssuerParameters' '400': description: Bad Request. The parameters are not well-formed. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' '422': description: |- Unprocessable Entity. The parameters, while well-formed, are invalid. This error response may have one of the following `type` values: * [`cardRefNotFound`](#err-cardRefNotFound) x-apiture-errors: - cardRefNotFound content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' security: - apiKey: [] accessToken: - card/read /activeCards: post: operationId: activateCard summary: Activate a card description: |- Activate a card so a customer can use it and change the card's `state` property to `active`. Services or administrative users may activate a `requested` card after a card request has been approved. Customers may _not_ use this operation for activating new cards. This operation is available via the `apiture:activate` link on the card resource, if and only if the activation operation is available. The response is the updated representation of the card. The `If-Match` request header value must match the current entity tag value of the card. tags: - Card Actions parameters: - $ref: '#/components/parameters/cardsQueryParam' - $ref: '#/components/parameters/ifMatchHeaderParam' responses: '200': description: OK. The operation succeeded. The card was updated and its `state` changed to `active`. 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 the resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/card' application/json: schema: $ref: '#/components/schemas/card' '400': $ref: '#/components/responses/400ActivateCard' '409': $ref: '#/components/responses/409ActivateCardConflict' '412': $ref: '#/components/responses/412' security: - apiKey: [] accessToken: - card/write /lockedCards: post: operationId: lockCard summary: Lock a card description: |- Lock a card so that it cannot be used for debits or other financial activity. (This differs from locking the entire account.) This is also referred to a _placing a hold on the card_. This is one step before reporting a card as lost or stolen. A user can unlock the card (restore it to the normal, active state) by using the `apiture:unlock` link which invokes the [`unlockCard`](#op-unlockCard) operation. This is a self-service operation which a card holder may take if they want to prevent fraudulent use of the card, such as if they have misplaced it (but expect to find it again), or will be out of the country. This operation changes the `state` property of the card to `locked`. This operation is available via the `apiture:lock` link on the card resource, if and only if the card is eligible for the lock operation. The response is the updated representation of the card. The `If-Match` request header value must match the current entity tag value of the card. Only the card holder or an admin can lock a card. tags: - Card Actions parameters: - $ref: '#/components/parameters/cardsQueryParam' - $ref: '#/components/parameters/ifMatchHeaderParam' responses: '200': description: OK. The operation succeeded. The card was updated and its `state` changed to `locked`. 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 the resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/card' application/json: schema: $ref: '#/components/schemas/card' '400': $ref: '#/components/responses/400LockCard' '409': $ref: '#/components/responses/409LockCardConflict' '412': $ref: '#/components/responses/412' security: - apiKey: [] accessToken: - card/write /unlockedCards: post: operationId: unlockCard summary: Unlock a card description: |- Unlock a locked card so that it can be used for debits or other financial activity. This changes the `state` property of the card back to `active`. This operation is available via the `apiture:unlock` link on the card resource, if and only if the card is currently `locked`. The response is the updated representation of the card. The `If-Match` request header value, if passed, must match the current entity tag value of the card. Only the card holder or an admin can unlock a card. tags: - Card Actions parameters: - $ref: '#/components/parameters/cardsQueryParam' - $ref: '#/components/parameters/ifMatchHeaderParam' responses: '200': description: OK. The operation succeeded. The card was updated and its `state` changed to `active`. 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 the resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/card' application/json: schema: $ref: '#/components/schemas/card' '400': $ref: '#/components/responses/400UnlockCard' '409': $ref: '#/components/responses/409UnlockCardConflict' '412': $ref: '#/components/responses/412' security: - apiKey: [] accessToken: - card/write /closedCards: post: operationId: closeCard summary: Close a card description: >- Close a card by adding it to the set of closed cards. This changes the `state` property of the card to `closed`. This operation is available via the `apiture:close` link on the card resource, if and only if the card is eligible for the close operation. The response is the updated representation of the card. The `If-Match` request header value, if passed, must match the current entity tag value of the card. Only the card holder or an admin can close a card. tags: - Card Actions parameters: - $ref: '#/components/parameters/cardsQueryParam' - $ref: '#/components/parameters/ifMatchHeaderParam' responses: '200': description: OK. The operation succeeded. The card was updated and its `state` changed to `closed`. 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 the resource. schema: type: string content: application/hal+json: schema: $ref: '#/components/schemas/card' application/json: schema: $ref: '#/components/schemas/card' '400': $ref: '#/components/responses/400CloseCard' '409': $ref: '#/components/responses/409CloseCardConflict' '412': $ref: '#/components/responses/412' security: - apiKey: [] accessToken: - card/write /labels: get: summary: Localized Labels description: >- Return a JSON object which defines labels for enumeration types defined by the schemas defined in this API. The labels in the response may not all match the requested language; some may be in the default language (`en-us`). operationId: getLabels security: - apiKey: [] parameters: - name: Accept-Language in: header description: >- The weighted language tags which indicate the user's preferred natural language for the localized labels in the response, as per [RFC 7231](https://tools.ietf.org/html/rfc7231#section-5.3.5). schema: type: string responses: '200': description: OK content: application/hal+json: schema: $ref: '#/components/schemas/localizedLabels' application/json: schema: $ref: '#/components/schemas/localizedLabels' tags: - API /: get: summary: Top-level resources and operations in this API description: Return links to the top-level resources and operations in this API. operationId: getApi responses: '200': description: OK content: application/hal+json: schema: $ref: '#/components/schemas/root' application/json: schema: $ref: '#/components/schemas/root' tags: - API security: - apiKey: [] /apiDoc: get: summary: Return API definition document description: Return the OpenAPI document that describes this API. operationId: getApiDoc responses: '200': description: OK content: application/json: schema: type: object application/openapi+json;version=2.0: schema: type: object application/openapi+yaml;version=2.0: schema: type: object application/hal+json: schema: type: object tags: - API security: - apiKey: [] x-apiture-errors: cardRequestRefNotFound: description: The request card request resource ID does not identify a card remediation: Pass the ID of an existing card request resource cardRefNotFound: description: The request card resource ID does not identify a card remediation: Pass the ID of an existing card resource invalidAccountLink: description: The request contains an invalid reference to an account remediation: Pass the URI of a valid account that the current user holds. missingApitureChallengeHeader: description: The Apiture-Challenge request header was not passed remediation: 'Pass the _id of a valid, verified challenge resource in the Apiture-Challenge request header.' productDoesNotSupportCards: description: The banking product associated with the account does not support card requests. remediation: Select an account that supports cards. challengedExpired: description: The challenge resource specified in the Apiture-Challenge request header has expired remediation: Obtain a new challenge resource challengedNotVerified: description: The challenge resource specified in the Apiture-Challenge request header has not been verified remediation: Complete the challenge verification before using a challenge resource challengedAlreadyRedeemed: description: The challenge resource specified in the Apiture-Challenge request header has been redeemed the maximum number of times remediation: Obtain a new challenge resource x-apiture-traits: - api: name: Cards links: - getApi - getApiDoc - getLabels - getCards - createCardRequest - getCards - createCard - estimateCardShippingCharges - resource: name: card description: Debit cards associated with a banking account and credit cards. excludeMethods: - put - patch - resource: name: card request description: 'A request to issue a new card or to replace a lost, stolen, or damaged card.' excludeMethods: - put - patch - state: name: card verb: activate state: active - state: name: card verb: lock state: locked - state: name: card verb: close state: closed - state: name: card request verb: cancel state: canceled - state: name: card request verb: reject state: rejected - state: name: card request verb: complete state: completed - labels: applied: true - security: baseScope: card x-apiture-annotated-at: '2020-08-12T16:15:09.192Z' components: schemas: createCard: title: Create Card (v2.0.0) description: Representation used to create a new card. x-apiture-version: 2.0.0 required: - accountName example: _profile: 'https://api.apiture.com/schemas/cards/createCard/v2.0.0/profile.json' accountName: My Premiere Savings _links: 'apiture:account': href: /accounts/accounts/e7076b86-0f0b-4126-92eb-d90f4be1ae6a x-apiture-composition: - $ref: '#/components/schemas/abstractResource' - $ref: '#/components/schemas/cardFields' properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' allOf: - $ref: '#/components/schemas/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/components/schemas/error' accountName: description: The name of the account that this card is tied to. type: string minLength: 1 maxLength: 128 example: Premiere Checking readOnly: true accountNumbers: description: >- The masked and (optionally) full number for the account this card is associated with. This is derived from the account used in the initial card request. By default, only the `masked` number is returned; use `?unmasked=true` to reveal the `full` account number. allOf: - $ref: '#/components/schemas/accountNumbers' readOnly: true type: object x-apiture-flattened: true summaryCard: title: Card Summary (v2.0.0) description: >- Summary representation of a card resource in cards collections. This representation normally does not contain any `_embedded` objects. If needed, call the `GET` operation on the item's `self` link to get `_embedded` objects. x-apiture-version: 2.0.0 example: _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'https://api.apiture.com/schemas/cards/summaryCard/v2.0.0/profile.json' holderName: LUCILLE WELLPHUNDED label: Premiere Checking *3210 accountName: Premiere Checking accountNumbers: masked: '*************3210' full: '9876543210' cardNumbers: masked: '************3210' state: active fulfillmentState: shipped fulfillmentDescription: 'Shipped on June 7, 2020' issuedAt: '2019-06-07T05:18:30.375Z' updatedAt: '2019-06-07T05:18:30.375Z' mine: true updatedBy: lucy.wellphunded@bankcustomer.example.com expiresOn: '2012-04-30' _embedded: {} _links: self: href: /cards/cards/0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:lock': href: /cards/lockedCards?card=0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:account': href: /accounts/accounts/d62c0701-0d74-4836-83f9-ebf3709442ea x-apiture-composition: - $ref: '#/components/schemas/abstractResource' - $ref: '#/components/schemas/cardFields' - properties: - _id - label - holderName - cardNumbers - fulfillmentState - fulfillmentDescription - mine - state - issuedAt - activatedAt - expiresOn - updatedAt - updatedBy properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' allOf: - $ref: '#/components/schemas/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/components/schemas/error' accountName: description: The name of the account that this card is tied to. type: string minLength: 1 maxLength: 128 example: Premiere Checking readOnly: true accountNumbers: description: >- The masked and (optionally) full number for the account this card is associated with. This is derived from the account used in the initial card request. By default, only the `masked` number is returned; use `?unmasked=true` to reveal the `full` account number. allOf: - $ref: '#/components/schemas/accountNumbers' readOnly: true _id: description: The unique identifier for this card resource. This is an immutable opaque string. readOnly: true type: string label: description: The text label for this card. type: string minLength: 1 maxLength: 128 readOnly: true example: My debit card for Premiere Checking holderName: description: 'The card holder''s full name, as it appears on the card. This value is often ALL CAPS.' type: string example: LUCILLE WELLPHUNDED readOnly: true cardNumbers: description: The masked and full card number this card. allOf: - $ref: '#/components/schemas/cardNumbers' readOnly: true fulfillmentState: description: Indicates the state of a card replacement request. The user cannot change this property. allOf: - $ref: '#/components/schemas/cardFulfillmentState' readOnly: true example: replacedWithNewNumber fulfillmentDescription: description: The card provider's explanation of the current `fulfillmentState`. type: string readOnly: true mine: description: >- If `true`, the card is owned by the user making the request. By default a user can view all cards for a given Account, but they may only take action on cards they own. type: boolean readOnly: true state: description: The state of this card. This is derived. allOf: - $ref: '#/components/schemas/cardState' readOnly: true issuedAt: description: >- The date-time when this card was issued. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC format. This field is present only after the card has been issued, _and_ if the card vendor provides the time stamp. type: string format: date-time example: {} readOnly: true activatedAt: description: >- The date-time when this card was activated. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC format. This field is present only after the card has been activated, _and_ if the card vendor provides the time stamp. type: string format: date-time example: {} readOnly: true expiresOn: description: >- The card's expiration date. The day should is the last day of the month, such as 2021-10-31 if the card expires at the end of October, 2021. in [RFC 3339](https://tools.ietf.org/html/rfc3339) `YYYY-MM-DD` format. type: string format: date example: '2012-04-30' readOnly: true updatedAt: description: >- The date-time when this card's state or other attributes were last changed. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC format. type: string format: date-time example: {} readOnly: true updatedBy: description: 'The username of the person who last modified this card resource. ' type: string readOnly: true example: lucy.wellphunded@bankcustomer.example.com type: object x-apiture-flattened: true cardState: title: Card State (v1.0.0) description: | The state of a card. cardState strings may have one of the following [enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations) values (described by the named cardState) These enumeration values are further described by the [label group](https://developer.apiture.com/concepts/label-groups) named `cardState` in the response from the [`getLabels`](#op-getLabels) operation.
ValueDescription
unknownUnknown
requestedRequested: The used has submitted the request to issue the card but the request has not been completed.
issuedIssued: The card has been issued but the card holder has not activated it.
activeActive: The card has been issued and activated an is available for use.
lockedLocked: The user has requested that the card be locked so that it may not be used. This is useful if they have misplaced the card but do not yet want to report it as lost.
lostReported as lost: The user has reported the card as lost. The card is disabled. A new card (with a new card number) will be issued.
stolenReported as stolen: The user has reported the card as stolen. The card is disabled. A new card (with a new card number) will be issued.
damagedReported as damaged: The user has reported the card as stolen. A new card with the same card number will be issued.
frozenFrozen: The financial institution has frozen the card or the account associated with this card.
closedClosed: The card has been closed at the card holder's request or by the financial institution. The card is disabled and the card holder cannot use it for banking activity.
type: string enum: - unknown - requested - issued - active - locked - lost - stolen - damaged - frozen - closed x-apiture-enum: cardState x-apiture-version: 1.0.0 x-apiture-flattened: true cardReplacementState: description: | The state of a card replacement request. cardReplacementState strings may have one of the following [enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations) values (described by the named cardReplacementState) These enumeration values are further described by the [label group](https://developer.apiture.com/concepts/label-groups) named `cardReplacementState` in the response from the [`getLabels`](#op-getLabels) operation.
ValueDescription
noneNone: No card replacement requests are active.
requestedRequested: The user has requested a card replacement.
orderedOrdered: The card replacement order has been sent to the card provider.
issuedIssued: The card has been issued by the card provider.
shippedShipped: The issued card has been shipped by the card provider.
replacedWithSameNumberReplaced with same card number: The card for this account number has been replaced; the card has been issued, shipped, and activated.
replacedWithNewNumberReplaced with new card number: The card for this account has been replaced with a new card and new card number; the card has been issued, shipped, and activated.
title: Card Replacement State (v1.0.0) type: string enum: - none - requested - ordered - issued - shipped - replacedWithSameNumber - replacedWithNewNumber - rejected x-apiture-enum: cardReplacementState x-apiture-version: 1.0.0 x-apiture-flattened: true cardFulfillmentState: description: | The state of a card order fulfillment from the provider. cardFulfillmentState strings may have one of the following [enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations) values (described by the named cardReplacementState) These enumeration values are further described by the [label group](https://developer.apiture.com/concepts/label-groups) named `cardReplacementState` in the response from the [`getLabels`](#op-getLabels) operation.
ValueDescription
noneNone: No card replacement requests are active.
requestedRequested: The user has requested a card replacement.
orderedOrdered: The card replacement order has been sent to the card provider.
issuedIssued: The card has been issued by the card provider.
shippedShipped: The issued card has been shipped by the card provider.
replacedWithSameNumberReplaced with same card number: The card for this account number has been replaced; the card has been issued, shipped, and activated.
replacedWithNewNumberReplaced with new card number: The card for this account has been replaced with a new card and new card number; the card has been issued, shipped, and activated.
title: Card Fulfillment State (v1.0.0) type: string enum: - none - requested - ordered - reordered - issued - shipped - rejected x-apiture-enum: cardReplacementState x-apiture-version: 1.0.0 x-apiture-flattened: true card: title: Card (v2.0.0) description: > A card resource, which represents physical Debit cards associated with a banking account or credit cards. The default representation includes only a masked card number. Use `?unmasked=true` on the request to include the full card number. The hypermedia `_links` in the response (listed below) include several action links which change the state of the card. These links should be used with the `POST` verb (see [Resource sets](https://developer.apiture.com/docs/concepts/resource-sets/)). Response and request bodies using this card schema may contain the following links:
RelSummaryMethod
selfFetch a representation of this cardGET
apiture:account The Account associated with this cardGET
apiture:unlockUnlock a cardPOST
apiture:closeClose a cardPOST
apiture:lockLock a cardPOST
apiture:activateActivate a cardPOST
apiture:replaceRequest a new or replacement cardPOST
x-apiture-version: 2.0.0 example: _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'https://api.apiture.com/schemas/cards/card/v2.0.0/profile.json' holderName: LUCILLE WELLPHUNDED name: My debit card for Premiere Checking accountName: Premiere Checking accountNumbers: masked: '*************3210' full: '9876543210' cardNumbers: masked: '************3210' state: active fulfillmentState: shipped fulfillmentDescription: 'Shipped on June 7, 2020' issuedAt: '2019-06-07T05:18:30.375Z' updatedAt: '2019-06-07T05:18:30.375Z' mine: true updatedBy: lucy.wellphunded@bankcustomer.example.com expiresOn: '2012-04-30' _embedded: {} _links: self: href: /cards/cards/0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:lock': href: /cards/lockedCards?card=0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:account': href: /accounts/accounts/d62c0701-0d74-4836-83f9-ebf3709442ea x-apiture-links: - rel: self operationId: getCard - rel: 'apiture:account' title: The Account associated with this card verb: get - rel: 'apiture:unlock' operationId: unlockCard - rel: 'apiture:close' operationId: closeCard - rel: 'apiture:lock' operationId: lockCard - rel: 'apiture:activate' operationId: activateCard - rel: 'apiture:replace' operationId: createCardRequest x-apiture-composition: - $ref: '#/components/schemas/summaryCard' properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' allOf: - $ref: '#/components/schemas/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/components/schemas/error' accountName: description: The name of the account that this card is tied to. type: string minLength: 1 maxLength: 128 example: Premiere Checking readOnly: true accountNumbers: description: >- The masked and (optionally) full number for the account this card is associated with. This is derived from the account used in the initial card request. By default, only the `masked` number is returned; use `?unmasked=true` to reveal the `full` account number. allOf: - $ref: '#/components/schemas/accountNumbers' readOnly: true _id: description: The unique identifier for this card resource. This is an immutable opaque string. readOnly: true type: string label: description: The text label for this card. type: string minLength: 1 maxLength: 128 readOnly: true example: My debit card for Premiere Checking holderName: description: 'The card holder''s full name, as it appears on the card. This value is often ALL CAPS.' type: string example: LUCILLE WELLPHUNDED readOnly: true cardNumbers: description: The masked and full card number this card. allOf: - $ref: '#/components/schemas/cardNumbers' readOnly: true fulfillmentState: description: Indicates the state of a card replacement request. The user cannot change this property. allOf: - $ref: '#/components/schemas/cardFulfillmentState' readOnly: true example: replacedWithNewNumber fulfillmentDescription: description: The card provider's explanation of the current `fulfillmentState`. type: string readOnly: true mine: description: >- If `true`, the card is owned by the user making the request. By default a user can view all cards for a given Account, but they may only take action on cards they own. type: boolean readOnly: true state: description: The state of this card. This is derived. allOf: - $ref: '#/components/schemas/cardState' readOnly: true issuedAt: description: >- The date-time when this card was issued. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC format. This field is present only after the card has been issued, _and_ if the card vendor provides the time stamp. type: string format: date-time example: {} readOnly: true activatedAt: description: >- The date-time when this card was activated. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC format. This field is present only after the card has been activated, _and_ if the card vendor provides the time stamp. type: string format: date-time example: {} readOnly: true expiresOn: description: >- The card's expiration date. The day should is the last day of the month, such as 2021-10-31 if the card expires at the end of October, 2021. in [RFC 3339](https://tools.ietf.org/html/rfc3339) `YYYY-MM-DD` format. type: string format: date example: '2012-04-30' readOnly: true updatedAt: description: >- The date-time when this card's state or other attributes were last changed. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC format. type: string format: date-time example: {} readOnly: true updatedBy: description: 'The username of the person who last modified this card resource. ' type: string readOnly: true example: lucy.wellphunded@bankcustomer.example.com type: object x-apiture-flattened: true cardFields: title: Card Fields (v2.0.0) description: 'Common fields of the card resource, used to build other model schemas.' x-apiture-fragment: true x-apiture-version: 2.0.0 properties: accountName: description: The name of the account that this card is tied to. type: string minLength: 1 maxLength: 128 example: Premiere Checking readOnly: true accountNumbers: description: >- The masked and (optionally) full number for the account this card is associated with. This is derived from the account used in the initial card request. By default, only the `masked` number is returned; use `?unmasked=true` to reveal the `full` account number. allOf: - $ref: '#/components/schemas/accountNumbers' readOnly: true type: object x-apiture-flattened: true cards: title: Card Collection (v2.0.0) description: |- Collection of cards. The items in the collection are ordered in the `_embedded.items` array; the `name` is `cards`. The top-level `_links` object may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`). x-apiture-version: 2.0.0 example: _profile: 'https://api.apiture.com/schemas/cards/cards/v2.0.0/profile.json' start: 10 limit: 10 count: 67 name: cards _links: self: href: /cards/cards?start=10&limit=10 first: href: /cards/cards?start=0&limit=10 next: href: /cards/cards?start=20&limit=10 collection: href: /cards/cards _embedded: items: _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'https://api.apiture.com/schemas/cards/card/v2.0.0/profile.json' holderName: LUCILLE WELLPHUNDED label: Premiere Checking *3210 accountName: Premiere Checking accountNumbers: masked: '*************3210' full: '9876543210' cardNumbers: masked: '************3210' state: active fulfillmentState: shipped fulfillmentDescription: 'Shipped on June 7, 2020' mine: true issuedAt: '2019-06-07T05:18:30.375Z' updatedAt: '2019-06-07T05:18:30.375Z' updatedBy: lucy.wellphunded@bankcustomer.example.com expiresOn: '2012-04-30' _links: self: href: /cards/cards/0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:account': href: /accounts/accounts/d62c0701-0d74-4836-83f9-ebf3709442ea x-apiture-composition: - $ref: '#/components/schemas/collection' - properties: - _embedded properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' allOf: - $ref: '#/components/schemas/links' _embedded: type: object description: Embedded objects. properties: items: description: An array containing a page of card items. type: array items: $ref: '#/components/schemas/summaryCard' _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/components/schemas/error' count: description: >- The number of items in the collection. This value is _optional_ and may be omitted if the count is not computable efficiently. If a filter is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the filter. type: integer start: description: The start index of this page of items. type: integer limit: description: The maximum number of items per page. type: integer name: description: The name of the collection. type: string type: object x-apiture-flattened: true createCardRequest: title: Create Card Request (v1.1.0) description: > Representation used to create a request for a new or replacement card. The `_links` in the request must contain a `apiture:account` link to the user's banking account; that account must allow card ordering (as contained in the banking product's `card` object; see the Products API.) Response and request bodies using this createCardRequest schema may contain the following links:
RelSummaryMethod
apiture:account The banking account associated with the cardGET
x-apiture-version: 1.1.0 example: _profile: 'https://api.apiture.com/schemas/cards/cardRequest/v1.0.0/profile.json' cardId: 9e5a519c-ed3d-48ec-84d0-ef29b2843803 reason: lost description: Replace lost card _links: 'apiture:account': href: 'https://api.example.com/accounts/accounts/617c31ce-7bf0-4e55-a5df-12916ff22ada' x-apiture-links: - rel: 'apiture:account' title: The banking account associated with the card description: The account for which the user is requesting a new card. verb: get x-apiture-composition: - $ref: '#/components/schemas/abstractResource' - $ref: '#/components/schemas/cardRequestFields' properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' allOf: - $ref: '#/components/schemas/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/components/schemas/error' cardId: description: The resource ID of the card that is to be replaced. type: string example: 9e5a519c-ed3d-48ec-84d0-ef29b2843803 reason: description: Reasons which describe why the user is requesting a a card. allOf: - $ref: '#/components/schemas/cardRequestReason' example: lost description: description: |- The card holder's description, note, or explanation of why they requested a card. type: string accountNumbers: description: >- The masked and (optionally) full number for the account this card is associated with. The `full` number is only returned when requests contain the `?unmasked` query parameter. readOnly: true allOf: - $ref: '#/components/schemas/accountNumbers' type: object x-apiture-flattened: true summaryCardRequest: title: Card Request Summary (v1.1.0) description: >- Summary representation of a card request resource in replacements collections. This representation normally does not contain any `_embedded` objects. If needed, call the `GET` operation on the item's `self` link to get `_embedded` objects. x-apiture-version: 1.1.0 example: _id: 35eb0e67-ac9b-44d7-8799-6648ba6b1c65 _profile: 'https://api.apiture.com/schemas/cards/cardRequest/v1.0.0/profile.json' cardId: 9e5a519c-ed3d-48ec-84d0-ef29b2843803 reason: lost description: Replace lost card submittedAt: '2019-06-07T05:18:30.375Z' updatedAt: '2019-06-07T05:18:30.375Z' updatedBy: lucy.wellphunded@bankcustomer.example.com _links: self: href: /cards/cards/35eb0e67-ac9b-44d7-8799-6648ba6b1c65 'apiture:account': href: 'https://api.example.com/accounts/accounts/617c31ce-7bf0-4e55-a5df-12916ff22ada' 'apiture:cancel': href: 'https://api.example.com/cards/canceledCardRequests?cardRequest=617c31ce-7bf0-4e55-a5df-12916ff22ada' x-apiture-composition: - $ref: '#/components/schemas/abstractResource' - $ref: '#/components/schemas/cardRequestFields' - properties: - _id - state - submittedAt - resolvedAt - updatedAt - resolutionReason - updatedBy properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' allOf: - $ref: '#/components/schemas/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/components/schemas/error' cardId: description: The resource ID of the card that is to be replaced. type: string example: 9e5a519c-ed3d-48ec-84d0-ef29b2843803 reason: description: Reasons which describe why the user is requesting a a card. allOf: - $ref: '#/components/schemas/cardRequestReason' example: lost description: description: |- The card holder's description, note, or explanation of why they requested a card. type: string accountNumbers: description: >- The masked and (optionally) full number for the account this card is associated with. The `full` number is only returned when requests contain the `?unmasked` query parameter. readOnly: true allOf: - $ref: '#/components/schemas/accountNumbers' _id: description: The unique identifier for this card request resource. This is an immutable opaque string. readOnly: true type: string state: description: Indicates the state of a card request. allOf: - $ref: '#/components/schemas/cardRequestState' readOnly: true example: submitted submittedAt: description: 'The date-time when this card request request was submitted. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC format.' type: string format: date-time example: {} resolvedAt: description: >- The date-time when this card request request was completed, rejected, or canceled. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC format. type: string format: date-time example: {} updatedAt: description: 'The date-time when this card request attributes were last changed. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC format.' type: string format: date-time example: {} resolutionReason: description: The explanation for why the card was resolved. This may be the reason the card request was rejected. type: string maxLength: 2048 example: Suspected fraudulent activity has been detected. updatedBy: description: The username of the person who last modified or resolved this card request. type: string type: object x-apiture-flattened: true cardRequestState: title: Card Request State (v1.0.0) description: | Indicates the state of a card request. cardRequestState strings may have one of the following [enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations) values (described by the named cardRequestState) These enumeration values are further described by the [label group](https://developer.apiture.com/concepts/label-groups) named `cardRequestState` in the response from the [`getLabels`](#op-getLabels) operation.
ValueDescription
pendingPending: A card request has been created but not yet submitted.
submittedSubmitted: A card request has been submitted but not processed.
canceledCanceled: A card request has been canceled.
rejectedRejected: A card request has been rejected.
completedCompleted: A card request has been completed.
type: string enum: - pending - submitted - canceled - rejected - completed x-apiture-enum: cardRequestState x-apiture-version: 1.0.0 x-apiture-flattened: true cardRequest: title: Card Request (v1.1.0) description: > Representation of a card request resource. This represents a request to issue a new card or replace a lost, stolen, or damaged card. The hypermedia `_links` in the card request representation (listed below) include several action links which change the state of the card request. These links should be used with the `POST` verb (see [Resource sets](https://developer.apiture.com/docs/concepts/resource-sets/)). Response and request bodies using this cardRequest schema may contain the following links:
RelSummaryMethod
apiture:cancelCancel a card requestPOST
apiture:completeComplete a card requestPOST
apiture:rejectReject a card requestPOST
x-apiture-version: 1.1.0 x-apiture-links: - rel: 'apiture:cancel' operationId: cancelCardRequest - rel: 'apiture:complete' operationId: completeCardRequest - rel: 'apiture:reject' operationId: rejectCardRequest example: _id: 35eb0e67-ac9b-44d7-8799-6648ba6b1c65 _profile: 'https://api.apiture.com/schemas/cards/cardRequest/v1.0.0/profile.json' cardId: 9e5a519c-ed3d-48ec-84d0-ef29b2843803 reason: lost description: Replace lost card submittedAt: '2019-06-07T05:18:30.375Z' updatedAt: '2019-06-07T05:18:30.375Z' updatedBy: lucy.wellphunded@bankcustomer.example.com _links: self: href: /cards/cardRequests/35eb0e67-ac9b-44d7-8799-6648ba6b1c65 'apiture:card': href: /cards/cards/9e5a519c-ed3d-48ec-84d0-ef29b2843803 'apiture:account': href: 'https://api.example.com/accounts/accounts/617c31ce-7bf0-4e55-a5df-12916ff22ada' 'apiture:cancel': href: 'https://api.example.com/cards/canceledCardRequests?cardRequest=617c31ce-7bf0-4e55-a5df-12916ff22ada' x-apiture-composition: - $ref: '#/components/schemas/summaryCardRequest' properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' allOf: - $ref: '#/components/schemas/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/components/schemas/error' cardId: description: The resource ID of the card that is to be replaced. type: string example: 9e5a519c-ed3d-48ec-84d0-ef29b2843803 reason: description: Reasons which describe why the user is requesting a a card. allOf: - $ref: '#/components/schemas/cardRequestReason' example: lost description: description: |- The card holder's description, note, or explanation of why they requested a card. type: string accountNumbers: description: >- The masked and (optionally) full number for the account this card is associated with. The `full` number is only returned when requests contain the `?unmasked` query parameter. readOnly: true allOf: - $ref: '#/components/schemas/accountNumbers' _id: description: The unique identifier for this card request resource. This is an immutable opaque string. readOnly: true type: string state: description: Indicates the state of a card request. allOf: - $ref: '#/components/schemas/cardRequestState' readOnly: true example: submitted submittedAt: description: 'The date-time when this card request request was submitted. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC format.' type: string format: date-time example: {} resolvedAt: description: >- The date-time when this card request request was completed, rejected, or canceled. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC format. type: string format: date-time example: {} updatedAt: description: 'The date-time when this card request attributes were last changed. This is in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC format.' type: string format: date-time example: {} resolutionReason: description: The explanation for why the card was resolved. This may be the reason the card request was rejected. type: string maxLength: 2048 example: Suspected fraudulent activity has been detected. updatedBy: description: The username of the person who last modified or resolved this card request. type: string type: object x-apiture-flattened: true cardRequests: title: Card Requests Collection (v1.1.0) description: >- Collection of requests to issue a new or replacement card. The items in the collection are ordered in the `_embedded.items` array; the `name` is `replacements`. The top-level `_links` object may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`). x-apiture-version: 1.1.0 example: _profile: 'https://api.apiture.com/schemas/cards/cardRequests/v1.0.0/profile.json' start: 10 limit: 10 count: 67 name: cardRequests _links: self: href: /cards/cardRequests?start=10&limit=10 first: href: /cards/cardRequests?start=0&limit=10 next: href: /cards/cardRequests?start=20&limit=10 collection: href: /cards/cardRequests _embedded: items: anyOf: - _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'https://api.apiture.com/schemas/cards/cardRequest/v1.0.0/profile.json' _links: self: href: /cards/cardRequests/0399abed-fd3d-4830-a88b-30f38b8a365c - _id: d62c0701-0d74-4836-83f9-ebf3709442ea _profile: 'https://api.apiture.com/schemas/cards/cardRequest/v1.0.0/profile.json' _links: self: href: /cards/cardRequests/d62c0701-0d74-4836-83f9-ebf3709442ea x-apiture-composition: - $ref: '#/components/schemas/collection' - properties: - _embedded properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' allOf: - $ref: '#/components/schemas/links' _embedded: type: object description: Embedded objects. properties: items: description: An array containing a page of replacement items. type: array items: $ref: '#/components/schemas/summaryCardRequest' _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/components/schemas/error' count: description: >- The number of items in the collection. This value is _optional_ and may be omitted if the count is not computable efficiently. If a filter is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the filter. type: integer start: description: The start index of this page of items. type: integer limit: description: The maximum number of items per page. type: integer name: description: The name of the collection. type: string type: object x-apiture-flattened: true cardRequestFields: title: Card Request Fields (v1.1.0) x-apiture-version: 1.1.0 description: >- Common fields of the card request resource used to build other model schemas. The estimated shipping charges are based on the user's preferred mailing address. x-apiture-todo: Add the mailing address for the new card x-apiture-fragment: true required: - reason properties: cardId: description: The resource ID of the card that is to be replaced. type: string example: 9e5a519c-ed3d-48ec-84d0-ef29b2843803 reason: description: Reasons which describe why the user is requesting a a card. allOf: - $ref: '#/components/schemas/cardRequestReason' example: lost description: description: |- The card holder's description, note, or explanation of why they requested a card. type: string accountNumbers: description: >- The masked and (optionally) full number for the account this card is associated with. The `full` number is only returned when requests contain the `?unmasked` query parameter. readOnly: true allOf: - $ref: '#/components/schemas/accountNumbers' type: object x-apiture-flattened: true cardRequestReason: title: Card Request Reason (v1.1.0) x-apiture-version: 1.1.0 description: | The reason the user is requesting a replacement card. cardRequestReason strings may have one of the following [enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations) values (described by the named cardRequestReason) These enumeration values are further described by the [label group](https://developer.apiture.com/concepts/label-groups) named `cardRequestReason` in the response from the [`getLabels`](#op-getLabels) operation.
ValueDescription
initialInitial Card Request
lostLost Card
stolenStolen Card
damagedDamaged Card
neverReceivedNever Received: The card holder is requesting a replacement of card that was shipped but never received.
reorderReorder Closed Card: The card holder is requesting a replacement of a previously closed card.
type: string enum: - initial - lost - stolen - damaged - neverReceived - reorder x-apiture-enum: cardRequestReason x-apiture-flattened: true cardNumbers: title: Card Numbers (v1.0.0) description: Masked and full representation of a card number. properties: masked: description: >- A partial (masked) card number that does not contain all the digits of the full card number. This masked number appears in statements or in user experience presentation. It is sufficient for a user to differentiate this card from other cards the user holds, but is not sufficient for initiating transactions, etc. The first character is the mask character and is repeated; this does not indicate that the full card number is the same as the mask length. This value is derived and immutable. type: string maxLength: 16 readOnly: true example: '************3210' x-apiture-version: 1.0.0 type: object x-apiture-flattened: true cardShippingEstimateRequest: title: Card Shipping Estimate Request (v1.0.0) x-apiture-version: 1.0.0 description: > Information required to estimate the expedited shipping costs for a card. The shipping address is the preferred mailing address for the user making the request. Response and request bodies using this cardShippingEstimateRequest schema may contain the following links:
RelSummaryMethod
apiture:account The account associated with the cardGET
example: _profile: 'https://production.api.apiture.com/schemas/cards/cardShippingEstimateRequest/v1.0.0/profile.json' cardId: 0399abed-fd3d-4830-a88b-30f38b8a365c _links: 'apiture:account': href: /accounts/accounts/c4fff7a4-8654-4085-aeba-a984de81dcc3 x-apiture-links: - rel: 'apiture:account' title: The account associated with the card verb: get x-apiture-composition: - $ref: '#/components/schemas/abstractRequest' - properties: - cardId properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' allOf: - $ref: '#/components/schemas/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri cardId: description: 'The `_id` property of a card if requesting card replacement. For a new card, pass the `apiture:account` link instead.' type: string type: object x-apiture-flattened: true cardShippingEstimate: title: Card Shipping Estimate (v1.0.0) description: > The estimated shipping costs for a new or replacement card. Response and request bodies using this cardShippingEstimate schema may contain the following links:
RelSummaryMethod
apiture:cardFetch a representation of this cardGET
apiture:account The account associated with the cardGET
x-apiture-links: - rel: 'apiture:card' operationId: getCard - rel: 'apiture:account' title: The account associated with the card description: The account for which the user is requesting a new card. verb: get example: _profile: 'https://production.api.apiture.com/schemas/cards/cardShippingEstimate/v1.0.0/profile.json' cardId: 0399abed-fd3d-4830-a88b-30f38b8a365c normal: value: '0.00' currency: USD expedited: value: '12.00' currency: USD _links: 'apiture:account': href: /accounts/accounts/c4fff7a4-8654-4085-aeba-a984de81dcc3 'apiture:card': href: /cards/card/0399abed-fd3d-4830-a88b-30f38b8a365c x-apiture-version: 1.0.0 x-apiture-composition: - $ref: '#/components/schemas/abstractResource' - properties: - cardId - normal - expedited properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' allOf: - $ref: '#/components/schemas/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/components/schemas/error' cardId: description: >- The `_id` property of a card if requesting card replacement. For a new card, this is blank; refer to the the `apiture:account` link instead. type: string readOnly: true normal: description: The normal (non-expedited) shipping charges. allOf: - $ref: '#/components/schemas/positiveMoney' expedited: description: >- The optional expedited shipping charges. This is omitted from the response if expedited shipping is not allowed for the account's banking product. (The `card` object of the banking product reveals if expedited shipping is for that product.) allOf: - $ref: '#/components/schemas/positiveMoney' type: object x-apiture-flattened: true cardIssuerParameters: title: Card Issuer Parameters (v1.0.0) description: >- Parameters that the client passes to the card issuer user interface component. The example shows possible parameters for the card issuer Marqueta. x-apiture-version: 1.0.0 example: _profile: 'https://api.apiture.com/schemas/cards/cardIssuerParameters/v1.0.0/profile.json' issuer: marqueta parameters: - name: user_token value: 'cd8775f7f49a/408a|9afa-982a78bd08bd::7466c8c38489/4541|b695/af7ac2ba4537' - name: onetime_token value: '130d1a7d_fa0c/453a|86a9_93c411a9df3a::5f1d4ade5c34/40e4|8098/493475dd0c92' - name: application_id value: 09CF5D57C6084956866126610758E149 - name: card_token value: '77639FAF::7E77::4CDF::B096::4B5C5F971691--fc09b0af::a30b::4D34834F682826EE1C44' x-apiture-composition: - $ref: '#/components/schemas/abstractResource' - properties: - issuer - parameters properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' allOf: - $ref: '#/components/schemas/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/components/schemas/error' issuer: description: The name of the card issuer associated with the parameters. type: string parameters: description: An array of individual card issuer parameters. type: array items: $ref: '#/components/schemas/cardIssuerParameter' type: object x-apiture-flattened: true cardIssuerParameter: title: Card Issuer Parameter (v1.0.0) description: A single name/value parameter that the client passes to the card issuer user interface component. type: object x-apiture-version: 1.0.0 required: - name - value properties: name: description: The parameter name. type: string minLength: 4 maxLength: 32 pattern: '^[a-zA-Z][-a-zA-Z0-9_]{3,31}' value: description: The parameter value. type: string maxLength: 256 example: name: card_token value: '77639FAF::7E77::4CDF::B096::4B5C5F971691--fc09b0af::a30b::4D34834F682826EE1C44' x-apiture-flattened: true challengeErrorResponse: title: Challenge Error Response (v1.0.0) description: >- When an operation requires an additional identity verification challenge, it returns a 401 Unauthorized response status code and an error response with a challenge resource embedded in the `_error._embedded.challenge`. This informs the caller that they should verify the challenge via one or more of its `authenticators`, then retry the operation with the `Apiture-Challenge` header that references the challenge's `_id`. x-apiture-version: 1.0.0 x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/challengeErrorResponse/v1.0.0/model.json' x-apiture-namespace: auth x-apiture-composition: - $ref: '#/components/schemas/errorResponse' - properties: - _error properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' allOf: - $ref: '#/components/schemas/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: The description of the error. type: object allOf: - $ref: '#/components/schemas/challengeError' type: object x-apiture-flattened: true errorResponse: x-apiture-version: 2.0.0 title: Error Response (v2.0.0) description: 'Describes an error response, typically returned on 4xx or 5xx errors from API operations. The `_error` object contains the error details.' example: _profile: 'https://api.apiture.com/schemas/common/errorResponse/v2.0.0/profile.json' _error: _id: 2eae46e1-575c-4d69-8a8f-0a7b0115a4b3 message: The value for deposit must be greater than 0. statusCode: 422 type: positiveNumberRequired attributes: value: -125.5 remediation: Provide a value which is greater than 0 occurredAt: '2018-01-25T05:50:52.375Z' _links: describedby: href: 'https://api.apiture.com/errors/positiveNumberRequired' _embedded: errors: [] x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/errorResponse/v2.0.0/model.json' x-apiture-namespace: common x-apiture-composition: - $ref: '#/components/schemas/abstractResource' properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' allOf: - $ref: '#/components/schemas/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/components/schemas/error' type: object x-apiture-flattened: true localizedLabels: title: Localized Labels (v1.0.0) description: >- A map that defines lables for an enumeration or other item in a JSON schema. This is a map which maps enumeration schema names to an `localizedLabel` object. This schema is deprecated. Use [`labelGroups`](#schema-labelgroups)` instead. x-apiture-version: 1.0.0 x-apiture-deprecated: since: 1.0.0 replacement: labelGroups additionalProperties: $ref: '#/components/schemas/localizedLabel' x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/localizedLabels/v1.0.0/model.json' x-apiture-namespace: common type: object properties: {} x-apiture-flattened: true root: x-apiture-version: 2.0.0 title: API Root (v2.0.0) description: 'A HAL response, with hypermedia `_links` for the top-level resources and operations in API.' example: id: apiName name: API name apiVersion: 1.0.0 _profile: 'https://production.api.apiture.com/schemas/common/root/v2.0.0/profile.json' _links: {} x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/root/v2.0.0/model.json' x-apiture-namespace: common x-apiture-composition: - $ref: '#/components/schemas/abstractResource' - properties: - _id - name - apiVersion properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' allOf: - $ref: '#/components/schemas/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/components/schemas/error' _id: description: This API's unique ID. readOnly: true type: string name: type: string description: This API's name. apiVersion: type: string description: This API's version. type: object x-apiture-flattened: true abstractResource: x-apiture-version: 2.0.0 title: Abstract Resource (v2.0.0) description: >- An abstract schema used to define other schemas for request and response bodies. This is a [HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource representation. This model contains hypermedia `_links`, and either optional domain object data with `_profile` and optional `_embedded` objects, or an `_error` object. In responses, if the operation was successful, this object will not include the `_error`, but if the operation was a 4xx or 5xx error, this object will not include `_embedded` or any data fields, only `_error` and optionally `_links`. example: _profile: '{uri of resource profile.json}' _links: self: href: '{uri of current resource}' x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/abstractResource/v2.0.0/model.json' x-apiture-namespace: common x-apiture-composition: - $ref: '#/components/schemas/abstractRequest' - properties: - _error properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' allOf: - $ref: '#/components/schemas/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/components/schemas/error' type: object x-apiture-flattened: true accountNumbers: title: Account Numbers (v1.0.0) 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. type: string minLength: 8 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. This value is derived and immutable. type: string minLength: 4 maxLength: 17 example: '9876543210' readOnly: true x-apiture-version: 1.0.0 x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/accountNumbers/v1.0.0/model.json' x-apiture-namespace: common type: object x-apiture-flattened: true collection: x-apiture-version: 2.0.0 title: Collection (v2.0.0) description: A collection of resources. This is an abstract model schema which is extended to define specific resource collections. x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/collection/v2.0.0/model.json' x-apiture-namespace: common x-apiture-composition: - $ref: '#/components/schemas/abstractResource' - properties: - count - start - limit - name properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' allOf: - $ref: '#/components/schemas/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/components/schemas/error' count: description: >- The number of items in the collection. This value is _optional_ and may be omitted if the count is not computable efficiently. If a filter is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the filter. type: integer start: description: The start index of this page of items. type: integer limit: description: The maximum number of items per page. type: integer name: description: The name of the collection. type: string type: object x-apiture-flattened: true abstractRequest: x-apiture-version: 2.0.0 title: Abstract Request (v2.0.0) description: >- An abstract schema used to define other request-only schemas. This is a [HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource representation, minus the `_error` defined in `abstractResource`. properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' allOf: - $ref: '#/components/schemas/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri example: _profile: '{uri of resource profile.json}' _links: self: href: '{uri of current resource}' x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/model.json' x-apiture-namespace: common type: object x-apiture-flattened: true positiveMoney: title: Positive Money (v1.0.0) description: 'An amount of money in a specific currency, supporting only positive amounts.' properties: value: description: >- The monetary value, supporting only positive amounts. The numeric value is represented as a string so that it can be exact with no loss of precision. example: '3456.78' type: string currency: description: 'The [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217) for this monetary value. This is always upper case ASCII.' x-apiture-todo: 'ISO 4217 defines three-character codes. However, ISO 4217 does not account for cryptocurrencies. Of note, `DASH` uses 4 characters.' type: string minLength: 3 maxLength: 3 x-apiture-version: 1.0.0 x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/transfers/positiveMoney/v1.0.0/model.json' x-apiture-namespace: transfers type: object x-apiture-flattened: true links: title: Links (v1.0.0) x-apiture-version: 1.0.0 description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' type: object x-apiture-key: linkRelationName additionalProperties: $ref: '#/components/schemas/link' x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/links/v1.0.0/model.json' x-apiture-namespace: common properties: {} x-apiture-flattened: true error: x-apiture-version: 2.0.0 title: Error (v2.0.0) description: Describes an error in an API request or in a service called via the API. required: - message properties: message: type: string description: A localized message string describing the error condition. _id: description: >- A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at the source of the error). This is is an opaque string. readOnly: true type: string statusCode: description: The HTTP status code associate with this error. type: integer minimum: 100 maximum: 599 example: 422 type: type: string description: >- An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to render an appropriate message or hint. This provides a finer level of granularity than the `statusCode`. For example, instead of just 400 Bad Request, the `type` may be much more specific. such as `integerValueNotInAllowedRange` or `numericValueExceedsMaximum` or `stringValueNotInAllowedSet`. occurredAt: type: string format: date-time description: 'An [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC time stamp indicating when the error occurred.' example: '2018-02-02T03:37:15.375Z' attributes: description: >- Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the `minimum` and `maximum` values. This allows clients to present error messages as they see fit (the API does not assume the client/presentation tier). The set of attributes varies by error `type`. allOf: - $ref: '#/components/schemas/attributes' remediation: type: string description: An optional localized string which provides hints for how the user or client can resolve the error. errors: description: An optional array of nested error objects. This property is not always present. type: array items: $ref: '#/components/schemas/error' _links: $ref: '#/components/schemas/links' example: _id: 2eae46e1575c0a7b0115a4b3 message: Descriptive error message... statusCode: 422 type: errorType1 remediation: Remediation string... occurredAt: '2018-01-25T05:50:52.375Z' errors: - _id: ccdbe2c5c938a230667b3827 message: An optional embedded error - _id: dbe9088dcfe2460f229338a3 message: Another optional embedded error _links: describedby: href: 'https://developer.apiture.com/errors/errorType1' x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/error/v2.0.0/model.json' x-apiture-namespace: common type: object x-apiture-flattened: true localizedLabel: title: Localized Label (v1.0.0) description: >- A localized label and optional description for localizable content defined in this API. This schema is deprecated; use [`labelItem`](#schema-labelitem) instead. x-apiture-version: 1.0.0 x-apiture-deprecated: since: 1.0.0 replacement: labelGroups type: object properties: label: type: string description: A localized label or title which may be used labels or other UI controls which present a value. example: Limited Liability Corporation description: type: string description: A more detailed localized description of a localizable label. language: type: string description: >- The actual natural language tag to which this localized label is associated, as per [RFC 7231](https://tools.ietf.org/html/rfc7231#section-3.1.3.1) example: en-us code: type: string description: 'If the localized value is associated with an external standard, this is a lookup code or key or URI for that value.' example: '31' x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/localizedLabel/v1.0.0/model.json' x-apiture-namespace: common x-apiture-flattened: true link: x-apiture-version: 1.0.0 title: Link (v1.0.0) description: >- Describes a hypermedia link within a `_links` object in HAL representations. In Apiture APIs, links are [HAL links](https://developer.apiture.com/docs/concepts/links), but Apiture APIs do not use the `name` or `hreflang` properties of HAL. Apiture links _may_ include a `method` property. required: - href properties: href: type: string format: uri description: The URI or URI template for the resource/operation this link refers to. type: type: string description: The media type for the resource. templated: type: boolean description: 'If true, the link''s href is a [URI template](https://tools.ietf.org/html/rfc6570).' title: type: string description: An optional human-readable localized title for the link. deprecation: type: string format: uri description: 'If present, the containing link is deprecated and the value is a URI which provides human-readable text information about the deprecation.' profile: type: string format: uri description: 'The URI of a profile document, a JSON document which describes the target resource/operation.' example: href: /contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f title: Applicant x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/link/v1.0.0/model.json' x-apiture-namespace: common type: object x-apiture-flattened: true attributes: x-apiture-version: 2.0.0 title: Attributes (v2.0.0) description: An optional map of name/value pairs which contains additional dynamic data about the resource. type: object x-apiture-key: attributeName additionalProperties: $ref: '#/components/schemas/attributeValue' x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/attributes/v2.0.0/model.json' x-apiture-namespace: common properties: {} x-apiture-flattened: true challengeError: title: Challenge Error (v1.0.0) description: The operation error description with an embedded identity challenge. type: object x-apiture-version: 1.0.0 x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/challengeError/v1.0.0/model.json' x-apiture-namespace: auth x-apiture-composition: - $ref: '#/components/schemas/error' - properties: - _embedded properties: message: type: string description: A localized message string describing the error condition. _id: description: >- A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at the source of the error). This is is an opaque string. readOnly: true type: string statusCode: description: The HTTP status code associate with this error. type: integer minimum: 100 maximum: 599 example: 422 type: type: string description: >- An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to render an appropriate message or hint. This provides a finer level of granularity than the `statusCode`. For example, instead of just 400 Bad Request, the `type` may be much more specific. such as `integerValueNotInAllowedRange` or `numericValueExceedsMaximum` or `stringValueNotInAllowedSet`. occurredAt: type: string format: date-time description: 'An [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC time stamp indicating when the error occurred.' example: '2018-02-02T03:37:15.375Z' attributes: description: >- Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the `minimum` and `maximum` values. This allows clients to present error messages as they see fit (the API does not assume the client/presentation tier). The set of attributes varies by error `type`. allOf: - $ref: '#/components/schemas/attributes' remediation: type: string description: An optional localized string which provides hints for how the user or client can resolve the error. errors: description: An optional array of nested error objects. This property is not always present. type: array items: $ref: '#/components/schemas/error' _links: $ref: '#/components/schemas/links' _embedded: description: Embedded objects type: object properties: challenge: description: The details of the identity verification challenge. allOf: - $ref: '#/components/schemas/challenge' x-apiture-flattened: true attributeValue: x-apiture-version: 2.0.0 title: Attribute Value (v2.0.0) description: The data associated with this attribute. x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/attributeValue/v2.0.0/model.json' x-apiture-namespace: common type: object properties: {} x-apiture-flattened: true challenge: title: Challenge (v1.0.1) description: > A resource which represents an identity verification challenge to a user. The user must verify one or more of the authentication methods defined in this challenge in order to proceed with a banking operation (such as scheduling a larger than normal transfer, adding a joint owner or authorized signer to an account, or changing their mailing address or mobile phone number). Response and request bodies using this challenge schema may contain the following links:
RelSummaryMethod
apiture:redeemRedeem or use a challengePOST
x-apiture-version: 1.0.1 example: _id: 0399abed-fd3d-4830-a88b-30f38b8a365c _profile: 'https://api.apiture.com/schemas/auth/challenge/v1.0.1/profile.json' reason: Transfer amount much higher than normal contextUri: 'https://fi.apiture.com/transfers/scheduledTransfers/50b9df19-d6bf-4ac0-b5f4-3e6448b7dacd' minimumAuthenticatorCount: 1 authenticators: - _id: 7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3 _profile: 'https://api.apiture.com/schemas/auth/authenticator/v1.0.1/profile.json' userId: b2720469-3497-4b82-8b85-30f2155aa66d state: started type: name: sms label: SMS Code description: Enter a code sent via SMS to the user's preferred mobile device. category: device schema: title: SMS attributes description: Schema for an authenticator's `attributes` when the authenticator type is `sms`. type: object required: - code - length properties: code: type: string description: >- A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'. minLength: 3 maxLength: 10 length: description: The number of digits/characters that are sent to the user via SMS. type: integer minimum: 3 maximum: 10 example: 6 maximumRetries: 3 retryCount: 1 createdAt: '2019-08-23T12:42:50.375Z' expiresAt: '2019-08-23T13:12:50.375Z' _links: self: href: /auth/challenges/0399abed-fd3d-4830-a88b-30f38b8a365c/authenticators/7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3 'apiture:challenge': href: /auth/challenges/0399abed-fd3d-4830-a88b-30f38b8a365c 'apiture:retry': href: /auth/challenges/retriedAuthenticators?authenticator=7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3 'apiture:verify': href: /auth/challenges/verifiedAuthenticators maximumRedemptionCount: 1 redemptionCount: 0 state: pending createdAt: '2019-08-23T11:37:55.375Z' expiresAt: '2019-08-23T12:37:55.375Z' _links: self: href: /auth/challenges/5d63053d-435c-4455-a0b5-6f88ab729d1a 'apiture:redeem': href: /auth/redeemedChallenges?challenge=5d63053d-435c-4455-a0b5-6f88ab729d1a x-apiture-links: - rel: 'apiture:redeem' operationId: redeemChallenge x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/challenge/v1.0.1/model.json' x-apiture-namespace: auth x-apiture-composition: - $ref: '#/components/schemas/summaryChallenge' - properties: - _id - authenticators - redeemable - verifiedAt - failedAt - expiresAt - redemptionHistory - code properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' allOf: - $ref: '#/components/schemas/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/components/schemas/error' reason: description: >- The reason the application or service has issued a challenge requesting the user verify their identity. This is for labeling or informational purposes. type: string x-apiture-todo: - Should this be a reasonCode (non-localizable identifier and reason label? contextUri: description: >- The URI of a resource that establishes the context in which the user is asked to authenticate their identity. For example, for this may be for a pending transfer, a user's mailing address, or an account if adding a joint owner. type: string format: uri maxLength: 2048 userId: description: >- The user ID of the user who is requested to verify their identity. The default is the userID of the authenticated person creating the challenge. type: string minimumAuthenticatorCount: description: The minimum number of different authenticators the user must verify in order to satisfy the identity challenge. The default is 1. type: integer minimum: 0 maximum: 4 maximumRedemptionCount: description: The maximum number of times the challenge may be used or redeemed. The default is 1. type: integer minimum: 1 _id: description: The unique identifier for this challenge resource. This is an immutable opaque string assigned upon creation. readOnly: true type: string redemptionCount: description: How many times the challenge has been redeemed. type: integer readOnly: true state: description: The state of this authenticator. allOf: - $ref: '#/components/schemas/challengeState' readOnly: true createdAt: description: >- The time stamp when challenge was created, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format (`YYYY-MM-DDThh:mm:ss.sssZ`). type: string format: date-time readOnly: true authenticators: description: >- An array of authenticators with which the user can verify their identity. This is derived; the array and the authenticators are constructed in the `createChallenge` operation. type: array items: $ref: '#/components/schemas/authenticator' readOnly: true redeemable: description: >- `true` if and only if the challenge may be redeemed. This is derived from the states of the challenge's authenticators; if the number of `verified` authenticators meets or exceeds the `minimumAuthenticatorCount`, the challenge becomes `verified` and may be redeemed via a `POST` to href in the challenge's `apiture:redeem` link. type: boolean readOnly: true verifiedAt: description: >- The time stamp when challenge was verified in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format (`YYYY-MM-DDThh:mm:ss.sssZ`). type: string format: date-time readOnly: true failedAt: description: >- The time stamp when the user failed to verify their identity verification (authentication) for this challenge, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format (`YYYY-MM-DDThh:mm:ss.sssZ`). type: string format: date-time readOnly: true expiresAt: description: >- The time stamp when the this challenge expires, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format (`YYYY-MM-DDThh:mm:ss.sssZ`). type: string format: date-time readOnly: true redemptionHistory: description: >- The time stamps when a service or operation redeemed this challenge, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format (`YYYY-MM-DDThh:mm:ss.sssZ`). Item 0 is the time stamp the challenge was first redeemed, item 1 is the time stamp of the next redemption, and so on. readOnly: true type: array items: type: string format: date-time readOnly: true code: description: >- An optional authentication code which is only returned in the challenge resource if both a) the platform assigned the `code` when [constructing the challenge](#op-createChallenge)), _and_ b) the user has successfully verified the challenge. The client must [re-fetch the verified challenge](#op-getChallenge) in order to access this property. type: string minLength: 16 maxLength: 128 readOnly: true type: object x-apiture-flattened: true summaryChallenge: title: Summary Challenge (v1.0.0) description: 'Summary representation of a challenge, used in the challenge collection.' x-apiture-version: 1.0.0 x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/summaryChallenge/v1.0.0/model.json' x-apiture-namespace: auth x-apiture-composition: - $ref: '#/components/schemas/abstractResource' - $ref: '#/components/schemas/challengeFields' - properties: - _id - redemptionCount - state - createdAt properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' allOf: - $ref: '#/components/schemas/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/components/schemas/error' reason: description: >- The reason the application or service has issued a challenge requesting the user verify their identity. This is for labeling or informational purposes. type: string x-apiture-todo: - Should this be a reasonCode (non-localizable identifier and reason label? contextUri: description: >- The URI of a resource that establishes the context in which the user is asked to authenticate their identity. For example, for this may be for a pending transfer, a user's mailing address, or an account if adding a joint owner. type: string format: uri maxLength: 2048 userId: description: >- The user ID of the user who is requested to verify their identity. The default is the userID of the authenticated person creating the challenge. type: string minimumAuthenticatorCount: description: The minimum number of different authenticators the user must verify in order to satisfy the identity challenge. The default is 1. type: integer minimum: 0 maximum: 4 maximumRedemptionCount: description: The maximum number of times the challenge may be used or redeemed. The default is 1. type: integer minimum: 1 _id: description: The unique identifier for this challenge resource. This is an immutable opaque string assigned upon creation. readOnly: true type: string redemptionCount: description: How many times the challenge has been redeemed. type: integer readOnly: true state: description: The state of this authenticator. allOf: - $ref: '#/components/schemas/challengeState' readOnly: true createdAt: description: >- The time stamp when challenge was created, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format (`YYYY-MM-DDThh:mm:ss.sssZ`). type: string format: date-time readOnly: true type: object x-apiture-flattened: true authenticator: title: Authenticator (v1.0.1) x-apiture-version: 1.0.1 description: > Representation of authenticators which verify a user's identity. Response and request bodies using this authenticator schema may contain the following links:
RelSummaryMethod
apiture:retryRetry an authenticatorPOST
apiture:startStart an authenticatorPOST
apiture:verifyVerify a user's identityPOST
apiture:challengeFetch a representation of this challengeGET
example: _id: 7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3 _profile: 'https://api.apiture.com/schemas/auth/authenticator/v1.0.1/profile.json' userId: b2720469-3497-4b82-8b85-30f2155aa66d state: started type: name: sms label: SMS Code description: Enter a code sent via SMS to the user's preferred mobile device. category: device schema: title: SMS attributes description: Schema for an authenticator's `attributes` when the authenticator type is `sms`. type: object required: - code - length properties: code: type: string description: >- A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'. minLength: 3 maxLength: 10 length: description: The number of digits/characters that are sent to the user via SMS. type: integer minimum: 3 maximum: 10 example: 6 maximumRetries: 3 retryCount: 1 createdAt: '2019-08-23T12:42:50.375Z' expiresAt: '2019-08-23T13:12:50.375Z' _links: self: href: /auth/challenges/2e61e506-1568-4f1a-a93e-4d0a48a06d0e/authenticators/7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3 'apiture:challenge': href: /auth/challenges/challenges/b59438cd-5efb-4915-916b-0600bb2a4e1e 'apiture:retry': href: /auth/challenges/retriedAuthenticators?authenticator=7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3 'apiture:verify': href: /auth/challenges/verifiedAuthenticators x-apiture-links: - rel: 'apiture:retry' operationId: retryAuthenticator - rel: 'apiture:start' operationId: startAuthenticator - rel: 'apiture:verify' operationId: verifyAuthenticator - rel: 'apiture:challenge' operationId: getChallenge x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/authenticator/v1.0.1/model.json' x-apiture-namespace: auth x-apiture-composition: - $ref: '#/components/schemas/abstractResource' - $ref: '#/components/schemas/authenticatorFields' - properties: - _id - userId - state - retryCount - attributes - createdAt - verifiedAt - failedAt - expiresAt properties: _links: description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.' allOf: - $ref: '#/components/schemas/links' _embedded: description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.' type: object _profile: description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.' type: string format: uri _error: description: An object which describes an error. This value is omitted if the operation succeeded without error. type: object allOf: - $ref: '#/components/schemas/error' type: description: The type of this authenticator. This must be one of the items in the `/authenticatorTypes` resource. allOf: - $ref: '#/components/schemas/authenticatorType' maximumRetries: description: >- The maximum number of times the user may retry this authenticator. If `0`, the user must authenticate correctly on the first try. When an authenticator is retried, the client should `POST` to the `apiture:retry` link on the authenticators; absence of the link means the user cannot retry the authenticator. The default is `3`. type: integer minimum: 0 maximum: 10 _id: description: The unique identifier for this authenticator resource. This is an immutable opaque string assigned upon creation. readOnly: true type: string userId: description: The user ID of the user who is requested to verify their identity. type: string state: description: The state of this authenticator. This is derived and read-only. allOf: - $ref: '#/components/schemas/authenticatorState' readOnly: true retryCount: description: The actual number of times a user has retried this authenticator. type: integer minimum: 0 maximum: 10 readOnly: true attributes: description: >- Data collected from the user that is used to verify this authenticator. This data conforms to the schema defined in the `type`. For example, for `sms`, the `attributes` must contains a `code`. type: object createdAt: description: >- The time stamp when authenticator was created, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format (`YYYY-MM-DDThh:mm:ss.sssZ`). type: string format: date-time readOnly: true verifiedAt: description: >- The time stamp when authenticator was verified in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format (`YYYY-MM-DDThh:mm:ss.sssZ`). type: string format: date-time readOnly: true failedAt: description: >- The time stamp when the user failed to verify their identity verification (authentication) for this challenge, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format (`YYYY-MM-DDThh:mm:ss.sssZ`). type: string format: date-time readOnly: true expiresAt: description: >- The time stamp when the this challenge expires, in [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC date-time format (`YYYY-MM-DDThh:mm:ss.sssZ`). type: string format: date-time readOnly: true type: object x-apiture-flattened: true challengeFields: title: Challenge Fields (v1.0.0) description: Properties of challenge objects. x-apiture-fragment: true properties: reason: description: >- The reason the application or service has issued a challenge requesting the user verify their identity. This is for labeling or informational purposes. type: string x-apiture-todo: - Should this be a reasonCode (non-localizable identifier and reason label? contextUri: description: >- The URI of a resource that establishes the context in which the user is asked to authenticate their identity. For example, for this may be for a pending transfer, a user's mailing address, or an account if adding a joint owner. type: string format: uri maxLength: 2048 userId: description: >- The user ID of the user who is requested to verify their identity. The default is the userID of the authenticated person creating the challenge. type: string minimumAuthenticatorCount: description: The minimum number of different authenticators the user must verify in order to satisfy the identity challenge. The default is 1. type: integer minimum: 0 maximum: 4 maximumRedemptionCount: description: The maximum number of times the challenge may be used or redeemed. The default is 1. type: integer minimum: 1 x-apiture-version: 1.0.0 x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/challengeFields/v1.0.0/model.json' x-apiture-namespace: auth type: object x-apiture-flattened: true challengeState: title: Challenge States (v1.0.0) description: |+ The state of an identity challenge resource. This is derived based on the state of the challenge's authenticators. challengeState strings may have one of the following [enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations):
ValueDescription
pendingPending: The challenge is created but not yet started.
startedStarted: The user has started the challenge and associated authenticator(s).
verifiedVerified: The user correctly verified the corresponding authenticator(s), marking the challenge as verified.
failedFailed: The challenge has failed, often because the user failed one or more of the authenticators.
redeemedRedeemed: The user has redeemed (used) the challenge.
expiredExpired: The challenge has expired without being verified.
x-apiture-enum: challengeState type: string enum: - pending - started - verified - failed - redeemed - expired x-apiture-version: 1.0.0 x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/challengeState/v1.0.0/model.json' x-apiture-namespace: auth x-apiture-flattened: true authenticatorFields: title: Authenticator Fields (v1.0.0) description: Common fields of an authenticator. x-apiture-fragment: true properties: type: description: The type of this authenticator. This must be one of the items in the `/authenticatorTypes` resource. allOf: - $ref: '#/components/schemas/authenticatorType' maximumRetries: description: >- The maximum number of times the user may retry this authenticator. If `0`, the user must authenticate correctly on the first try. When an authenticator is retried, the client should `POST` to the `apiture:retry` link on the authenticators; absence of the link means the user cannot retry the authenticator. The default is `3`. type: integer minimum: 0 maximum: 10 x-apiture-version: 1.0.0 x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/authenticatorFields/v1.0.0/model.json' x-apiture-namespace: auth type: object x-apiture-flattened: true authenticatorState: title: Authenticator State (v1.0.0) description: |+ The state of a challenge authenticator resource. * The `startAuthenticator` operation (link `apiture:start`) changes the state from `pending` to `started`. * The `retryAuthenticator` operation (link `apiture:retry`) changes the state to `started` and is only allowed if the authenticator has more retries available. * The `verifyAuthenticator` operation (link `apiture:verify`) validates the `attributes` and changes the state to `verified` if valid or to `failed` if invalid. authenticatorState strings may have one of the following [enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations):
ValueDescription
pendingPending: The authenticator is created but not yet started.
startedStarted: The user has started the authenticator.
verifiedVerified: The user corresponding verified the authenticator.
failedFailed: The user failed the authenticators criteria.
expiredExpired: The authenticator expired before the user completed the criteria.
x-apiture-enum: authenticatorState type: string enum: - pending - started - verified - failed - expired x-apiture-version: 1.0.0 x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/authenticatorState/v1.0.0/model.json' x-apiture-namespace: auth x-apiture-flattened: true authenticatorType: title: Authenticator Type (v1.0.0) description: An authenticator type description. properties: name: type: string description: The name of this authenticator; also the key in the `authenticatorTypes` object. example: sms label: type: string description: A localized label or title which may be used labels or other UI controls which present a value. example: SMS code description: type: string description: A more detailed localized description of an authenticator type. language: type: string description: >- The actual natural language tag to which this authentication type description is associated, as per [RFC 7231](https://tools.ietf.org/html/rfc7231#section-3.1.3.1). If omitted, this serves as the _default_. example: en-us category: type: string description: The authentication category. allOf: - $ref: '#/components/schemas/authenticatorCategory' schema: type: object description: >- The JSON schema which describe the `attributes` object for all authenticators of this type. For example, for `sms`, the schema defines a required `code` string. example: name: sms label: SMS code description: Enter a code sent via SMS to the user's preferred mobile device. category: device schema: title: SMS attributes description: Schema for an authenticator's `attributes` when the authenticator type is `sms`. type: object required: - code - length properties: code: type: string description: >- A code that was sent to the user's mobile device via SMS. The user should enter the code in the app, then set `attributes.code` to that. The length of the code (the number of characters or digits) must equal the `length'. minLength: 3 maxLength: 10 length: description: The number of digits/characters that are sent to the user via SMS. type: integer minimum: 3 maximum: 10 example: 6 x-apiture-version: 1.0.0 x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/authenticatorType/v1.0.0/model.json' x-apiture-namespace: auth type: object x-apiture-flattened: true authenticatorCategory: title: authenticatorCategory (v1.0.0) description: |+ Categories which help classify and organize different authenticator types: * `knowledge` - Something you know, such as a password or answers to personal questions. * `biometric` - Something you are, such as facial recognition or fingerprints. * `device` - Something you have, such as a mobile phone (for confirmation via a code sent via text message) or an electronic key. authenticatorCategory strings may have one of the following [enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations):
ValueDescription
knowledgeKnowledge: Authenticate with information the user knows, such as a password or answers to personal questions.
biometricBiometric: Authenticate with physical characteristics of the user, such as fingerprints, voiceprint, or faceprint.
deviceDevice: Authenticate with a device that the user has, such as a mobile phone or an electronic key.
x-apiture-enum: authenticatorCategory type: string enum: - knowledge - biometric - device x-apiture-version: 1.0.0 x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/authenticatorCategory/v1.0.0/model.json' x-apiture-namespace: auth x-apiture-flattened: true responses: '304': description: Not Modified. The resource has not been modified since it was last fetched. '400': description: >- Bad Request. The request body or one or more of the query parameters was not well formed. The `_error` field in the response will contain details about the request error. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' '412': description: >- Precondition Failed. The supplied `if-Match` header value does not match the most recent `ETag` response header value. The resource has changed in the interim. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' '422': description: >- Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The `_error` field in the response will contain details about the request error. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 422CardShippingEstimate: 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. This error response may have one of the following `type` values: * [`cardRefNotFound`](#err-cardRefNotFound) * [`invalidAccountLink`](#err-invalidAccountLink) x-apiture-errors: - cardRefNotFound - invalidAccountLink content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 400CompleteCardRequest: description: |- Bad Request. The cardRequest parameter was malformed or does not refer to an existing or accessible card request. This error response may have one of the following `type` values: * [`cardRequestRefNotFound`](#err-cardRequestRefNotFound) x-apiture-errors: - cardRequestRefNotFound content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 409CompleteCardRequestConflict: description: >- Conflict. The request to complete the card request is not allowed. The `_error` field in the response will contain details about the request error. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 400RejectCardRequest: description: |- Bad Request. The cardRequest parameter was malformed or does not refer to an existing or accessible card request. This error response may have one of the following `type` values: * [`cardRequestRefNotFound`](#err-cardRequestRefNotFound) x-apiture-errors: - cardRequestRefNotFound content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 409RejectCardRequestConflict: description: >- Conflict. The request to reject the card request is not allowed. The `_error` field in the response will contain details about the request error. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 400CancelCardRequest: description: |- Bad Request. The cardRequest parameter was malformed or does not refer to an existing or accessible card request. This error response may have one of the following `type` values: * [`cardRequestRefNotFound`](#err-cardRequestRefNotFound) x-apiture-errors: - cardRequestRefNotFound content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 409CancelCardRequestConflict: description: >- Conflict. The request to cancel the card request is not allowed. The `_error` field in the response will contain details about the request error. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 400UnlockCard: description: |- Bad Request. The card parameter was malformed or does not refer to an existing or accessible card. This error response may have one of the following `type` values: * [`cardRefNotFound`](#err-cardRefNotFound) x-apiture-errors: - cardRefNotFound content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 409UnlockCardConflict: description: Conflict. The request to unlock the card is not allowed. The `_error` field in the response will contain details about the request error. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 400CloseCard: description: |- Bad Request. The card parameter was malformed or does not refer to an existing or accessible card. This error response may have one of the following `type` values: * [`cardRefNotFound`](#err-cardRefNotFound) x-apiture-errors: - cardRefNotFound content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 409CloseCardConflict: description: Conflict. The request to close the card is not allowed. The `_error` field in the response will contain details about the request error. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 400LockCard: description: |- Bad Request. The card parameter was malformed or does not refer to an existing or accessible card. This error response may have one of the following `type` values: * [`cardRefNotFound`](#err-cardRefNotFound) x-apiture-errors: - cardRefNotFound content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 409LockCardConflict: description: Conflict. The request to lock the card is not allowed. The `_error` field in the response will contain details about the request error. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 400ActivateCard: description: |- Bad Request. The card parameter was malformed or does not refer to an existing or accessible card. This error response may have one of the following `type` values: * [`cardRefNotFound`](#err-cardRefNotFound) x-apiture-errors: - cardRefNotFound content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 409ActivateCardConflict: description: Conflict. The request to activate the card is not allowed. The `_error` field in the response will contain details about the request error. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 404CardRequest: description: >- Not Found. There is no such card card request resource at the specified `{cardRequestId}`. The `_error` field in the response will contain details about the request error. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 404Card: description: >- Not Found. There is no such card resource at the specified `{cardId}`. The `_error` field in the response will contain details about the request error. content: application/hal+json: schema: $ref: '#/components/schemas/errorResponse' application/json: schema: $ref: '#/components/schemas/errorResponse' 204Deleted: description: No Content. The resource was deleted successfully. parameters: apitureChallengeHeaderParam: name: Apiture-Challenge description: >- The unique identifier of a Challenge resource which demonstrates the user has recently verified their identity. See the discussion of _Multi-factor authentication challenges_ above. The value must be the `_id` string of a valid, redeemable Challenge resource which matches the challenge context. in: header required: false schema: type: string cardRequestQueryParam: name: cardRequest required: true in: query description: >- A string which uniquely identifies a card request which is to added to the canceled card requests resource set. This may be the unique cardRequestId or the URI of the card request. schema: type: string unmaskedQueryParam: name: unmasked description: >- For security reasons, the default response includes only a [_masked_ banking account number](#schema-accountNumbers), for partial identification purposes. For `?unmasked=true`, the response body includes the _full_ account number for each of the requested cards. Requests for full account numbers are auditable.
Note that card numbers are _always_ masked. in: query required: false schema: type: boolean default: false cardsQueryParam: name: card required: true in: query description: 'A string which uniquely identifies a card. This may be the unique `{cardId}` or the URI of the card.' schema: type: string cardRequestIdPathParam: name: cardRequestId description: The unique identifier of this card request resource. This is an opaque string. in: path required: true schema: type: string filterQueryParam: name: filter in: query description: 'Optional filter criteria. See [filtering](http://developer.apiture.com/docs/concepts/filtering).' schema: type: string qQueryParam: name: q in: query description: 'Optional search string. See [searching](http://developer.apiture.com/docs/concepts/searching).' schema: type: string cardIdPathParam: name: cardId description: The unique identifier of this card. This is an opaque string. in: path required: true schema: type: string ifMatchHeaderParam: name: If-Match description: The entity tag that was returned in the `ETag` response. This must match the current entity tag of the resource. in: header required: true schema: type: string ifNoneMatchHeaderParam: name: If-None-Match description: >- The entity tag that was returned in the `ETag` response. If the resource's current entity tag matches, the `GET` will return 304 (Not Modified) and no response body, else the resource representation will be returned. in: header schema: type: string typeIdPathParam: name: typeId description: The unique identifier of this policy type. This is the policy name. in: path required: true schema: type: string securitySchemes: apiKey: type: apiKey name: API-Key in: header description: >- API Key based authentication. Each client application must pass its private, unique API key, allocated in the developer portal, via the `API-Key: {api-key}` request header. accessToken: type: oauth2 description: >- OAuth2 client access token authentication. The client authenticates against the server at `authorizationUrl`, passing the client's private `clientId` (and optional `clientSecret`) as part of this flow. The client obtains an access token from the server at `tokenUrl`. It then passes the received access token via the `Authorization: Bearer {access-token}` header in subsequent API calls. The authorization process also returns a refresh token which the client should use to renew the access token before it expires. flows: authorizationCode: authorizationUrl: 'https://auth.apiture.com/oauth2/authorize' tokenUrl: 'http://auth.apiture.com/auth/oauth2/token' scopes: card/read: Read access to cards and card replacements. card/write: Write (update) access to cards and card replacements. card/delete: Delete access to cards and card replacements. card/full: Full access to cards and card replacements. admin/write: Administrative write (update) access to cards and card replacements.