openapi: 3.0.0
servers:
- url: 'https://api.devbank.apiture.com/users'
info:
title: Users
description: >
The Users API provides operations to create and maintain online customers for the financial institution. A user represents a person who has
registered for online digital banking. Each user resource contains contact information about them (their name, addresses, phone numbers, email
addresses) as well as birthdate, government identification, citizenship, and other information that allows the financial institution to conform to
regulations related to customers. Every user is uniquely identifiable by a system-generated unique identifier. Users can be created (never
deleted) and the state of a user can be modified by authorized financial institution administrators. This API also maintains other banking
information about a user, such as their funds transfer limits or other constraints. In addition to the basic operations to create and modify
users, there are several actions supported for users. API [links](http://developer.apiture.com/docs/concepts/links) for these actions are
described in the `user` schema.
* Lock - if someone attempts to log in with an incorrect password too many times,
the user is locked.
([`POST /lockedUsers?user={userId}`](#op-lockUser).
The user can be unlocked by resetting their password.
Unlocking a user is done by reactivating them
([`POST /activeUsers?user={userId}`](#op-activateUser)).
* Deactivate - If the financial institution wishes to suspend a user's activity.
([`POST /inactiveUsers?user={userId}`](#op-deactivateUser)).
Inactive users can be reactivated
([`POST /activeUsers?user={userId}`](#op-activateUser)).
* Freeze - If the financial institution suspects fraudulent use of a user's account,
they can freeze a user.
([`POST /frozenUsers?user={userId}`](#op-freezeUser)).
Unfreezing a user is done by reactivating them
([`POST /activeUsers?user={userId}`](#op-activateUser)).
* Remove - The financial institution can remove a user when they leave the financial institution.
([`POST /removedUsers?user={userId}`](#op-removeUser)).
The user resource is retained rather than being deleted, so that other audit
and other information that references the user remains valid.
This API also supports service configuration operations.
## User addresses, phone numbers, and email addresses
A [`user`](#schema-user) resource contains the user's `addresses`, `phoneNumbers` and `emailAddresses`. These properties may be passed in the
[`createUser`](#op-createUser) operation when a client is creating a new user, but are immutable after: the [`updateUser`](#op-updateUser) and
[`patchUser`](#op-patchUser) operations do not change these `readOnly` properties in the `user` schema. This is a security measure to prevent
account takeover attacks in case a user's login account is compromised.
Add new contact items to a user via [`createAddress`](#op-createAddress), [`createPhoneNumber`](#op-createPhoneNumber) and
[`createEmailAddress`](#op-createEmailAddress). These operations also support a `?replaceId={id}` argument for replacing an existing item (by its
ID). The financial institution may review and approve these changes to help prevent fraud. Replacing the user's preferred mailing address, email,
or phone number may also require multi-factor authentication challenges; see the next section.
## Multi-factor authentication challenges
To prevent account takeover attacks, some operations to update the user's profile require _multi-factor authentication_ (MFA). An MFA _challenge_
is a process to verify the user's identity through one or more additional authentication steps.
Some examples are the operations which change the user's preferred phone number:
1. [`setPreferredPhoneNumber`](#op-setPreferredPhoneNumber) operation
1. [`createPhoneNumber`](#op-createPhoneNumber) operation when the `?replaceId` names the current preferred phone number.
Both require an MFA challenge. When the client tries the operation 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`](#schema-challenge) resource which includes one or more [_authenticators_](#schema-authenticator). The client should start at least
one of the authenticators, optionally allowing the user choose which ones to use, depending on how many authenticators are required.
When changing the user's preferred phone number, for example, the challenge may include an authenticator that sends a verification code to the
user's email account. The user completes the authentication by entering the code in the client application. Once the authentication step has
completed successfully, the client must pass the resource ID of the challenge resource in the `Apiture-Challenge` request header in order for the
operation to update the user's profile information. Thus, these operations often require two tries: the first (without the `Apiture-Challenge`
header), which fails with a 409 status but returns 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.
cannotChangeId
**Description**: The id of a resource cannot be changed.
**Remediation**: Please submit the correct id if you must include it in the request body.
cannotUpdateState
**Description**: A users state cannot be updated using put.
**Remediation**: See the apiture API documentation about using the /removedUsers, /activeUsers, /inactiveUsers, /lockedUsers and /frozenUsers
endpoints to update state.
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.
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.
duplicateTaxId
**Description**: A user with the given taxId already exists.
**Remediation**: Resubmit the operation with a unique taxId.
duplicateUsername
**Description**: A user with the given username already exists.
**Remediation**: Resubmit the operation with a unique username.
invalidAddressType
**Description**: An invalid address type was given.
**Remediation**: Resubmit the operation with a valid address type according to the Users API documentation.
The `attributes` object in the error may have the following properties:
| Property | Type | Description |
|----------|------|-------------|
| validTypes | [string] | A list of allowed address types.
Example:
`home,mailing,home,prior,work,vacation,shipping,billing,headquarters,location,property,school,commercial,other` |
invalidPhoneType
**Description**: An invalid phone type was given.
**Remediation**: Resubmit the operation with a valid phone type according to the Users API documentation.
The `attributes` object in the error may have the following properties:
| Property | Type | Description |
|----------|------|-------------|
| validTypes | [string] | A list of allowed phone number types.
Example: `home,mobile,work,fax,school,other` |
invalidStateChange
**Description**: A user can only be changed to a different state if they meet the current state requirement.
**Remediation**: Check the state of the user and the applicable allowed state transitions in the Users API documentation.
The `attributes` object in the error may have the following properties:
| Property | Type | Description |
|----------|------|-------------|
| requiredStates | [string] | A list of states the user must be in in order for this state change request to be valid.
Example: `inactive` |
invalidUserId
**Description**: No Users were found for the specified userId.
**Remediation**: Check to make sure that the supplied userId corresponds to an apiture user resource.
itemStillPending
**Description**: The selected item cannot be assigned as preferred profile data because it is still `pending`.
**Remediation**: Pass the _id of an `approved` profile item.
malformedRequestBody
**Description**: The supplied request body was malformed.
**Remediation**: Check to make sure that your request body exists and that it does not contain syntax errors.
This error type may be included in error responses for the following HTTP status code: 400
**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.
noSuchChallenge
**Description**: The challenge resource specified in the Apiture-Challenge request header does not exist.
**Remediation**: Pass the _id of an existing, unexpired, unredeemed challenge.
noSuchProfileValue
**Description**: The selected profile value _id does not exist.
**Remediation**: Pass the _id of an existing item.
requestError
**Description**: There was a server side error when executing the API request.
**Remediation**: Check your parameters and resubmit the request.
This error type may be included in error responses for the following HTTP status code: 5xx
updateUserError
**Description**: There was an error updating the user with the given userId.
**Remediation**: Check to make sure that the user was not updated and resubmit the operation, if it was not.
version: 0.24.4
contact:
name: Apiture
url: 'https://developer.apiture.com'
email: api@apiture.com
termsOfService: 'https://developer.apiture.com/docs/Apiture-Open-API-License-Agreement.pdf'
license:
name: Pending.
tags:
- name: API
description: Endpoints which describe this API
- name: User
description: Endpoints to manage users
- name: User Actions
description: Actions on users
- name: Addresses
description: User's Mailing Addresses
- name: Email Addresses
description: User's Email Addresses
- name: Phone Numbers
description: User's Phone Numbers
- name: Encryption
description: Data Encryption
- name: Configuration
description: Users Service Configuration
paths:
'/users/{userId}/addresses':
parameters:
- $ref: '#/components/parameters/userIdPathParam'
get:
summary: Get user's addresses
description: Return the list of the user's addresses.
operationId: getAddresses
x-apiture-implemented: true
tags:
- Addresses
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/userAddresses'
application/json:
schema:
$ref: '#/components/schemas/userAddresses'
'400':
$ref: '#/components/responses/400'
'422':
$ref: '#/components/responses/422'
security:
- apiKey: []
accessToken:
- profiles/read
post:
summary: Create a new address
description: |-
Add an address to the list of the user's addresses.
The new address will be `pending` until the financial institution has
reviewed and approved it, after which it will become `approved`.
This operation may require the user to complete an additional
authentication challenge as described in _Multi-factor
authentication challenges_ above. A valid
`Apiture-Challenge` request header may be required
if the `?replaceId` parameter is used and the profile item being
replaced is the preferred mailing address.
See _Multi-factor authentication challenges_ above.
operationId: createAddress
x-apiture-implemented: true
tags:
- Addresses
parameters:
- name: replaceId
in: query
description: >-
An optional `_id` of an existing address to be _replaced_ with this new address instead of adding a new address, once it has been
approved. If `replaceId` matches the `_id` of the preferred mailing address the `preferredMailingAddressId` will also be updated to the
value of `replaceId` once approved (the `Apiture-Challenge` header may be required also). If no existing address matches `replaceId`, the
new address is added to the list of addresses. Example: `?replaceId=ha1`
schema:
type: string
- $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 may 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/userAddress'
application/json:
schema:
$ref: '#/components/schemas/userAddress'
'400':
$ref: '#/components/responses/400'
'409':
$ref: '#/components/responses/409PreferredConflict'
security:
- apiKey: []
accessToken:
- profiles/write
requestBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/userAddress'
application/json:
schema:
$ref: '#/components/schemas/userAddress'
description: The data necessary to create a new address.
required: true
'/users/{userId}/addresses/{addressId}':
parameters:
- $ref: '#/components/parameters/userIdPathParam'
- $ref: '#/components/parameters/addressIdPathParam'
get:
summary: Fetch a representation of this address
description: 'Return a [HAL](http://developer.apiture.com/docs/concepts/hal) representation of this address resource.'
operationId: getAddress
x-apiture-implemented: true
tags:
- Addresses
parameters:
- $ref: '#/components/parameters/ifNoneMatchHeaderParam'
responses:
'200':
description: OK
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update this address resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/userAddress'
application/json:
schema:
$ref: '#/components/schemas/userAddress'
'304':
$ref: '#/components/responses/304'
'404':
$ref: '#/components/responses/404Address'
security:
- apiKey: []
accessToken:
- profiles/read
delete:
summary: Delete this address resource
description: Delete this address. The address can only be deleted if it is _not_ the user's preferred address.
operationId: deleteAddress
x-apiture-implemented: true
tags:
- Addresses
responses:
'204':
$ref: '#/components/responses/204Deleted'
'409':
$ref: '#/components/responses/409AddressConflict'
security:
- apiKey: []
accessToken:
- profiles/delete
'/users/{userId}/emailAddresses':
parameters:
- $ref: '#/components/parameters/userIdPathParam'
get:
summary: Get user's email addresses
description: Return the list of the user's email addresses.
operationId: getEmailAddresses
x-apiture-implemented: true
tags:
- Email Addresses
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/userEmailAddresses'
application/json:
schema:
$ref: '#/components/schemas/userEmailAddresses'
'400':
$ref: '#/components/responses/400'
'422':
$ref: '#/components/responses/422'
security:
- apiKey: []
accessToken:
- profiles/read
post:
summary: Create a new email address
description: |-
Add an email address to the list of the user's email addresses.
The new email address will be `pending` until the financial institution has
reviewed and approved it, after which it will become `approved`.
This operation may require the user to complete an additional
authentication challenge as described in _Multi-factor
authentication challenges_ above. A valid
`Apiture-Challenge` request header may be required
if the `?replaceId` parameter is used and the profile item being
replaced is the preferred email address.
See _Multi-factor authentication challenges_ above.
operationId: createEmailAddress
x-apiture-implemented: true
tags:
- Email Addresses
parameters:
- name: replaceId
in: query
description: >-
An optional `_id` of an existing email address to be _replaced_ with this new email address instead of adding a new email address, once it
has been approved. If `replaceId` matches the `_id` of the preferred email address the `preferredEmailAddressId` will also be updated to
the value of `replaceId` once approved (the `Apiture-Challenge` header may be required also). If no existing email address matches
`replaceId`, the new email address is added to the list of email addresses. Example: `?replaceId=e1`
schema:
type: string
- $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 may 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/userEmailAddress'
application/json:
schema:
$ref: '#/components/schemas/userEmailAddress'
'400':
$ref: '#/components/responses/400'
'409':
$ref: '#/components/responses/409PreferredConflict'
security:
- apiKey: []
accessToken:
- profiles/write
requestBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/userEmailAddress'
application/json:
schema:
$ref: '#/components/schemas/userEmailAddress'
description: The data necessary to create a new email address.
required: true
'/users/{userId}/emailAddresses/{emailAddressId}':
parameters:
- $ref: '#/components/parameters/userIdPathParam'
- $ref: '#/components/parameters/emailAddressIdPathParam'
get:
summary: Fetch a representation of this email address
description: 'Return a [HAL](http://developer.apiture.com/docs/concepts/hal) representation of this email address resource.'
operationId: getEmailAddress
x-apiture-implemented: true
tags:
- Email Addresses
parameters:
- $ref: '#/components/parameters/ifNoneMatchHeaderParam'
responses:
'200':
description: OK
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update this email address resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/userEmailAddress'
application/json:
schema:
$ref: '#/components/schemas/userEmailAddress'
'304':
$ref: '#/components/responses/304'
'404':
$ref: '#/components/responses/404EmailAddress'
security:
- apiKey: []
accessToken:
- profiles/read
delete:
summary: Delete this email address resource
description: Delete this email address. The email address can only be deleted if it is _not_ the user's preferred email address.
operationId: deleteEmailAddress
x-apiture-implemented: true
tags:
- Email Addresses
responses:
'204':
$ref: '#/components/responses/204Deleted'
'409':
$ref: '#/components/responses/409EmailAddressConflict'
security:
- apiKey: []
accessToken:
- profiles/delete
'/users/{userId}/phoneNumbers':
parameters:
- $ref: '#/components/parameters/userIdPathParam'
get:
summary: Get user's phone numbers
description: Return the list of the user's phone numbers
operationId: getPhoneNumbers
x-apiture-implemented: true
tags:
- Phone Numbers
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/userPhoneNumbers'
application/json:
schema:
$ref: '#/components/schemas/userPhoneNumbers'
'400':
$ref: '#/components/responses/400'
'422':
$ref: '#/components/responses/422'
security:
- apiKey: []
accessToken:
- profiles/read
post:
summary: Create a new phone number
description: |-
Add a phone number to the list of the user's phone numbers.
The new number will be `pending` until the financial institution has
reviewed and approved it, after which it will become `approved`.
This operation may require the user to complete an additional
authentication challenge as described in _Multi-factor
authentication challenges_ above. A valid
`Apiture-Challenge` request header may be required
if the `?replaceId` parameter is used and the profile item being
replaced is the preferred phone number.
See _Multi-factor authentication challenges_ above.
operationId: createPhoneNumber
x-apiture-implemented: true
tags:
- Phone Numbers
parameters:
- name: replaceId
in: query
description: >-
An optional `_id` of an existing phone number to be _replaced_ with this new phone number instead of adding a new phone number, once it
has been approved. If `replaceId` matches the `_id` of the preferred phone number the `preferredPhoneNumberId` will also be updated to the
value of `replaceId` once approved (the `Apiture-Challenge` header may be required also). If no existing phone number matches `replaceId`,
the new phone number is added to the list of phone numbers. Example: `?replaceId=p1`
schema:
type: string
- $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 may 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/userPhoneNumber'
application/json:
schema:
$ref: '#/components/schemas/userPhoneNumber'
'400':
$ref: '#/components/responses/400'
'409':
$ref: '#/components/responses/409PreferredConflict'
security:
- apiKey: []
accessToken:
- profiles/write
requestBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/userPhoneNumber'
application/json:
schema:
$ref: '#/components/schemas/userPhoneNumber'
description: The data necessary to create a new phone number.
required: true
'/users/{userId}/phoneNumbers/{phoneNumberId}':
parameters:
- $ref: '#/components/parameters/userIdPathParam'
- $ref: '#/components/parameters/phoneNumberIdPathParam'
get:
summary: Fetch a representation of this phone number
description: 'Return a [HAL](http://developer.apiture.com/docs/concepts/hal) representation of this phone number resource.'
operationId: getPhoneNumber
x-apiture-implemented: true
tags:
- Phone Numbers
parameters:
- $ref: '#/components/parameters/ifNoneMatchHeaderParam'
responses:
'200':
description: OK
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update this phone number resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/userPhoneNumber'
application/json:
schema:
$ref: '#/components/schemas/userPhoneNumber'
'304':
$ref: '#/components/responses/304'
'404':
$ref: '#/components/responses/404PhoneNumber'
security:
- apiKey: []
accessToken:
- profiles/read
delete:
summary: Delete this phone number resource
description: Delete this phone number. The number can only be deleted if it is _not_ the user's preferred phone number.
operationId: deletePhoneNumber
x-apiture-implemented: true
tags:
- Phone Numbers
responses:
'204':
$ref: '#/components/responses/204Deleted'
'409':
$ref: '#/components/responses/409PhoneNumberConflict'
security:
- apiKey: []
accessToken:
- profiles/delete
'/users/{userId}/preferredAddress':
parameters:
- $ref: '#/components/parameters/userIdPathParam'
put:
summary: Set Preferred mailing Address
description: |-
Set the user's preferred mailing address.
The user may set their preferred address
to an _approved_ address by passing its
unique `_id` in the `value` query parameter.
This updates the `preferredAddressId`
property of the user.
This operation may require the user to complete an additional
authentication challenge as described in _Multi-factor
authentication challenges_ above. A valid
`Apiture-Challenge` request header may be required.
This operation is available via the `apiture:setAsPreferred`
link on an address if that resource is eligible
to be set as the preferred address.
No changes are made if the specified address is
already the preferred address.
operationId: setPreferredAddress
x-apiture-implemented: true
tags:
- Addresses
security:
- apiKey: []
accessToken:
- profiles/write
parameters:
- name: value
description: >-
The `_id` of the address to assign as the preferred address. If this query parameter exists, the request body, if any, is ignored.
Example: `?value=ha1`
in: query
schema:
type: string
- $ref: '#/components/parameters/apitureChallengeHeaderParam'
responses:
'200':
description: OK. The user's `preferredAddressId` is updated to the passed value.
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update this user resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/user'
application/json:
schema:
$ref: '#/components/schemas/user'
'409':
$ref: '#/components/responses/409PreferredConflict'
'422':
$ref: '#/components/responses/422PreferredUnprocessable'
'/users/{userId}/preferredEmailAddress':
parameters:
- $ref: '#/components/parameters/userIdPathParam'
put:
summary: Set Preferred Email Address
description: |-
Set the user's preferred email address.
The user may set their preferred email address
to an _approved_ address by passing its
unique `_id` in the `value` query parameter.
This updates the `preferredEmailAddressId`
property of the user.
This operation may require the user to complete an additional
authentication challenge as described in _Multi-factor
authentication challenges_ above. A valid
`Apiture-Challenge` request header may be required.
This operation is available via the `apiture:setAsPreferred`
link on an email address if that resource is eligible
to be set as the preferred email address.
No changes are made if the specified email address is
already the preferred email address.
operationId: setPreferredEmailAddress
x-apiture-implemented: true
tags:
- Email Addresses
security:
- apiKey: []
accessToken:
- profiles/write
parameters:
- name: value
description: >-
The `_id` of the email address to assign as the preferred email address. If this query parameter exists, the request body, if any, is
ignored. Example: `?value=pe0`
in: query
schema:
type: string
- $ref: '#/components/parameters/apitureChallengeHeaderParam'
responses:
'200':
description: OK. The user's `preferredEmailAddressId` is updated to the passed value.
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update this user resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/user'
application/json:
schema:
$ref: '#/components/schemas/user'
'409':
$ref: '#/components/responses/409PreferredConflict'
'422':
$ref: '#/components/responses/422PreferredUnprocessable'
'/users/{userId}/preferredPhoneNumber':
parameters:
- $ref: '#/components/parameters/userIdPathParam'
put:
summary: Set Preferred Phone Number
description: |-
Set the user's preferred phone number.
The user may set their preferred phone number
to an _approved_ number by passing its
unique `_id` in the `value` query parameter.
This updates the `preferredPhoneNumberId`
property of the user.
This operation may require the user to complete an additional
authentication challenge as described in _Multi-factor
authentication challenges_ above. A valid
`Apiture-Challenge` request header may be required.
This operation is available via the `apiture:setAsPreferred`
link on an phone number if that resource is eligible
to be set as the preferred phone number.
No changes are made if the specified phone number is
already the preferred phone number.
operationId: setPreferredPhoneNumber
x-apiture-implemented: true
tags:
- Phone Numbers
security:
- apiKey: []
accessToken:
- profiles/write
parameters:
- name: value
description: >-
The `_id` of the number to assign as the preferred phone number. If this query parameter exists, the request body, if any, is ignored.
Example: `?value=pe0`
in: query
schema:
type: string
- $ref: '#/components/parameters/apitureChallengeHeaderParam'
responses:
'200':
description: OK. The user's `preferredPhoneNumberId` is updated to the passed value.
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update this user resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/user'
application/json:
schema:
$ref: '#/components/schemas/user'
'409':
$ref: '#/components/responses/409PreferredConflict'
'422':
$ref: '#/components/responses/422PreferredUnprocessable'
/:
get:
summary: Top-level resources and operations in this API
description: |-
Return links to the top-level resources and operations in this API. Links in the root response may include:
* [*`apiture:me`*](#op-getUser): The current authenticated user
* [*`apiture:users`*](#op-getUsers): The collection of all users
* [*`apiture:createUser`*](#op-createUser): Create a new user (via `POST`) with [`createUser`](#schema-createUser) schema.
* [*`getLabels`*](#op-getLabels): Retrieve labels for the API's enumerations and choice lists
* [*`getApiDoc`*](#op-getApiDoc): Return the OpenAPI document for this API
operationId: getApi
x-apiture-implemented: true
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: []
/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: []
x-apiture-implemented: true
parameters:
- name: Accept-Language
in: header
description: >-
The weighted language tags which indicate the user's preferred natural language for the localized labels in the response, as per [RFC
7231](https://tools.ietf.org/html/rfc7231#section-5.3.5).
schema:
type: string
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/labelGroups'
application/json:
schema:
$ref: '#/components/schemas/labelGroups'
tags:
- API
/users:
get:
summary: Return a collection of users
description: >-
Use this operation to retrieve a [paginated](https://developer.apiture.com/docs/concepts/pagination),
[sortable](https://developer.apiture.com/docs/concepts/sorting), [filterable](https://developer.apiture.com/docs/concepts/filtering),
[searchable](https://developer.apiture.com/docs/concepts/searchable) collection of users. An authenticated user will have access only to their
User resource. The [links](https://developer.apiture.com/docs/concepts/links) in the response include collection pagination links. Each
resource in the `_embedded.items` array is a summary representation of a user; use the `getUser` operation on the summary's `self` link to get
the full representation of the user and all available links.
operationId: getUsers
security:
- apiKey: []
accessToken:
- profiles/read
tags:
- User
x-apiture-traits:
sortBy:
- state
- occupation
- createdAt
- username
- firstName
- middleName
- lastName
- preferredName
- birthdate
- lastContactedAt
- lastLoggedInAt
itemSchema: user
filters:
state:
filter:
- eq
- ne
- in
occupation:
filter:
- eq
- ne
- in
createdAt:
filter:
- lt
- le
- gt
- ge
customerId:
filter:
- eq
lastLoggedInAt:
filter:
- lt
- le
- gt
- ge
lastContactedAt:
filter:
- lt
- le
- gt
- ge
_id:
filter:
- eq
- in
username:
filter:
- eq
- in
parameters:
- name: start
in: query
description: 'The zero-based index of the first user in this page. The default, 0, represents the first page of the collection.'
schema:
type: integer
format: int64
default: 0
- name: limit
in: query
description: The maximum number of user 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](https://developer.apiture.com/docs/concepts/sorting), such as
`?sortBy=field1,-field2`.
This collection may be sorted by following properties:
• `state`
•
`occupation`
• `createdAt`
• `username`
• `firstName`
• `middleName`
•
`lastName`
• `preferredName`
• `birthdate`
• `lastContactedAt`
• `lastLoggedInAt`
schema:
type: string
- name: filter
in: query
description: >-
Optional filter criteria. See [filtering](https://developer.apiture.com/docs/concepts/filtering).
This collection may be filtered by
following properties and functions:
• Property `state` using functions `eq`, `ne`, `in`
• Property `occupation`
using functions `eq`, `ne`, `in`
• Property `createdAt` using functions `lt`, `le`, `gt`, `ge`
• Property
`customerId` using functions `eq`
• Property `lastLoggedInAt` using functions `lt`, `le`, `gt`, `ge`
• Property
`lastContactedAt` using functions `lt`, `le`, `gt`, `ge`
• Property `_id` using functions `eq`, `in`
• Property
`username` using functions `eq`, `in`
schema:
type: string
- $ref: '#/components/parameters/qQueryParam'
- $ref: '#/components/parameters/stateQueryParam'
- $ref: '#/components/parameters/customerIdQueryParam'
- $ref: '#/components/parameters/occupationQueryParam'
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/users'
application/json:
schema:
$ref: '#/components/schemas/users'
'400':
$ref: '#/components/responses/400'
'422':
$ref: '#/components/responses/422'
post:
summary: Create a new user
operationId: createUser
description: Create a new user resource.
security:
- apiKey: []
accessToken:
- profiles/write
tags:
- User
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
*`schema`*`://host`
schema:
type: string
format: uri
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update the resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/user'
application/json:
schema:
$ref: '#/components/schemas/user'
'202':
description: Accepted
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
*`schema`*`://host`
schema:
type: string
format: uri
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update the resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/user'
application/json:
schema:
$ref: '#/components/schemas/user'
requestBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/createUser'
application/json:
schema:
$ref: '#/components/schemas/createUser'
description: The data necessary to create a new user.
required: true
/userSearch:
post:
summary: Find existing registered user
description: |-
Use this operation to determine if a user is already registered.
Each resource in the `_embedded.items` array is a summary
representation of a user; use the `getUser` operation
on the summary's `self` link to get the full representation
of the user and all available links. If no users match,
the response has an empty (but not `null`) `_embedded.items` array.
This operation uses a "`GET` over `POST`" pattern so that personally sensitive information
(the user's tax identification number) are transmitted securely in the request body
and not in the request URL as query parameters. Like a `GET`, this operation
is idempotent and safe.
This operation is only allowed for trusted services or administrators.
operationId: searchUsers
security:
- apiKey: []
accessToken:
- admin/read
tags:
- User
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/users'
application/json:
schema:
$ref: '#/components/schemas/users'
'400':
$ref: '#/components/responses/400'
'422':
$ref: '#/components/responses/422'
requestBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/userSearch'
application/json:
schema:
$ref: '#/components/schemas/userSearch'
required: true
/encryptionKeys:
get:
summary: Get client-side encryption keys
description: >-
Get encryption keys that the client should use to encrypt sensitive data such as personally identifiable information (PII) and passwords. This
adds security on top of transport layer security (TLS/HTTPS) so that sensitive data is not represented as plain text in request bodies.
Clients should [encrypt properties](https://developer.apiture.com/doc/concepts/encryption) that have a x-apiture-encrypt:
{keyName}
annotation in the schema. The client adds metadata in an `_encryption` object next to the encrypted properties in
the request body.
operationId: getEncryptionKeys
security:
- apiKey: []
tags:
- Encryption
parameters:
- name: keys
in: query
description: >-
A list of encryption key names necessary to encrypt one or more properties in a request body. For example, if the request body schema
contains two fields that are tagged `x-apiture-encrypt: secret`, use `?keys=secret`. If the schema contain two fields, one encrypted with
`password` and one with the key named `pii`, use `?keys=secret,pii`
required: true
style: form
schema:
type: array
items:
type: string
minLength: 1
responses:
'200':
description: OK.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/encryptionKeys'
application/json:
schema:
$ref: '#/components/schemas/encryptionKeys'
'/users/{userId}':
get:
summary: Fetch a representation of this user
description: |-
Return a [HAL](https://developer.apiture.com/docs/concepts/hal)
representation of this user resource.
This representation will contain links related to the current user
as defined in the `user` schema.
operationId: getUser
security:
- apiKey: []
accessToken:
- profiles/read
tags:
- User
parameters:
- $ref: '#/components/parameters/userIdPathParam'
- $ref: '#/components/parameters/ifNoneMatchHeaderParam'
responses:
'200':
description: OK
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update this user resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/user'
application/json:
schema:
$ref: '#/components/schemas/user'
'404':
$ref: '#/components/responses/404User'
put:
summary: Update this user
description: >-
Perform a complete replacement of this user.
Note that the user's `addresses`, `emailAddresses` and `phoneNumbers` are immutable; see the **User addresses, phone numbers, and email
addresses** section in the API description. The user's `userVerificationFields` is also immutable.
operationId: updateUser
security:
- apiKey: []
accessToken:
- profiles/write
x-apiture-implemented: true
tags:
- User
parameters:
- $ref: '#/components/parameters/userIdPathParam'
- $ref: '#/components/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update this user resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/user'
application/json:
schema:
$ref: '#/components/schemas/user'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404User'
'409':
$ref: '#/components/responses/409UserConflict'
'412':
$ref: '#/components/responses/412'
'422':
$ref: '#/components/responses/422'
requestBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/user'
application/json:
schema:
$ref: '#/components/schemas/user'
required: true
patch:
summary: Update this user
description: >-
Perform a partial update of this user. Fields which are omitted are not updated.
Note that the user's `addresses`, `emailAddresses` and `phoneNumbers` are immutable; see the **User addresses, phone numbers, and email
addresses** section in the API description. The user's `userVerificationFields` is also immutable.
operationId: patchUser
security:
- apiKey: []
accessToken:
- profiles/write
x-apiture-implemented: true
tags:
- User
parameters:
- $ref: '#/components/parameters/userIdPathParam'
- $ref: '#/components/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update this user resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/user'
application/json:
schema:
$ref: '#/components/schemas/user'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404User'
'409':
$ref: '#/components/responses/409UserConflict'
'412':
$ref: '#/components/responses/412'
'422':
$ref: '#/components/responses/422'
requestBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/user'
application/json:
schema:
$ref: '#/components/schemas/user'
required: true
/removedUsers:
post:
summary: Remove a user
tags:
- User Actions
description: |-
Remove a user from active use.
This operation is invoked from the `apiture:remove` link on a user
resource when that user is eligible to be removed.
This changes the `state` to `removed`.
operationId: removeUser
security:
- apiKey: []
accessToken:
- profiles/write
parameters:
- name: user
description: The ID or URI of an existing user which is eligible to be removed.
in: query
required: false
schema:
type: string
- $ref: '#/components/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update this user resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/user'
application/json:
schema:
$ref: '#/components/schemas/user'
'400':
description: Bad Request. The `user` was malformed or does not refer to a user.
'409':
$ref: '#/components/responses/409UserConflict'
'412':
$ref: '#/components/responses/412'
'422':
$ref: '#/components/responses/422'
/activeUsers:
post:
summary: Activate a user
tags:
- User Actions
description: |-
Activate a user from an inactive state.
This operation is invoked from the `apiture:activate` link on a user
resource when that user is eligible to be activated.
This operation will fail if the user is frozen or locked unless an FI
admin is invoking the operation.
This changes the `state` to `active`.
operationId: activateUser
security:
- apiKey: []
accessToken:
- profiles/write
parameters:
- name: user
description: The ID or URI of an existing user which is eligible to be removed.
in: query
required: false
schema:
type: string
- $ref: '#/components/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update this user resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/user'
application/json:
schema:
$ref: '#/components/schemas/user'
'400':
description: Bad Request. The `user` was malformed or does not refer to a user.
'409':
$ref: '#/components/responses/409UserConflict'
'412':
$ref: '#/components/responses/412'
'422':
$ref: '#/components/responses/422'
/inactiveUsers:
post:
summary: Deactivate a user
tags:
- User Actions
description: |-
Deactivate a user from an active state.
This operation is invoked from the `apiture:deactivate` link on a user
resource when that user is eligible to be deactivated.
This changes the `state` to `inactive`.
operationId: deactivateUser
security:
- apiKey: []
accessToken:
- profiles/write
parameters:
- name: user
description: The ID or URI of an existing user which is eligible to be removed.
in: query
required: false
schema:
type: string
- $ref: '#/components/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update this user resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/user'
application/json:
schema:
$ref: '#/components/schemas/user'
'400':
description: Bad Request. The `user` was malformed or does not refer to a user.
'409':
$ref: '#/components/responses/409UserConflict'
'412':
$ref: '#/components/responses/412'
'422':
$ref: '#/components/responses/422'
/lockedUsers:
post:
summary: Lock a user
tags:
- User Actions
description: |-
Lock a user from an active or inactive state.
This operation is invoked from the `apiture:lock` link on a user
resource when that user is eligible to be lock.
This changes the `state` to `locked`.
operationId: lockUser
security:
- apiKey: []
accessToken:
- profiles/write
parameters:
- name: user
description: The ID or URI of an existing user which is eligible to be removed.
in: query
required: false
schema:
type: string
- $ref: '#/components/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update this user resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/user'
application/json:
schema:
$ref: '#/components/schemas/user'
'400':
description: Bad Request. The `user` was malformed or does not refer to a user.
'409':
$ref: '#/components/responses/409UserConflict'
'412':
$ref: '#/components/responses/412'
'422':
$ref: '#/components/responses/422'
/frozenUsers:
post:
summary: Freeze a user
tags:
- User Actions
description: |-
Freeze a user from an active, inactive or locked state. A state of
frozen indicates that an admin has a concern of fraud.
This operation is invoked from the `apiture:freeze` link on a user
resource when an admin user has suspicion of fraud. Only admin has
access to freeze a user.
This changes the `state` to `frozen`.
operationId: freezeUser
security:
- apiKey: []
accessToken:
- admin/write
parameters:
- name: user
description: The ID or URI of an existing user which is eligible to be frozen.
in: query
required: false
schema:
type: string
- $ref: '#/components/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update this user resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/user'
application/json:
schema:
$ref: '#/components/schemas/user'
'400':
description: Bad Request. The `user` was malformed or does not refer to a user.
'409':
$ref: '#/components/responses/409UserConflict'
'412':
$ref: '#/components/responses/412'
'422':
$ref: '#/components/responses/422'
'/users/{userId}/constraints':
get:
summary: Fetch a representation of this user's constraints
description: >-
Return a [HAL](https://developer.apiture.com/docs/concepts/hal) representation of this user's constraints resource. Constraints are limits and
other values established for the user, such as single or daily transfer limits.
operationId: getUserConstraints
security:
- apiKey: []
accessToken:
- profiles/read
tags:
- User
parameters:
- $ref: '#/components/parameters/userIdPathParam'
- $ref: '#/components/parameters/ifNoneMatchHeaderParam'
responses:
'200':
description: OK
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update this user resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/constraints'
application/json:
schema:
$ref: '#/components/schemas/constraints'
'404':
$ref: '#/components/responses/404User'
put:
summary: Update this user's constraints
description: Perform a complete replacement of this user's constraints. This operation is performed by an admin. A user cannot change their own limits.
operationId: updateUserConstraints
security:
- apiKey: []
accessToken:
- admin/write
x-apiture-implemented: true
tags:
- User
parameters:
- $ref: '#/components/parameters/userIdPathParam'
- $ref: '#/components/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update this user resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/constraints'
application/json:
schema:
$ref: '#/components/schemas/constraints'
'404':
$ref: '#/components/responses/404User'
'412':
$ref: '#/components/responses/412'
'422':
$ref: '#/components/responses/422'
requestBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/updateConstraints'
application/json:
schema:
$ref: '#/components/schemas/updateConstraints'
required: true
patch:
summary: Update this user's constraints
description: >-
Perform a partial update of this user's constraints, a user should not be able to change their own limits. Fields which are omitted are not
updated.
operationId: patchUserConstraints
security:
- apiKey: []
accessToken:
- admin/write
x-apiture-implemented: true
tags:
- User
parameters:
- $ref: '#/components/parameters/userIdPathParam'
- $ref: '#/components/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update this user resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/constraints'
application/json:
schema:
$ref: '#/components/schemas/constraints'
'404':
$ref: '#/components/responses/404User'
'412':
$ref: '#/components/responses/412'
'422':
$ref: '#/components/responses/422'
requestBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/updateConstraints'
application/json:
schema:
$ref: '#/components/schemas/updateConstraints'
required: true
/configurations/groups:
get:
summary: Return a collection of configuration groups
description: >-
Return a [paginated](https://developer.apiture.com/docs/concepts/pagination) [sortable](https://developer.apiture.com/docs/concepts/sorting)
[filterable](https://developer.apiture.com/docs/concepts/filtering) [searchable](https://developer.apiture.com/docs/concepts/searchable)
collection of configuration groups. The [links](https://developer.apiture.com/docs/concepts/links) in the response include pagination links.
operationId: getConfigurationGroups
security:
- apiKey: []
accessToken:
- profiles/read
tags:
- Configuration
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/configurationGroups'
application/json:
schema:
$ref: '#/components/schemas/configurationGroups'
'400':
$ref: '#/components/responses/400'
'422':
$ref: '#/components/responses/422'
'/configurations/groups/{groupName}':
get:
summary: Fetch a representation of this configuration group
description: 'Return a [HAL](https://developer.apiture.com/docs/concepts/hal) representation of this configuration group resource.'
operationId: getConfigurationGroup
security:
- apiKey: []
accessToken:
- profiles/read
tags:
- Configuration
parameters:
- $ref: '#/components/parameters/configurationGroupNamePathParam'
- $ref: '#/components/parameters/ifNoneMatchHeaderParam'
responses:
'200':
description: OK
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-None-Match` request header for *`GET`* operations
for this configuration group resource.
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/configurationGroup'
application/json:
schema:
$ref: '#/components/schemas/configurationGroup'
'304':
$ref: '#/components/responses/304'
'404':
$ref: '#/components/responses/404ConfigurationGroup'
'/configurations/groups/{groupName}/schema':
get:
summary: Fetch the schema for this configuration group
description: 'Return a [HAL](https://developer.apiture.com/docs/concepts/hal) representation of this configuration group schema resource.'
operationId: getConfigurationGroupSchema
security:
- apiKey: []
accessToken:
- profiles/read
tags:
- Configuration
parameters:
- $ref: '#/components/parameters/configurationGroupNamePathParam'
- $ref: '#/components/parameters/ifNoneMatchHeaderParam'
responses:
'200':
description: OK
headers:
ETag:
description: The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`*
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/configurationSchema'
application/json:
schema:
$ref: '#/components/schemas/configurationSchema'
'304':
$ref: '#/components/responses/304'
'404':
$ref: '#/components/responses/404ConfigurationGroup'
'/configurations/groups/{groupName}/values':
get:
summary: Fetch the values for the specified configuration group
description: Return a representation of this configuration group values resource.
operationId: getConfigurationGroupValues
security:
- apiKey: []
accessToken:
- profiles/read
tags:
- Configuration
parameters:
- $ref: '#/components/parameters/configurationGroupNamePathParam'
- $ref: '#/components/parameters/ifNoneMatchHeaderParam'
responses:
'200':
description: OK
headers:
ETag:
description: The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`*
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/configurationValues'
application/json:
schema:
$ref: '#/components/schemas/configurationValues'
'304':
$ref: '#/components/responses/304'
'404':
$ref: '#/components/responses/404ConfigurationGroup'
put:
summary: Update the values for the specified configuration group
description: Perform a complete replacement of this set of values
operationId: updateConfigurationGroupValues
security:
- apiKey: []
accessToken:
- admin/write
tags:
- Configuration
parameters:
- $ref: '#/components/parameters/configurationGroupNamePathParam'
- $ref: '#/components/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK
headers:
ETag:
description: The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`*
schema:
type: string
content:
application/hal+json:
schema:
$ref: '#/components/schemas/configurationSchema'
application/json:
schema:
$ref: '#/components/schemas/configurationSchema'
'400':
$ref: '#/components/responses/400'
'403':
description: Access denied. Only user allowed to update configurations is an admin.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'404':
$ref: '#/components/responses/404ConfigurationGroup'
'412':
$ref: '#/components/responses/412'
requestBody:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/configurationValues'
application/json:
schema:
$ref: '#/components/schemas/configurationValues'
required: true
'/configurations/groups/{groupName}/values/{valueName}':
get:
summary: Fetch a single value associated with the specified configuration group
description: >-
Fetch a single value associated with this configuration group. This provides convenient access to individual values of the configuration
group. The response is always a JSON value which can be parsed with a strict JSON parser. The response may be
* a primitive number, boolean, or quoted JSON string.
* a JSON array.
* a JSON object.
* `null`.
Examples:
* `"a string configuration value"`
* `120`
* `true`
* `null`
* `{ "borderWidth": 8, "foregroundColor": "blue" }`
To update a specific value, use `PUT /users/configurations/groups/{groupName}/values/{valueName}` (operation `updateConfigurationGroupValue`).
operationId: getConfigurationGroupValue
security:
- apiKey: []
accessToken:
- profiles/read
tags:
- Configuration
parameters:
- $ref: '#/components/parameters/configurationGroupNamePathParam'
- $ref: '#/components/parameters/configurationGroupValueNamePathParam'
responses:
'200':
description: 'OK. The value of the named configuration value as a JSON string, number, boolean, array, or object.'
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update this configuration group resource.
schema:
type: string
content:
application/hal+json:
schema:
type: string
application/json:
schema:
type: string
'404':
$ref: '#/components/responses/404ConfigurationGroupOrValue'
put:
summary: Update a single value associated with the specified configuration group
description: >-
Update a single value associated with this configuration group. This provides convenient access to individual values of the configuration
group as defined in the configuration group's `schema`. The request body must conform to the configuration group's schema for the named
`{valueName}`. This operation is idempotent. The request body must be a JSON value which can be parsed with a strict JSON parser. The response
may be
* a primitive number, boolean, or quoted JSON string.
* a JSON array.
* a JSON object.
* `null`.
Examples:
* `"a string configuration value"`
* `120`
* `true`
* `null`
* `{ "borderWidth": 8, "foregroundColor": "blue" }`
To fetch specific value, use `GET /users/configurations/groups/{groupName}/values/{valueName}` (operation `getConfigurationGroupValue`).
operationId: updateConfigurationGroupValue
security:
- apiKey: []
accessToken:
- admin/write
tags:
- Configuration
parameters:
- $ref: '#/components/parameters/configurationGroupNamePathParam'
- $ref: '#/components/parameters/configurationGroupValueNamePathParam'
responses:
'200':
description: OK
headers:
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update this configuration group resource.
schema:
type: string
content:
application/hal+json:
schema:
type: string
application/json:
schema:
type: string
'403':
description: Access denied. Only user allowed to update configurations is an admin.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
requestBody:
content:
application/hal+json:
schema:
type: string
application/json:
schema:
type: string
description: >-
The request body must a valid JSON value and should be parsable with a JSON parser. The result may be a string, number, boolean, array, or
object.
required: true
x-apiture-errors:
invalidUserId:
description: No Users were found for the specified userId
remediation: Check to make sure that the supplied userId corresponds to an apiture user resource
updateUserError:
description: There was an error updating the user with the given userId
remediation: 'Check to make sure that the user was not updated and resubmit the operation, if it was not'
duplicateUsername:
description: A user with the given username already exists
remediation: Resubmit the operation with a unique username
duplicateTaxId:
description: A user with the given taxId already exists
remediation: Resubmit the operation with a unique taxId
cannotUpdateState:
description: A users state cannot be updated using put
remediation: >-
See the apiture API documentation about using the /removedUsers, /activeUsers, /inactiveUsers, /lockedUsers and /frozenUsers endpoints to update
state
invalidStateChange:
description: A user can only be changed to a different state if they meet the current state requirement
remediation: Check the state of the user and the applicable allowed state transitions in the Users API documentation
attributes:
properties:
requiredStates:
type: array
items:
type: string
description: A list of states the user must be in in order for this state change request to be valid.
example:
- inactive
malformedRequestBody:
description: The supplied request body was malformed
remediation: Check to make sure that your request body exists and that it does not contain syntax errors
implicit:
- '400'
requestError:
description: There was a server side error when executing the API request
remediation: Check your parameters and resubmit the request
implicit:
- 5xx
cannotChangeId:
description: The id of a resource cannot be changed
remediation: Please submit the correct id if you must include it in the request body
invalidPhoneType:
description: An invalid phone type was given
remediation: Resubmit the operation with a valid phone type according to the Users API documentation
attributes:
properties:
validTypes:
description: A list of allowed phone number types.
type: array
items:
type: string
example:
- home
- mobile
- work
- fax
- school
- other
invalidAddressType:
description: An invalid address type was given
remediation: Resubmit the operation with a valid address type according to the Users API documentation
attributes:
properties:
validTypes:
description: A list of allowed address types.
type: array
items:
type: string
example:
- home
- mailing
- home
- prior
- work
- vacation
- shipping
- billing
- headquarters
- location
- property
- school
- commercial
- other
noSuchProfileValue:
description: The selected profile value _id does not exist
remediation: Pass the _id of an existing item
noSuchChallenge:
description: The challenge resource specified in the Apiture-Challenge request header does not exist
remediation: 'Pass the _id of an existing, unexpired, unredeemed challenge.'
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
itemStillPending:
description: The selected item cannot be assigned as preferred profile data because it is still `pending`.
remediation: Pass the _id of an `approved` profile item.
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.'
x-apiture-traits:
- api:
links:
- getApi
- getApiDoc
- getUsers
- createUser
- getLabels
applied: true
- resource:
name: address
pluralName: addresses
resourceSchema: userAddress
collectionSchema: userAddresses
excludeMethods:
- put
- patch
pathPrefix: '/users/{userId}'
paginated: false
sortable: false
filterable: false
searchable: false
simpleModelSchema: true
article: an
applied: true
- resource:
name: email address
pluralName: email addresses
resourceSchema: userEmailAddress
collectionSchema: userEmailAddresses
excludeMethods:
- put
- patch
pathPrefix: '/users/{userId}'
paginated: false
sortable: false
filterable: false
searchable: false
simpleModelSchema: true
article: an
applied: true
- resource:
name: phone number
resourceSchema: userPhoneNumber
collectionSchema: userPhoneNumbers
excludeMethods:
- put
- patch
pathPrefix: '/users/{userId}'
paginated: false
sortable: false
filterable: false
searchable: false
simpleModelSchema: true
applied: true
- security:
baseScope: profiles
applied: true
x-apiture-annotated-at: '2020-10-02T13:42:07.886Z'
components:
schemas:
userAddress:
title: User Address (v1.0.0)
description: >
Representation of a user's address resource.
Links
Response and request bodies using this userAddress
schema may contain
the following links:
x-apiture-links:
- rel: delete
operationId: deleteAddress
- rel: 'apiture:setAsPreferred'
operationId: setPreferredAddress
example:
_id: ha1
type: home
addressLine1: 555 N Front Street
addressLine2: Suite 5555
city: Wilmington
regionCode: NC
postalCode: 28401-5405
countryCode: US
state: approved
_links:
self:
href: /users/users/f2d87aa6-33c8-458c-819b-41bb00f1ec08/addresses/ha1
x-apiture-version: 1.0.0
x-apiture-composition:
- $ref: '#/components/schemas/address'
- $ref: '#/components/schemas/abstractResource'
- properties:
- state
properties:
addressLine1:
description: 'The first street address line of the address, normally a house number and street name.'
type: string
minLength: 4
maxLength: 128
addressLine2:
description: The optional second street address line of the address.
type: string
maxLength: 128
city:
description: The name of the city or municipality.
type: string
minLength: 2
maxLength: 128
regionCode:
description: 'The mailing address region code, such as state in the US, or a province in Canada. This is normalized to uppercase.'
type: string
example: NC
minLength: 2
maxLength: 2
pattern: '^[a-zA-Z]{2}$'
postalCode:
description: 'The mailing address postal code, such as a US Zip or Zip+4 code, or a Canadian postal code.'
type: string
example: 28401-5405
minLength: 5
maxLength: 10
pattern: '^[0-9]{5}(?:-[0-9]{4})?$'
countryCode:
description: 'The [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. This is normalized to uppercase.'
type: string
minLength: 2
maxLength: 2
pattern: '^[a-zA-Z]{2}$'
type:
description: The type of this address.
allOf:
- $ref: '#/components/schemas/addressType'
label:
description: 'A text label, suitable for presentation to the end user. This is derived from `type` or from `otherType` if `type` is `other`'
type: string
readOnly: true
minLength: 4
maxLength: 32
otherType:
description: The actual address type if `type` is `other`.
minLength: 4
maxLength: 32
type: string
_id:
description: >-
An identifier for this address, so that it can be referenced uniquely. The service will assign a unique `_id` if the client does not
provide one. The `_id` must be unique across all addresses within the `addresses` array.
type: string
minLength: 1
maxLength: 8
example: ha5
pattern: '^[-a-zA-Z0-9_]{1,8}$'
_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'
state:
description: >-
The state of this address. `pending` addresses require financial institution approval. Only `approved` addresses may be set as the
preferred address.
allOf:
- $ref: '#/components/schemas/profileItemState'
type: object
x-apiture-flattened: true
userAddresses:
title: User Addresses (v1.0.0)
description: The list of the user's addresses.
example:
_profile: 'https://api.apiture.com/schemas/users/userAddresses/v1.0.0/profile.json'
items:
anyOf:
- _id: ha1
type: home
addressLine1: 555 N Front Street
addressLine2: Suite 5555
city: Wilmington
regionCode: NC
postalCode: 28401-5405
countryCode: US
state: approved
_links:
self:
href: /users/users/f2d87aa6-33c8-458c-819b-41bb00f1ec08/addresses/ha1
- _id: wa1
type: work
addressLine1: 123 S 3rd Street
addressLine2: Apt 42
city: Wilmington
regionCode: NC
postalCode: 28411-5405
countryCode: US
_links:
self:
href: /users/users/f2d87aa6-33c8-458c-819b-41bb00f1ec08/addresses/wa1
_links:
self:
href: /users/users/f2d87aa6-33c8-458c-819b-41bb00f1ec08/addresses
x-apiture-version: 1.0.0
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- properties:
- items
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'
items:
description: An array containing address items.
type: array
items:
$ref: '#/components/schemas/userAddress'
type: object
x-apiture-flattened: true
userEmailAddress:
title: Email Address (v1.0.1)
description: >
Representation of email address resources. An email address is immutable, although users can add new email addresses.
Links
Response and request bodies using this userEmailAddress
schema may contain
the following links:
x-apiture-version: 1.0.1
x-apiture-links:
- rel: delete
operationId: deleteEmailAddress
- rel: 'apiture:setAsPreferred'
operationId: setPreferredEmailAddress
example:
_id: pe1
_profile: 'https://api.apiture.com/schemas/users/userEmailAddress/v1.0.1/profile.json'
type: personal
value: user7838@example.com
state: approved
_links:
self:
href: /users/users/f2d87aa6-33c8-458c-819b-41bb00f1ec08/emailAddresses/pe1
delete:
href: /users/users/f2d87aa6-33c8-458c-819b-41bb00f1ec08/emailAddresses/pe1
'apiture:setAsPreferred':
href: /users/users/f2d87aa6-33c8-458c-819b-41bb00f1ec08/preferredEmailAddresses?value=pe1
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- $ref: '#/components/schemas/typedEmailAddress'
- properties:
- state
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'
value:
description: 'The email address, such as `JohnBankCustomer@example.com`'
type: string
format: email
minLength: 8
maxLength: 120
example: JohnBankCustomer@example.com
type:
description: The kind of email address.
allOf:
- $ref: '#/components/schemas/emailType'
_id:
description: >-
An identifier for this email address, so that it can be referenced uniquely. The service will assign a unique `_id` if the client does not
provide one. The `_id` must be unique across all email addresses within the `emailAddresses` array.
type: string
minLength: 1
maxLength: 8
example: ha3
pattern: '^[-a-zA-Z0-9_]{1,8}$'
state:
description: >-
The state of this email address. `pending` email addresses require financial institution approval. Only `approved` numbers may be set as
the preferred email address.
allOf:
- $ref: '#/components/schemas/profileItemState'
type: object
x-apiture-flattened: true
userEmailAddresses:
title: The user's email addresses (v1.0.1)
description: The list of the user's email addresses.
x-apiture-version: 1.0.1
example:
_profile: 'https://api.apiture.com/schemas/users/userEmailAddresses/v1.0.1/profile.json'
items:
anyOf:
- _id: pe0
type: personal
label: Personal
value: user7838@example.com
state: approved
_profile: 'https://api.apiture.com/schemas/users/userEmailAddress/v1.0.1/profile.json'
_links:
self:
href: /users/users/f2d87aa6-33c8-458c-819b-41bb00f1ec08/emailAddresses/pe0
- _id: pe2
type: personal
label: Personal
value: John.Smith@example.com
state: approved
_profile: 'https://api.apiture.com/schemas/users/userEmailAddress/v1.0.1/profile.json'
_links:
self:
href: /users/users/f2d87aa6-33c8-458c-819b-41bb00f1ec08/userEmailAddresses/pe2
_links:
self:
href: /users/users/f2d87aa6-33c8-458c-819b-41bb00f1ec08/emailAddresses
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- properties:
- items
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'
items:
description: An array containing email address items.
type: array
items:
$ref: '#/components/schemas/userEmailAddress'
type: object
x-apiture-flattened: true
userPhoneNumber:
title: Phone Number (v1.0.1)
description: >
Representation of phone number resources.
Links
Response and request bodies using this userPhoneNumber
schema may contain
the following links:
x-apiture-version: 1.0.1
x-apiture-links:
- rel: delete
operationId: deletePhoneNumber
- rel: 'apiture:setAsPreferred'
operationId: setPreferredPhoneNumber
example:
_id: hp1
_profile: 'https://api.apiture.com/schemas/users/userPhoneNumber/v1.0.1/profile.json'
type: home
number: '+19105550155'
state: approved
_links:
self:
href: /users/users/9b0387db-8705-469a-852c-ead8bfd872ba/phoneNumbers/hp1
x-apiture-composition:
- $ref: '#/components/schemas/phoneNumber'
- $ref: '#/components/schemas/abstractResource'
- properties:
- state
properties:
type:
description: The type or role of this phone number.
allOf:
- $ref: '#/components/schemas/phoneNumberType'
number:
description: >-
The phone number, as a string. The service strips all spaces, hyphens, periods and parentheses from input. The default country code prefix
is `+1`. Phone numbers are returned in responses in [E.164](https://en.wikipedia.org/wiki/E.164) format with a leading `+`, country code
(up to 3 digits) and subscriber number for a total of up to 15 digits. See [Phone Number
Representations](https://developer.apiture.com/docs/concepts/phone-numbers/) for more information.
type: string
example: '+19105550155'
minLength: 8
maxLength: 20
label:
description: 'A text label, suitable for presentation to the end user. This is also used if `type` is `other`.'
type: string
example: assistant
maxLength: 32
_id:
description: >-
An identifier for this phone number, so that it can be referenced uniquely. The service will assign a unique `_id` if the client does not
provide one. The `_id` must be unique across all phone numbers within the `phones` array.
type: string
minLength: 1
maxLength: 8
example: ha5
pattern: '^[-a-zA-Z0-9_]{1,8}$'
_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'
state:
description: >-
The state of this phone number. `pending` numbers require financial institution approval. Only `approved` numbers may be set as the
preferred phone number.
allOf:
- $ref: '#/components/schemas/profileItemState'
type: object
x-apiture-flattened: true
userPhoneNumbers:
title: The user's phone numbers (v1.0.1)
description: The list of the user's phone numbers.
x-apiture-version: 1.0.1
example:
_profile: 'https://api.apiture.com/schemas/users/userPhoneNumbers/v1.0.1/profile.json'
items:
anyOf:
- _id: mp0
type: mobile
label: Mobile
number: '+19105550155'
state: approved
_profile: 'https://api.apiture.com/schemas/users/userPhoneNumber/v1.0.1/profile.json'
_links:
self:
href: /users/users/9b0387db-8705-469a-852c-ead8bfd872ba/phoneNumbers/mp0
- _id: mp2
type: home
label: Home
number: '+19105551044'
state: approved
_profile: 'https://api.apiture.com/schemas/users/userPhoneNumber/v1.0.1/profile.json'
_links:
self:
href: /users/users/9b0387db-8705-469a-852c-ead8bfd872ba/phoneNumbers/mp2
_links:
self:
href: /users/users/9b0387db-8705-469a-852c-ead8bfd872ba/phoneNumbers
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- properties:
- items
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'
items:
description: An array containing phone number items.
type: array
items:
$ref: '#/components/schemas/userPhoneNumber'
type: object
x-apiture-flattened: true
profileItemState:
title: User Profile Item State (v1.0.0)
description: >-
The state of an item (address, email address, or phone number) within the user's profile. New addresses, email addresses, or phone numbers
start with the state `pending`, which means approval by the financial institution is pending. After they have been verified, the state becomes
`approved`. Some normalizing or sanitizing of the value may occur when this happens (for example, a ZIP code may change to ZIP+4 format).
`pending` items may not be assigned as the preferred item.
type: string
enum:
- pending
- approved
example: approved
x-apiture-version: 1.0.0
x-apiture-flattened: true
userVerificationFields:
title: User Verification Fields (v1.1.0)
description: >-
Fields for recording the status of user verification for a financial institution's Customer Identification Program (CIP). (This fragment
schema is used to build other schemas.)
type: object
x-apiture-version: 1.1.0
properties:
kycAnswers:
description: This user's answers Know Your Customer (KYC) questions.
x-apiture-pii: true
readOnly: true
allOf:
- $ref: '#/components/schemas/kycAnswers'
identityVerificationStatus:
description: >-
The identity verification status for this person. This field is read-only and is derived from the results of any Identity API verification
applied to this user's personally identifiable information (PII).
readOnly: true
allOf:
- $ref: '#/components/schemas/userIdentityVerificationState'
identityVerification:
description: >-
The identity verification data for this person. These fields are derived from the results from the results of any Identity API
verification applied to this user's personally identifiable information (PII).
**Warning**: The property `identityVerification` was
deprecated on version `v1.1.0` of the schema. Use identity information in Identity service instead. `identityVerification` will be removed
on version `v2.0.0` of the schema.
type: object
readOnly: true
allOf:
- $ref: '#/components/schemas/identityVerification'
x-apiture-deprecated:
since: 1.1.0
removeOn: 2.0.0
replacement: identity information in Identity service
x-apiture-flattened: true
userIdentityVerificationState:
title: User Identity Verification State (v1.0.0)
description: |-
The status of the user identity verification.
userIdentityVerificationState
strings may have one of the following
[enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations):
Value | Description |
unknown | Unknown |
verified | Verified |
unverified | UnVerified |
These enumeration values are further described by the [label group](https://developer.apiture.com/concepts/label-groups)
named `userIdentityVerificationState` in the response from the [`getLabels`](#op-getLabels) operation.
type: string
x-apiture-enum: userIdentityVerificationState
enum:
- unknown
- verified
- unverified
x-apiture-version: 1.0.0
x-apiture-flattened: true
kycAnswers:
title: Know Your Customer Answers (v1.0.0)
description: Answers to 'Know Your Customer' questions which allow financial institutions to conform to a customer identification program.
properties:
citizen:
description: '`true` if the person is a citizen of the country in which the financial institution is doing business.'
type: boolean
permanentResident:
description: '`true` if the person is a permanent resident of the country in which the financial institution is doing business.'
type: boolean
w9Withholdings:
description: '`true` if the person is a subject to backup W-9 Tax Withholdings.'
type: boolean
employmentStatus:
description: The employment status of the person.
allOf:
- $ref: '#/components/schemas/employmentStatus'
foreignPoliticalFigure:
title: Foreign Senior Political Figure
description: '`true` if the person is a foreign senior political figure.'
type: boolean
default: false
countryPoliticalFigure:
description: >-
If the person is a foreign senior political figure, this is the foreign country. This field is omitted if `foreignPoliticalFigure` is
`false`.
type: string
familyOfPoliticalFigure:
title: Family of Political Figure
description: '`true` if the person is an immediate family member or a close associate of political figure.'
type: boolean
foreignPoliticalFigureCountry:
title: Foreign Senior Political Country
description: >-
If the person is a foreign senior political figure, this is the foreign country ISO 3166-1 country code. This field is omitted if
`foreignPoliticalFigure` is `false`.
type: string
maxLength: 2
foreignPoliticalFigureAssociation:
title: Association with Foreign Senior Political Figure
description: The type of association to a foreign political figure.
allOf:
- $ref: '#/components/schemas/foreignPoliticalFigureAssociation'
x-apiture-version: 1.0.0
type: object
x-apiture-flattened: true
employmentStatus:
title: Employment Status (v1.0.0)
x-apiture-version: 1.0.0
description: |-
The employment status of the user.
The allowed values for this property are defined at runtime in the
[label group](https://developer.apiture.com/concepts/label-groups) named `employmentStatus`
in the response from the [`getLabels`](#op-getLabels) operation.
type: string
x-apiture-choice: employmentStatus
x-apiture-flattened: true
foreignPoliticalFigureAssociation:
title: foreign Political Figure Association (v1.0.0)
description: >-
The type of association to a foreign political figure. This enumeration is described by the foreignPoliticalFigureAssociation value from the
`getLabels` operation.
foreignPoliticalFigureAssociation
strings may have one of the following
[enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations):
Value | Description |
unknown | Unknown: The association status of this individual is unknown. |
closeAssociate | Close Associate: This individual is a close associate of a foreign political figure. |
familyMember | Family Member: This individual is a family member of a foreign political figure. |
none | None: This individual has no association to a foreign political figure. |
other | Other |
notApplicable | Not Applicable |
These enumeration values are further described by the [label group](https://developer.apiture.com/concepts/label-groups)
named `foreignPoliticalFigureAssociation` in the response from the [`getLabels`](#op-getLabels) operation.
type: string
enum:
- unknown
- closeAssociate
- familyMember
- none
- other
- notApplicable
x-apiture-enum: foreignPoliticalFigureAssociation
x-apiture-version: 1.0.0
x-apiture-flattened: true
identityVerification:
title: Identity Verification Data (v1.1.0)
description: >-
Data points on the identity verification process that tells if a user has passed, failed or expired the identity check.
**Warning**: The
schema `identityVerification` was deprecated on version `v0.19.0` of the API. Use identity information in Identity service instead.
`identityVerification` will be removed on version `v0.21.0` of the API.
x-apiture-version: 1.1.0
x-apiture-deprecated:
since: 0.19.0
removeOn: 0.21.0
replacement: identity information in Identity service
properties:
provider:
title: Identity verification provider
description: The name of the identity verification provider.
type: string
sessionId:
title: Session Id
description: The unique id for a session of the identity verification process.
type: string
scoredAt:
title: Time Stamp scored at
description: 'The date-time when the provider ran identity verification. This is an [RFC 3339](https://tools.ietf.org/html/rfc3339) time stamp.'
type: string
format: date-time
example: '2019-09-13T06:11:01.375Z'
score:
title: Verification Score
description: The indication if the user has passed or failed the identity verification process.
type: string
enum:
- passed
- failed
- expired
state:
title: Verification State
description: >-
The identity verification status for this person. This field is read-only and is derived from the results of any identity verification
processes executed against the personally identifiable information (PII) contained in this record.
type: string
readOnly: true
enum:
- verified
- unverified
type: object
x-apiture-flattened: true
userState:
title: User State (v1.0.0)
description: |-
The state of this user resource.
userState
strings may have one of the following
[enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations):
Value | Description |
active | active: The user has been activated after intial creation, or reactivated after being locked or after being frozen by an FI admin. |
inactive | inactive: The user has been deactivated after inactivity for a certain amount of days. |
locked | locked: The user has entered the incorrect password too many times and now needs to reset their password. |
frozen | frozen: The user has been frozen by the financial institution or reasons including suspicion of fraudulent activity. |
removed | removed: The user has been removed can not be reactivated, for example an old user account not being used anymore. |
These enumeration values are further described by the [label group](https://developer.apiture.com/concepts/label-groups)
named `userState` in the response from the [`getLabels`](#op-getLabels) operation.
type: string
enum:
- active
- inactive
- locked
- frozen
- removed
x-apiture-enum: userState
example: active
x-apiture-version: 1.0.0
x-apiture-flattened: true
userFields:
title: Common fields of a user (v1.1.3)
description: |-
Fields for a user.
(This fragment schema is used to build other schemas.)
To change user addresses, email addresses, and phone numbers, use
operations on the sub-resources (`/users/{userId}/addresses`,
`/users/{userId}/emailAddresses`, and `/users/{userId}/phoneNumbers`).
x-apiture-fragment: true
x-apiture-version: 1.1.3
type: object
x-apiture-composition:
- $ref: '#/components/schemas/identifiedContact'
- $ref: '#/components/schemas/userVerificationFields'
- properties:
- username
- state
- addresses
- yearsAtAddress
- preferredMailingAddressId
- phoneNumbers
- preferredPhoneId
- emailAddresses
- preferredEmailAddressId
properties:
firstName:
description: The person's first name (or given name).
type: string
middleName:
description: The person's middle name.
type: string
lastName:
description: The person's last name (or surname).
type: string
addresses:
description: An array of postal/mailing addresses. Add or delete addresses with the `createAddress` and `deleteAddress` operations.
type: array
items:
$ref: '#/components/schemas/userAddress'
readOnly: true
preferredMailingAddressId:
description: >-
The preferred mailing address. This string is the `_id` of an address in the `addresses` array. This value is set with the
`setPreferredMailingAddress` operation.
type: string
minLength: 1
maxLength: 4
readOnly: true
emailAddresses:
description: An array of email addresses. Add or delete email addresses with the `createEmailAddress` and `deleteEmailAddress` operations.
type: array
items:
$ref: '#/components/schemas/userEmailAddress'
readOnly: true
preferredEmailAddressId:
description: |-
The preferred email address. This string is the `_id` of an email address in the `emailAddresses` array.
This value is set with the `setPreferredEmailAddress` operation.
type: string
minLength: 1
maxLength: 4
readOnly: true
phones:
description: An array of phone numbers.
type: array
items:
$ref: '#/components/schemas/phoneNumber'
preferredPhoneId:
description: >-
The ID of preferred phone number. This string is the `_id` of a phone number in the `phones` array. This value is set with the
`setPreferredPhoneNumber` operation.
type: string
minLength: 1
maxLength: 4
readOnly: true
prefix:
description: A title or honorific prefix such as Dr. or Fr.
type: string
maxLength: 20
suffix:
description: A title or honorific suffix such as PhD or DDS.
type: string
maxLength: 20
preferredName:
description: >-
The contact's preferred name. This is how the contact's name is presented to the user in the interface. The default is the contact's
`firstName`.
type: string
identification:
description: A collection of official identifying information associated with the contact.
x-apiture-pii: true
type: array
items:
$ref: '#/components/schemas/identification'
preferredContactMethod:
description: The contact's preferred method of communication.
allOf:
- $ref: '#/components/schemas/preferredContactMethod'
birthdate:
description: The contact's birth date in `YYYY-MM-DD` format.
type: string
format: date
citizenship:
description: This individual's citizenship or nationality status.
allOf:
- $ref: '#/components/schemas/citizenship'
residencyStatus:
description: This individual's residency status.
allOf:
- $ref: '#/components/schemas/residencyStatus'
occupation:
description: The occupation of this individual.
allOf:
- $ref: '#/components/schemas/occupation'
otherOccupation:
description: The actual occupation of this individual if their `occupation` is `other`. This is ignored if `occupation` is not `other`.
type: string
minLength: 4
maxLength: 32
yearsAtAddress:
description: >-
The number of years the person has been at their present home address, as of the date the user registered. This value may become stale
over time.
allOf:
- $ref: '#/components/schemas/yearsAtAddress'
kycAnswers:
description: This user's answers Know Your Customer (KYC) questions.
x-apiture-pii: true
readOnly: true
allOf:
- $ref: '#/components/schemas/kycAnswers'
identityVerificationStatus:
description: >-
The identity verification status for this person. This field is read-only and is derived from the results of any Identity API verification
applied to this user's personally identifiable information (PII).
readOnly: true
allOf:
- $ref: '#/components/schemas/userIdentityVerificationState'
identityVerification:
description: >-
The identity verification data for this person. These fields are derived from the results from the results of any Identity API
verification applied to this user's personally identifiable information (PII).
**Warning**: The property `identityVerification` was
deprecated on version `v1.1.0` of the schema. Use identity information in Identity service instead. `identityVerification` will be removed
on version `v2.0.0` of the schema.
type: object
readOnly: true
allOf:
- $ref: '#/components/schemas/identityVerification'
x-apiture-deprecated:
since: 1.1.0
removeOn: 2.0.0
replacement: identity information in Identity service
username:
description: The unique username for the user.
type: string
state:
description: The state of this user record. The default is `active`.
allOf:
- $ref: '#/components/schemas/userState'
phoneNumbers:
description: An array of phone numbers. Add or delete phoneNumbers with the `createPhoneNumber` and `deletePhoneNumber` operations.
type: array
items:
$ref: '#/components/schemas/userPhoneNumber'
readOnly: true
x-apiture-flattened: true
createUser:
title: Create User (v1.1.3)
description: Representation used to create a new user.
required:
- username
- firstName
- lastName
- birthdate
- identification
x-apiture-version: 1.1.3
example:
_profile: 'https://api.apiture.com/schemas/users/createUser/v1.1.3/profile.json'
username: Johnny1733
firstName: John
middleName: Daniel
lastName: Smith
preferredName: John
identification:
- value: 111-11-1111
type: taxId
emailAddresses:
- _id: pe0
type: personal
value: johnny1733@example.com
- _id: we0
type: work
value: support@apiture.com
residencyStatus: resident
customerId: 00047294723672
phones:
- _id: hp0
type: home
number: '+19105550155'
- _id: mp0
type: mobile
number: '+19105550159'
preferredPhoneId: hp0
emailAddresses:
- _id: pe0
type: personal
value: johnny1733@example.com
- _id: we0
type: work
value: support@apiture.com
preferredEmailAddressId: pe0
birthdate: '1974-10-27'
citizenship:
- countryCode: US
state: citizen
occupation: officeAndAdministrativeSupport
addresses:
- _id: ha0
type: home
addressLine1: 555 N Front Street
addressLine2: Suite 5555
city: Wilmington
regionCode: NC
postalCode: 28401-5405
countryCode: US
- _id: ha1
type: home
addressLine1: 123 S 3rd Street
addressLine2: Apt 42
city: Wilmington
regionCode: NC
postalCode: 28411-5405
countryCode: Use
yearsAtAddress: fourOrMore
preferredAddressId: ha0
preferredContactMethod: email
preferences:
smsNotifications: true
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- $ref: '#/components/schemas/userFields'
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'
firstName:
description: The person's first name (or given name).
type: string
middleName:
description: The person's middle name.
type: string
lastName:
description: The person's last name (or surname).
type: string
addresses:
description: An array of postal/mailing addresses. Add or delete addresses with the `createAddress` and `deleteAddress` operations.
type: array
items:
$ref: '#/components/schemas/userAddress'
readOnly: true
preferredMailingAddressId:
description: >-
The preferred mailing address. This string is the `_id` of an address in the `addresses` array. This value is set with the
`setPreferredMailingAddress` operation.
type: string
minLength: 1
maxLength: 4
readOnly: true
emailAddresses:
description: An array of email addresses. Add or delete email addresses with the `createEmailAddress` and `deleteEmailAddress` operations.
type: array
items:
$ref: '#/components/schemas/userEmailAddress'
readOnly: true
preferredEmailAddressId:
description: |-
The preferred email address. This string is the `_id` of an email address in the `emailAddresses` array.
This value is set with the `setPreferredEmailAddress` operation.
type: string
minLength: 1
maxLength: 4
readOnly: true
phones:
description: An array of phone numbers.
type: array
items:
$ref: '#/components/schemas/phoneNumber'
preferredPhoneId:
description: >-
The ID of preferred phone number. This string is the `_id` of a phone number in the `phones` array. This value is set with the
`setPreferredPhoneNumber` operation.
type: string
minLength: 1
maxLength: 4
readOnly: true
prefix:
description: A title or honorific prefix such as Dr. or Fr.
type: string
maxLength: 20
suffix:
description: A title or honorific suffix such as PhD or DDS.
type: string
maxLength: 20
preferredName:
description: >-
The contact's preferred name. This is how the contact's name is presented to the user in the interface. The default is the contact's
`firstName`.
type: string
identification:
description: A collection of official identifying information associated with the contact.
x-apiture-pii: true
type: array
items:
$ref: '#/components/schemas/identification'
preferredContactMethod:
description: The contact's preferred method of communication.
allOf:
- $ref: '#/components/schemas/preferredContactMethod'
birthdate:
description: The contact's birth date in `YYYY-MM-DD` format.
type: string
format: date
citizenship:
description: This individual's citizenship or nationality status.
allOf:
- $ref: '#/components/schemas/citizenship'
residencyStatus:
description: This individual's residency status.
allOf:
- $ref: '#/components/schemas/residencyStatus'
occupation:
description: The occupation of this individual.
allOf:
- $ref: '#/components/schemas/occupation'
otherOccupation:
description: The actual occupation of this individual if their `occupation` is `other`. This is ignored if `occupation` is not `other`.
type: string
minLength: 4
maxLength: 32
yearsAtAddress:
description: >-
The number of years the person has been at their present home address, as of the date the user registered. This value may become stale
over time.
allOf:
- $ref: '#/components/schemas/yearsAtAddress'
kycAnswers:
description: This user's answers Know Your Customer (KYC) questions.
x-apiture-pii: true
readOnly: true
allOf:
- $ref: '#/components/schemas/kycAnswers'
identityVerificationStatus:
description: >-
The identity verification status for this person. This field is read-only and is derived from the results of any Identity API verification
applied to this user's personally identifiable information (PII).
readOnly: true
allOf:
- $ref: '#/components/schemas/userIdentityVerificationState'
identityVerification:
description: >-
The identity verification data for this person. These fields are derived from the results from the results of any Identity API
verification applied to this user's personally identifiable information (PII).
**Warning**: The property `identityVerification` was
deprecated on version `v1.1.0` of the schema. Use identity information in Identity service instead. `identityVerification` will be removed
on version `v2.0.0` of the schema.
type: object
readOnly: true
allOf:
- $ref: '#/components/schemas/identityVerification'
x-apiture-deprecated:
since: 1.1.0
removeOn: 2.0.0
replacement: identity information in Identity service
username:
description: The unique username for the user.
type: string
state:
description: The state of this user record. The default is `active`.
allOf:
- $ref: '#/components/schemas/userState'
phoneNumbers:
description: An array of phone numbers. Add or delete phoneNumbers with the `createPhoneNumber` and `deletePhoneNumber` operations.
type: array
items:
$ref: '#/components/schemas/userPhoneNumber'
readOnly: true
type: object
x-apiture-flattened: true
summaryUser:
title: Summary User (v1.1.5)
description: >-
Summary representation of a user resource in user 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.5
example:
_id: 9604e5f8-da29-4197-b6fb-60a1cfecfba8
_profile: 'https://api.apiture.com/schemas/users/summaryUser/v1.1.5/profile.json'
username: Johnny1733
firstName: John
middleName: Daniel
lastName: Smith
preferredName: John
identification:
- value: 111-11-1111
type: taxId
emailAddresses:
- _id: pe0
type: personal
value: johnny1733@example.com
- _id: we0
type: work
value: support@apiture.com
residencyStatus: resident
customerId: 00047294723672
phones:
- _id: hp0
type: home
number: '+19105550155'
- _id: mp0
type: mobile
number: '+19105550159'
preferredPhoneId: hp0
emailAddresses:
- _id: pe0
type: personal
value: johnny1733@example.com
- _id: we0
type: work
value: support@apiture.com
preferredEmailAddressId: pe0
birthdate: '1974-10-27'
citizenship:
- countryCode: US
state: citizen
occupation: officeAndAdministrativeSupport
addresses:
- _id: ha0
type: home
addressLine1: 555 N Front Street
addressLine2: Suite 5555
city: Wilmington
regionCode: NC
postalCode: 28401-5405
countryCode: US
- _id: ha1
type: home
addressLine1: 123 S 3rd Street
addressLine2: Apt 42
city: Wilmington
regionCode: NC
postalCode: 28411-5405
countryCode: Use
preferredAddressId: ha0
yearsAtAddress: fourOrMore
preferredContactMethod: email
state: active
attributes: {}
_links:
self:
href: /users/users/9604e5f8-da29-4197-b6fb-60a1cfecfba8
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- $ref: '#/components/schemas/userFields'
- properties:
- _id
- customerId
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'
firstName:
description: The person's first name (or given name).
type: string
middleName:
description: The person's middle name.
type: string
lastName:
description: The person's last name (or surname).
type: string
addresses:
description: An array of postal/mailing addresses. Add or delete addresses with the `createAddress` and `deleteAddress` operations.
type: array
items:
$ref: '#/components/schemas/userAddress'
readOnly: true
preferredMailingAddressId:
description: >-
The preferred mailing address. This string is the `_id` of an address in the `addresses` array. This value is set with the
`setPreferredMailingAddress` operation.
type: string
minLength: 1
maxLength: 4
readOnly: true
emailAddresses:
description: An array of email addresses. Add or delete email addresses with the `createEmailAddress` and `deleteEmailAddress` operations.
type: array
items:
$ref: '#/components/schemas/userEmailAddress'
readOnly: true
preferredEmailAddressId:
description: |-
The preferred email address. This string is the `_id` of an email address in the `emailAddresses` array.
This value is set with the `setPreferredEmailAddress` operation.
type: string
minLength: 1
maxLength: 4
readOnly: true
phones:
description: An array of phone numbers.
type: array
items:
$ref: '#/components/schemas/phoneNumber'
preferredPhoneId:
description: >-
The ID of preferred phone number. This string is the `_id` of a phone number in the `phones` array. This value is set with the
`setPreferredPhoneNumber` operation.
type: string
minLength: 1
maxLength: 4
readOnly: true
prefix:
description: A title or honorific prefix such as Dr. or Fr.
type: string
maxLength: 20
suffix:
description: A title or honorific suffix such as PhD or DDS.
type: string
maxLength: 20
preferredName:
description: >-
The contact's preferred name. This is how the contact's name is presented to the user in the interface. The default is the contact's
`firstName`.
type: string
identification:
description: A collection of official identifying information associated with the contact.
x-apiture-pii: true
type: array
items:
$ref: '#/components/schemas/identification'
preferredContactMethod:
description: The contact's preferred method of communication.
allOf:
- $ref: '#/components/schemas/preferredContactMethod'
birthdate:
description: The contact's birth date in `YYYY-MM-DD` format.
type: string
format: date
citizenship:
description: This individual's citizenship or nationality status.
allOf:
- $ref: '#/components/schemas/citizenship'
residencyStatus:
description: This individual's residency status.
allOf:
- $ref: '#/components/schemas/residencyStatus'
occupation:
description: The occupation of this individual.
allOf:
- $ref: '#/components/schemas/occupation'
otherOccupation:
description: The actual occupation of this individual if their `occupation` is `other`. This is ignored if `occupation` is not `other`.
type: string
minLength: 4
maxLength: 32
yearsAtAddress:
description: >-
The number of years the person has been at their present home address, as of the date the user registered. This value may become stale
over time.
allOf:
- $ref: '#/components/schemas/yearsAtAddress'
kycAnswers:
description: This user's answers Know Your Customer (KYC) questions.
x-apiture-pii: true
readOnly: true
allOf:
- $ref: '#/components/schemas/kycAnswers'
identityVerificationStatus:
description: >-
The identity verification status for this person. This field is read-only and is derived from the results of any Identity API verification
applied to this user's personally identifiable information (PII).
readOnly: true
allOf:
- $ref: '#/components/schemas/userIdentityVerificationState'
identityVerification:
description: >-
The identity verification data for this person. These fields are derived from the results from the results of any Identity API
verification applied to this user's personally identifiable information (PII).
**Warning**: The property `identityVerification` was
deprecated on version `v1.1.0` of the schema. Use identity information in Identity service instead. `identityVerification` will be removed
on version `v2.0.0` of the schema.
type: object
readOnly: true
allOf:
- $ref: '#/components/schemas/identityVerification'
x-apiture-deprecated:
since: 1.1.0
removeOn: 2.0.0
replacement: identity information in Identity service
username:
description: The unique username for the user.
type: string
state:
description: The state of this user record. The default is `active`.
allOf:
- $ref: '#/components/schemas/userState'
phoneNumbers:
description: An array of phone numbers. Add or delete phoneNumbers with the `createPhoneNumber` and `deletePhoneNumber` operations.
type: array
items:
$ref: '#/components/schemas/userPhoneNumber'
readOnly: true
_id:
description: The unique identifier for this user resource. This is an opaque string.
readOnly: true
type: string
customerId:
description: >-
The unique customer number, also known as the Customer Identification File number or CIF number. This derived value is assigned to the
user in the banking core. The `customerId` differs from the `_id` (which is the ID of the resource in the Users API).
type: string
minLength: 1
maxLength: 100
readOnly: true
example: 00047294723672
type: object
x-apiture-flattened: true
user:
title: User (v1.2.2)
description: |
Representation of a user. A user is a financial institution customer who is enrolled in on-line banking.
Links
Response and request bodies using this user
schema may contain
the following links:
x-apiture-version: 1.2.2
x-apiture-links:
- rel: self
operationId: getUser
- rel: 'apiture:remove'
operationId: removeUser
- rel: 'apiture:activate'
operationId: activateUser
- rel: 'apiture:deactivate'
operationId: deactivateUser
- rel: 'apiture:lock'
operationId: lockUser
- rel: 'apiture:freeze'
operationId: freezeUser
example:
_id: 9604e5f8-da29-4197-b6fb-60a1cfecfba8
_profile: 'https://api.apiture.com/schemas/users/user/v1.2.2/profile.json'
username: Johnny1733
firstName: John
middleName: Daniel
lastName: Smith
preferredName: John
identification:
- value: 111-11-1111
type: taxId
emailAddresses:
- _id: pe0
type: personal
value: johnny1733@example.com
- _id: we0
type: work
value: support@apiture.com
residencyStatus: resident
customerId: 00047294723672
phones:
- _id: hp0
type: home
number: '+19105550155'
- _id: mp0
type: mobile
number: '+19105550159'
preferredPhoneId: hp0
emailAddresses:
- _id: pe0
type: personal
value: johnny1733@example.com
- _id: we0
type: work
value: support@apiture.com
preferredEmailAddressId: pe0
birthdate: '1974-10-27'
citizenship:
- countryCode: US
state: citizen
occupation: officeAndAdministrativeSupport
addresses:
- _id: ha0
type: home
addressLine1: 555 N Front Street
addressLine2: Suite 5555
city: Wilmington
regionCode: NC
postalCode: 28401-5405
countryCode: US
- _id: ha1
type: home
addressLine1: 123 S 3rd Street
addressLine2: Apt 42
city: Wilmington
regionCode: NC
postalCode: 28411-5405
countryCode: Use
preferredAddressId: ha0
yearsAtAddress: fourOrMore
preferredContactMethod: email
state: active
preferences:
smsNotifications: true
coreBanking:
finxact:
customerGroup: '--64964c9c8e8f----2d-5e-'
partyPersonId: '--4WS6l0g7D4u-----5F-Bg-'
attributes: {}
_links:
self:
href: /users/users/9604e5f8-da29-4197-b6fb-60a1cfecfba8
'apiture:deactivate':
href: /users/inactiveUsers?user=9604e5f8-da29-4197-b6fb-60a1cfecfba8
'apiture:lock':
href: /users/lockedUsers?user=9604e5f8-da29-4197-b6fb-60a1cfecfba8
'apiture:freeze':
href: /users/frozenUsers?user=9604e5f8-da29-4197-b6fb-60a1cfecfba8
'apiture:remove':
href: /users/removedUsers?user=9604e5f8-da29-4197-b6fb-60a1cfecfba8
createdAt: '2018-03-09T20:14:32Z'
lastLoggedInAt: '2019-07-09T10:24:00Z'
lastContactedAt: '2019-07-16T06:00:00Z'
x-apiture-composition:
- $ref: '#/components/schemas/summaryUser'
- properties:
- createdAt
- lastContactedAt
- lastLoggedInAt
- preferences
- coreBanking
- attributes
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'
firstName:
description: The person's first name (or given name).
type: string
middleName:
description: The person's middle name.
type: string
lastName:
description: The person's last name (or surname).
type: string
addresses:
description: An array of postal/mailing addresses. Add or delete addresses with the `createAddress` and `deleteAddress` operations.
type: array
items:
$ref: '#/components/schemas/userAddress'
readOnly: true
preferredMailingAddressId:
description: >-
The preferred mailing address. This string is the `_id` of an address in the `addresses` array. This value is set with the
`setPreferredMailingAddress` operation.
type: string
minLength: 1
maxLength: 4
readOnly: true
emailAddresses:
description: An array of email addresses. Add or delete email addresses with the `createEmailAddress` and `deleteEmailAddress` operations.
type: array
items:
$ref: '#/components/schemas/userEmailAddress'
readOnly: true
preferredEmailAddressId:
description: |-
The preferred email address. This string is the `_id` of an email address in the `emailAddresses` array.
This value is set with the `setPreferredEmailAddress` operation.
type: string
minLength: 1
maxLength: 4
readOnly: true
phones:
description: An array of phone numbers.
type: array
items:
$ref: '#/components/schemas/phoneNumber'
preferredPhoneId:
description: >-
The ID of preferred phone number. This string is the `_id` of a phone number in the `phones` array. This value is set with the
`setPreferredPhoneNumber` operation.
type: string
minLength: 1
maxLength: 4
readOnly: true
prefix:
description: A title or honorific prefix such as Dr. or Fr.
type: string
maxLength: 20
suffix:
description: A title or honorific suffix such as PhD or DDS.
type: string
maxLength: 20
preferredName:
description: >-
The contact's preferred name. This is how the contact's name is presented to the user in the interface. The default is the contact's
`firstName`.
type: string
identification:
description: A collection of official identifying information associated with the contact.
x-apiture-pii: true
type: array
items:
$ref: '#/components/schemas/identification'
preferredContactMethod:
description: The contact's preferred method of communication.
allOf:
- $ref: '#/components/schemas/preferredContactMethod'
birthdate:
description: The contact's birth date in `YYYY-MM-DD` format.
type: string
format: date
citizenship:
description: This individual's citizenship or nationality status.
allOf:
- $ref: '#/components/schemas/citizenship'
residencyStatus:
description: This individual's residency status.
allOf:
- $ref: '#/components/schemas/residencyStatus'
occupation:
description: The occupation of this individual.
allOf:
- $ref: '#/components/schemas/occupation'
otherOccupation:
description: The actual occupation of this individual if their `occupation` is `other`. This is ignored if `occupation` is not `other`.
type: string
minLength: 4
maxLength: 32
yearsAtAddress:
description: >-
The number of years the person has been at their present home address, as of the date the user registered. This value may become stale
over time.
allOf:
- $ref: '#/components/schemas/yearsAtAddress'
kycAnswers:
description: This user's answers Know Your Customer (KYC) questions.
x-apiture-pii: true
readOnly: true
allOf:
- $ref: '#/components/schemas/kycAnswers'
identityVerificationStatus:
description: >-
The identity verification status for this person. This field is read-only and is derived from the results of any Identity API verification
applied to this user's personally identifiable information (PII).
readOnly: true
allOf:
- $ref: '#/components/schemas/userIdentityVerificationState'
identityVerification:
description: >-
The identity verification data for this person. These fields are derived from the results from the results of any Identity API
verification applied to this user's personally identifiable information (PII).
**Warning**: The property `identityVerification` was
deprecated on version `v1.1.0` of the schema. Use identity information in Identity service instead. `identityVerification` will be removed
on version `v2.0.0` of the schema.
type: object
readOnly: true
allOf:
- $ref: '#/components/schemas/identityVerification'
x-apiture-deprecated:
since: 1.1.0
removeOn: 2.0.0
replacement: identity information in Identity service
username:
description: The unique username for the user.
type: string
state:
description: The state of this user record. The default is `active`.
allOf:
- $ref: '#/components/schemas/userState'
phoneNumbers:
description: An array of phone numbers. Add or delete phoneNumbers with the `createPhoneNumber` and `deletePhoneNumber` operations.
type: array
items:
$ref: '#/components/schemas/userPhoneNumber'
readOnly: true
_id:
description: The unique identifier for this user resource. This is an opaque string.
readOnly: true
type: string
customerId:
description: >-
The unique customer number, also known as the Customer Identification File number or CIF number. This derived value is assigned to the
user in the banking core. The `customerId` differs from the `_id` (which is the ID of the resource in the Users API).
type: string
minLength: 1
maxLength: 100
readOnly: true
example: 00047294723672
createdAt:
description: The date-time when the user was created.
type: string
readOnly: true
format: date-time
lastContactedAt:
description: >-
The date-time when the user was last contacted. This is a computed, read-only field and will be ignored if specified as part of the
request body. This is in [RFC 3396](https://tools.ietf.org/html/rfc3339) format: `YYYY-MM-DDThh:mm:ss.sssZ`
type: string
format: date-time
lastLoggedInAt:
description: >-
The date-time when the user last logged in. This is a computed, read-only field and will be ignored if specified as part of the request
body. This is in [RFC 3396](https://tools.ietf.org/html/rfc3339) format: `YYYY-MM-DDThh:mm:ss.sssZ`
type: string
format: date-time
preferences:
description: User preferences.
allOf:
- $ref: '#/components/schemas/userPreferences'
coreBanking:
description: User properties that are specific to the banking core provider.
allOf:
- $ref: '#/components/schemas/userCoreBanking'
readOnly: true
attributes:
description: Additional unstructured application metadata about the user.
allOf:
- $ref: '#/components/schemas/attributes'
type: object
x-apiture-flattened: true
userCoreBanking:
title: User Core Banking Properties (v1.0.0)
description: >-
User properties that are specific to the banking core provider. The actual banking core in which the Apiture platform is executing determines
what data appears. The sub-object for each banking core is present on a user only if the Apiture system is connected to the corresponding core
banking provider. The name of each sub-object is the name of that provider.
type: object
properties:
finxact:
description: >-
User properties that are specific to the Finxact banking core system. This object is present only if the Apiture platform is connected to
a Finxact system.
allOf:
- $ref: '#/components/schemas/userFinxactCoreBanking'
readOnly: true
example:
finxact:
customerGroup: '--64964c9c8e8f----2d-5e-'
partyPersonId: '--4WS6l0g7D4u-----5F-Bg-'
x-apiture-version: 1.0.0
x-apiture-flattened: true
userFinxactCoreBanking:
title: User Core Banking Properties (v1.0.0)
description: >-
User properties that are specific to the Finxact banking core system. (Note that the Finxact `customerId` property is the Apiture
`user.customerId`.)
type: object
properties:
customerGroup:
description: |
Each user in Finxact belongs to a user group. This property is Finxact identifier of the customer group that this user belongs to.
type: string
readOnly: true
partyPersonId:
description: The unique identifier for the user in the Finxact system. (This is analogous to the user's `_id` in Apiture.)
type: string
readOnly: true
example:
customerGroup: '--64964c9c8e8f----2d-5e-'
partyPersonId: '--4WS6l0g7D4u-----5F-Bg-'
x-apiture-version: 1.0.0
x-apiture-flattened: true
userSearch:
title: User Search (v2.0.0)
description: Search parameters for finding a registered user.
x-apiture-version: 2.0.0
example:
_profile: 'https://api.apiture.com/schemas/users/userSearch/v2.0.0/profile.json'
taxId: 112-22-3333
_encryption:
taxId: secret-48729783
x-apiture-composition:
- $ref: '#/components/schemas/abstractRequest'
- properties:
- taxId
- _encryption
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
taxId:
description: >-
The tax identification number. In the U.S., this is the Social Security Number, in `nnn-nn-nnnn` format. This field must be encrypted
using client-side encryption keys obtained from the [`GET /encryptionKeys`](#op-getEncryptionKeys).
The value of `taxId` in requests _must_ be encrypted with the [`secret` encryption key](#op-getEncryptionKeys).
type: string
example: 112-22-3333
x-apiture-encrypt: secret
_encryption:
description: Metadata about the encrypted `currentPassword` and `newPassword` properties.
allOf:
- $ref: '#/components/schemas/encryptionMetadata'
example:
taxId: secret-48729783
type: object
x-apiture-flattened: true
userPreferences:
title: User preferences (v1.0.0)
description: User preferences for digital banking and applications.
type: object
properties:
smsNotifications:
description: >-
`true` if the user has not opted out of receiving SMS text messages from the financial institution for notification of banking or related
activity. This value reflects the user's most recent opt in/opt out selection. Note: SMS may still be used for multi-factor authentication
if `smsNotifications` is `false`.
type: boolean
default: true
additionalProperties:
$ref: '#/components/schemas/attributeValue'
x-apiture-version: 1.0.0
x-apiture-flattened: true
usersEmbedded:
title: Users Embedded Objects (v1.0.0)
description: 'Objects embedded in the [`users`](#schema-users) collection.'
type: object
properties:
items:
description: An array of users in this page of the `users` collection response.
type: array
items:
$ref: '#/components/schemas/summaryUser'
x-apiture-version: 1.0.0
x-apiture-flattened: true
users:
title: Users collection (v1.1.5)
description: >-
Collection of users. The items in the collection are ordered in the `_embedded` object with name `items`. The top-level `_links` object may
contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`).
x-apiture-version: 1.1.5
example:
_profile: 'https://api.apiture.com/schemas/users/users/v1.1.5/profile.json'
start: 0
limit: 10
count: 2
name: users
_links:
self:
href: /users?start=0&limit=10
first:
href: /users?start=10&limit=10
next:
href: /users?start=10&limit=10
collection:
href: /users
_embedded:
items:
anyOf:
- _id: 9604e5f8-da29-4197-b6fb-60a1cfecfba8
_profile: 'https://api.apiture.com/schemas/users/summaryUser/v1.1.5/profile.json'
_links:
self:
href: /users/users/9604e5f8-da29-4197-b6fb-60a1cfecfba8
'apiture:deactivate':
href: /users/inactiveUsers?user=9604e5f8-da29-4197-b6fb-60a1cfecfba8
'apiture:lock':
href: /users/lockedUsers?user=9604e5f8-da29-4197-b6fb-60a1cfecfba8
'apiture:freeze':
href: /users/frozenUsers?user=9604e5f8-da29-4197-b6fb-60a1cfecfba8
'apiture:remove':
href: /users/removedUsers?user=9604e5f8-da29-4197-b6fb-60a1cfecfba8
username: Johnny1733
firstName: John
middleName: Daniel
lastName: Smith
preferredName: John
identification:
- value: 111-11-1111
type: taxId
customerId: 00047294723672
emailAddresses:
- _id: pe0
type: personal
value: johnny1733@example.com
- _id: we0
type: work
value: support@apiture.com
phones:
- _id: hp0
type: home
number: '+19105550155'
- _id: mp0
type: mobile
number: '+19105550159'
birthdate: '1974-10-27'
citizenship:
- countryCode: US
state: citizen
occupation: officeAndAdministrativeSupport
addresses:
- type: home
addressLine1: 555 N Front Street
addressLine2: Suite 5555
city: Wilmington
regionCode: NC
postalCode: 28401-5405
countryCode: US
- type: home
addressLine1: 123 S 3rd Street
addressLine2: Apt 42
city: Wilmington
regionCode: NC
postalCode: 28411-5405
countryCode: US
yearsAtAddress: fourOrMore
lastContactedAt: '2018-07-29T11:13:54Z'
lastLoggedInAt: '2017-12-29T15:19:41Z'
state: active
createdAt: '2018-03-09T20:14:32Z'
- _id: d1fabf13-31d1-4351-89ad-877ac4d1220a
_profile: 'https://api.apiture.com/schemas/users/summaryUser/v1.1.5/profile.json'
_links:
self:
href: /users/users/d1fabf13-31d1-4351-89ad-877ac4d1220a
'apiture:deactivate':
href: /users/inactiveUsers?user=d1fabf13-31d1-4351-89ad-877ac4d1220a
'apiture:lock':
href: /users/lockedUsers?user=d1fabf13-31d1-4351-89ad-877ac4d1220a
'apiture:freeze':
href: /users/frozenUsers?user=d1fabf13-31d1-4351-89ad-877ac4d1220a
'apiture:remove':
href: /users/removedUsers?user=d1fabf13-31d1-4351-89ad-877ac4d1220a
username: LAS15
firstName: Laura
middleName: Eileen
lastName: Smith
preferredName: Laura
identification:
- value: 111-11-1111
type: taxId
emailAddresses:
- _id: pe0
type: personal
value: johnny1733@example.com
- _id: we0
type: work
value: support@apiture.com
phones:
- _id: hp0
type: home
number: '+19105550155'
- _id: mp0
type: mobile
number: '+19105550159'
birthdate: '1974-10-27'
citizenship:
- countryCode: US
state: citizen
occupation: officeAndAdministrativeSupport
addresses:
- type: home
addressLine1: 555 N Front Street
addressLine2: Suite 5555
city: Wilmington
regionCode: NC
postalCode: 28401-5405
countryCode: US
- type: home
addressLine1: 123 S 3rd Street
addressLine2: Apt 42
city: Wilmington
regionCode: NC
postalCode: 28411-5405
countryCode: US
yearsAtAddress: fourOrMore
lastContactedAt: '2018-07-29T11:13:54Z'
lastLoggedInAt: '2017-12-29T15:19:41Z'
state: active
createdAt: '2018-07-29T11:13:54Z'
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:
description: Embedded objects.
allOf:
- $ref: '#/components/schemas/usersEmbedded'
_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
constraints:
title: Constraints (v1.0.0)
description: An Constraints description. The `attributes` field a required map of name/value pairs which provide structured data about the constraint.
x-apiture-version: 1.0.0
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- $ref: '#/components/schemas/updateConstraints'
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'
transfers:
description: Constraints on the user's money transfers.
allOf:
- $ref: '#/components/schemas/transferConstraints'
checkDeposits:
description: Constraints on the user's remote check deposits.
allOf:
- $ref: '#/components/schemas/checkDepositConstraints'
type: object
x-apiture-flattened: true
updateConstraints:
title: Update user's constraints (v1.0.0)
description: Representation used to update or patch a user's constraints.
type: object
properties:
transfers:
description: Constraints on the user's money transfers.
allOf:
- $ref: '#/components/schemas/transferConstraints'
checkDeposits:
description: Constraints on the user's remote check deposits.
allOf:
- $ref: '#/components/schemas/checkDepositConstraints'
x-apiture-version: 1.0.0
x-apiture-flattened: true
transferConstraints:
title: User's constraints for transfers (v1.0.0)
description: Representation used to describe the limits for transfers.
properties:
singleCreditLimit:
description: The string representation of the limit on the amount of an individual credit transfer for a related user.
type: string
singleDebitLimit:
description: The string representation of the limit on the amount of an individual debit transfer for a related user.
type: string
dailyCreditLimit:
description: The string representation of the limit on the total amount of credit transfers per calendar day for a related user.
type: string
dailyDebitLimit:
description: The string representation of the limit on the total amount of debit transfers per calendar day for a related user.
type: string
example:
singleCreditLimit: '20000.00'
singleDebitLimit: '20000.00'
dailyCreditLimit: '500000.00'
dailyDebitLimit: '500000.00'
x-apiture-version: 1.0.0
type: object
x-apiture-flattened: true
checkDepositConstraints:
title: User's constraints for check deposits (v1.0.0)
description: Representation used to describe the limits for check deposits.
properties:
enabled:
description: Indicates that the check deposit feature is enabled for the user.
type: boolean
monthlyTotalAmountLimit:
description: >-
The string representation of the limit on the total amount of a check deposit per calendar month for a related user. The default is
“50000.00”, although the default may be configurable by the financial institution.
type: string
monthlyTotalChecksLimit:
description: >-
The string representation of the limit on the total number of a check per calendar month for a related user. The default is 1000, although
the default may be configurable by the financial institution.
type: integer
minimum: 0
example:
enabled: true
monthlyTotalAmountLimit: '30000.00'
monthlyTotalChecksLimit: 200
x-apiture-version: 1.0.0
type: object
x-apiture-flattened: true
root:
x-apiture-version: 2.0.0
title: API Root (v2.0.0)
description: |-
A HAL response, with hypermedia `_links` for the top-level resources and operations in API.
This schema was resolved from [`common/root`](https://production.api.apiture.com/schemas/common/root/v2.0.0/model.json).
example:
id: apiName
name: API name
apiVersion: 1.0.0
_profile: 'https://production.api.apiture.com/schemas/common/root/v2.0.0/profile.json'
_links: {}
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/root/v2.0.0/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- properties:
- _id
- name
- apiVersion
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
_id:
description: This API's unique ID.
readOnly: true
type: string
name:
type: string
description: This API's name.
apiVersion:
type: string
description: This API's version.
type: object
x-apiture-flattened: true
labelGroups:
title: Label Groups (v1.0.1)
description: |-
A set of named groups of labels, each of which contains multiple item labels.
The abbreviated example shows two groups, one named `structure` and one named `estimatedAnnualRevenue`.
The first has items with names such as `corporation`, `llc` and `soleProprietorship`,
with text labels for each in the default and in French. The second has
items for estimated revenue *ranges* but no localized labels. For example, the item named `from1to10Million`
has the `label` "$1M to $10M" and the range `[1000000.00,10000000.00)`.
This schema was resolved from [`common/labelGroups`](https://production.api.apiture.com/schemas/common/labelGroups/v1.0.1/model.json).
x-apiture-version: 1.0.1
example:
_profile: 'https://api.apiture.com/schemas/common/labelGroups/v1.0.1/profile.json'
groups:
structure:
unknown:
label: Unknown
code: '0'
hidden: true
corporation:
label: Corporation
code: '1'
variants:
fr:
label: Soci\u00e9t\u00e9
partnership:
label: Partnership
code: '2'
variants:
fr:
label: Partenariat
llc:
label: Limited Liability Company
code: '2'
variants:
fr:
label: Soci\u00e9t\u00e9 \u00e9 Responsabilit\u00e9 Limit\u00e9e
nonProfit:
label: Non Profit
code: '4'
variants:
fr:
label: Non Lucratif
financialInstitution:
label: Financial Institution
code: '8'
variants:
fr:
label: Institution financi\u00e8re
soleProprietorship:
label: Sole Proprietorship
code: '11'
variants:
fr:
label: Entreprise individuelle
other:
label: Other
code: '254'
variants:
fr:
label: Autre
estimatedAnnualRevenue:
unknown:
label: Unknown
code: '0'
under1Million:
label: Under $1M
code: '1'
range: '[0,1000000.00)'
from1to10Million:
label: $1M to $10M
code: '2'
range: '[1000000.00,10000000.00)'
from10to100Million:
label: $10M to $100M
code: '3'
range: '[10000000.00,100000000.00)'
over100Million:
label: 'Over $100,000,000.00'
code: '4'
range: '[100000000.00,]'
other:
label: Other
code: '254'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/labelGroups/v1.0.1/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- properties:
- groups
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
groups:
description: 'Groups of localized labels. This maps *group names* → [*a group of labels*](#schema-labelgroup) within that group.'
x-apiture-key: groupName
additionalProperties:
$ref: '#/components/schemas/labelGroup'
type: object
x-apiture-flattened: true
encryptionKeys:
title: Encryption Keys (v1.0.1)
description: >-
A set of rotating public encryption keys that the client may use to encrypt sensitive or secret data before sending it to the service. The
client only has access to the public key and only the service can decrypt the data. Such keys typically expire after several minutes.
This schema was resolved from [`common/encryptionKeys`](https://production.api.apiture.com/schemas/common/encryptionKeys/v1.0.1/model.json).
type: object
x-apiture-version: 1.0.1
example:
_profile: 'https://api.apiture.com/schemas/common/encryptionKeys/v1.0.1/profile.json'
keys:
pii:
name: sensitive
publicKey: '-----BEGIN RSA PUBLIC KEY-----\nMIIBCgKCAQEAwh8kIf3rM4FtehDl+WM1egDdxccXFLNPBUvgpbAISnEh373M4vdN...\n-----END RSA PUBLIC KEY-----'
alias: sensitive-47839398
createdAt: '2020-03-09T05:01:16.375Z'
expiresAt: '2020-03-09T05:01:53.375Z'
secret:
name: secret
publicKey: '-----BEGIN RSA PUBLIC KEY-----\nMIIBCgKCAQEAl2/fCtf69EnMqw6O/6Wh9wFvKW80jjNfXEWbHh0cnWKW1i0Heg0B...\n-----END RSA PUBLIC KEY-----'
alias: secret-48729783
createdAt: '2020-03-09T05:01:16.375Z'
expiresAt: '2020-03-09T05:01:53.375Z'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/encryptionKeys/v1.0.1/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- properties:
- keys
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'
keys:
description: A map of encryption keys. The map's keys are the key `name`; the values are encryption key objects.
type: object
x-apiture-key: keyName
additionalProperties:
$ref: '#/components/schemas/encryptionKey'
x-apiture-flattened: true
configurationGroups:
x-apiture-version: 2.0.1
title: Configuration Group Collection (v2.0.1)
description: >-
Collection of configuration groups. The items in the collection are ordered in the `_embedded` object with name `items`. The top-level
`_links` object may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`).
This schema was resolved from
[`configurations/configurationGroups`](https://production.api.apiture.com/schemas/configurations/configurationGroups/v2.0.1/model.json).
example:
_profile: 'https://production.api.apiture.com/schemas/configurations/configurationGroups/v2.0.1/profile.json'
start: 10
limit: 10
count: 67
name: configurationGroups
_links:
self:
href: /configurations/configurations/groups?start=10&limit=10
first:
href: /configurations/configurations/groups?start=0&limit=10
next:
href: /configurations/configurations/groups?start=20&limit=10
collection:
href: /configurations/configurations/groups
_embedded:
items:
anyOf:
- _profile: 'https://api.apiture.com/schemas/configurations/configurationGroup/v2.0.1/profile.json'
_links:
self:
href: /configurations/groups/basic
name: basic
label: Basic Settings
description: The basic settings for the Transfers API
- _profile: 'https://api.apiture.com/schemas/configurations/configurationGroup/v2.0.1/profile.json'
_links:
self:
href: /configurations/groups/calendar
name: calendar
label: Calendar
description: 'A calendar that specifies which dates are valid for performing transfers (e.g., weekdays excluding federal holidays)'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/configurations/configurationGroups/v2.0.1/model.json'
x-apiture-namespace: configurations
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:
description: Embedded objects.
allOf:
- $ref: '#/components/schemas/configurationGroupsEmbedded'
_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
configurationGroup:
x-apiture-version: 2.0.1
title: Configuration Group (v2.0.1)
description: >-
Represents a configuration group.
This schema was resolved from
[`configurations/configurationGroup`](https://production.api.apiture.com/schemas/configurations/configurationGroup/v2.0.1/model.json).
example:
_profile: 'https://api.apiture.com/schemas/configurations/configurationGroup/v2.0.1/profile.json'
_links:
self:
href: /configurations/groups/basic
name: basic
label: Basic Settings
description: The basic settings for the Transfers API
schema:
type: object
properties:
dailyLimit:
type: number
description: The daily limit for the number of transfers
cutoffTime:
type: string
format: time
description: The cutoff time for scheduling transfers for the current day
values:
dailyLimit: 5
cutoffTime: '17:30:00'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/configurations/configurationGroup/v2.0.1/model.json'
x-apiture-namespace: configurations
x-apiture-composition:
- $ref: '#/components/schemas/configurationGroupSummary'
- properties:
- schema
- values
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'
name:
description: 'The name of this configuration group, must be unique within the set of all resources of this type.'
type: string
maxLength: 48
minLength: 1
pattern: '[a-zA-Z][-\w_]*'
example: transfers
label:
description: 'The text label for this resource, suitable for presentation to the client.'
type: string
maxLength: 128
minLength: 1
example: Transfers Configuration
description:
description: 'The full description for this resource, suitable for presentation to the client.'
type: string
maxLength: 4096
minLength: 1
example: The configuration for the Transfers API.
schema:
$ref: '#/components/schemas/configurationSchema'
values:
$ref: '#/components/schemas/configurationValues'
type: object
x-apiture-flattened: true
configurationSchema:
x-apiture-version: 2.0.1
title: Configuration Schema (v2.0.1)
description: >-
The schema which defines the name and types of the
variables that are part of this configuration definition.
Property names must be simple identifiers
which follow the pattern `letter [letter | digit | - | _]*`.
This is implicitly a schema for `type: object`
and contains the properties.
The `values` in a configuration conform to the schema.
The names and types are described with a subset of
[JSON Schema Core](https://tools.ietf.org/html/draft-zyp-json-schema-04)
and [JSON Schema Validation](https://tools.ietf.org/html/draft-fge-json-schema-validation-00)
similar to that used to define schemas in
[OpenAPI Specification 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schemaObject).
This schema was resolved from
[`configurations/configurationSchema`](https://production.api.apiture.com/schemas/configurations/configurationSchema/v2.0.1/model.json).
type: object
additionalProperties:
$ref: '#/components/schemas/configurationSchemaValue'
example:
type: object
properties:
dailyLimit:
type: number
description: The daily limit for the number of transfers
cutoffTime:
type: string
format: time
description: The cutoff time for scheduling transfers for the current day
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/configurations/configurationSchema/v2.0.1/model.json'
x-apiture-namespace: configurations
properties: {}
x-apiture-flattened: true
configurationValues:
x-apiture-version: 2.0.0
title: Configuration Values (v2.0.0)
description: >-
The data values associated with this configuration group:
the group's variable names and values. These values must conform to this
item's `schema`.
*Note*: the `schema` may also contain `default` values
which, if present, are used if a value is *not* set in the
definition's `values`.
For example, multiple configurations may use the same schema
that defines values `a`, `b`, and `c`, but each configuration
may have their own unique values for `a`, `b`, and `c`
which is separate from the schema.
This schema was resolved from
[`configurations/configurationValues`](https://production.api.apiture.com/schemas/configurations/configurationValues/v2.0.0/model.json).
type: object
additionalProperties:
$ref: '#/components/schemas/configurationValue'
example:
dailyLimit: 5
cutoffTime: '17:30:00'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/configurations/configurationValues/v2.0.0/model.json'
x-apiture-namespace: configurations
properties: {}
x-apiture-flattened: true
errorResponse:
x-apiture-version: 2.0.0
title: Error Response (v2.0.0)
description: |-
Describes an error response, typically returned on 4xx or 5xx errors from API operations. The `_error` object contains the error details.
This schema was resolved from [`common/errorResponse`](https://production.api.apiture.com/schemas/common/errorResponse/v2.0.0/model.json).
example:
_profile: 'https://api.apiture.com/schemas/common/errorResponse/v2.0.0/profile.json'
_error:
_id: 2eae46e1-575c-4d69-8a8f-0a7b0115a4b3
message: The value for deposit must be greater than 0.
statusCode: 422
type: positiveNumberRequired
attributes:
value: -125.5
remediation: Provide a value which is greater than 0
occurredAt: '2018-01-25T05:50:52.375Z'
_links:
describedby:
href: 'https://api.apiture.com/errors/positiveNumberRequired'
_embedded:
errors: []
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/errorResponse/v2.0.0/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
type: object
x-apiture-flattened: true
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`.
This schema was resolved from
[`auth/challengeErrorResponse`](https://production.api.apiture.com/schemas/auth/challengeErrorResponse/v1.0.0/model.json).
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
address:
title: Address (v1.0.0)
description: |-
A postal address with the address type and an identifier.
This schema was resolved from [`contacts/address`](https://production.api.apiture.com/schemas/contacts/address/v1.0.0/model.json).
type: object
required:
- type
example:
_id: ha5
type: home
addressLine1: 555 N Front Street
addressLine2: Suite 5555
city: Wilmington
regionCode: NC
postalCode: 28401-5405
countryCode: US
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/address/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-composition:
- $ref: '#/components/schemas/simpleAddress'
- properties:
- type
- label
- otherType
- _id
properties:
addressLine1:
description: 'The first street address line of the address, normally a house number and street name.'
type: string
minLength: 4
maxLength: 128
addressLine2:
description: The optional second street address line of the address.
type: string
maxLength: 128
city:
description: The name of the city or municipality.
type: string
minLength: 2
maxLength: 128
regionCode:
description: 'The mailing address region code, such as state in the US, or a province in Canada. This is normalized to uppercase.'
type: string
example: NC
minLength: 2
maxLength: 2
pattern: '^[a-zA-Z]{2}$'
postalCode:
description: 'The mailing address postal code, such as a US Zip or Zip+4 code, or a Canadian postal code.'
type: string
example: 28401-5405
minLength: 5
maxLength: 10
pattern: '^[0-9]{5}(?:-[0-9]{4})?$'
countryCode:
description: 'The [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. This is normalized to uppercase.'
type: string
minLength: 2
maxLength: 2
pattern: '^[a-zA-Z]{2}$'
type:
description: The type of this address.
allOf:
- $ref: '#/components/schemas/addressType'
label:
description: 'A text label, suitable for presentation to the end user. This is derived from `type` or from `otherType` if `type` is `other`'
type: string
readOnly: true
minLength: 4
maxLength: 32
otherType:
description: The actual address type if `type` is `other`.
minLength: 4
maxLength: 32
type: string
_id:
description: >-
An identifier for this address, so that it can be referenced uniquely. The service will assign a unique `_id` if the client does not
provide one. The `_id` must be unique across all addresses within the `addresses` array.
type: string
minLength: 1
maxLength: 8
example: ha5
pattern: '^[-a-zA-Z0-9_]{1,8}$'
x-apiture-flattened: true
abstractResource:
x-apiture-version: 2.0.0
title: Abstract Resource (v2.0.0)
description: >-
An abstract schema used to define other schemas for request and response bodies. This is a
[HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource representation. This model contains hypermedia `_links`, and either
optional domain object data with `_profile` and optional `_embedded` objects, or an `_error` object. In responses, if the operation was
successful, this object will not include the `_error`, but if the operation was a 4xx or 5xx error, this object will not include `_embedded`
or any data fields, only `_error` and optionally `_links`.
This schema was resolved from
[`common/abstractResource`](https://production.api.apiture.com/schemas/common/abstractResource/v2.0.0/model.json).
example:
_profile: '{uri of resource profile.json}'
_links:
self:
href: '{uri of current resource}'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/abstractResource/v2.0.0/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/components/schemas/abstractRequest'
- properties:
- _error
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
type: object
x-apiture-flattened: true
typedEmailAddress:
title: Email Address (v1.0.0)
description: >-
An email address and the email address type.
This schema was resolved from
[`contacts/typedEmailAddress`](https://production.api.apiture.com/schemas/contacts/typedEmailAddress/v1.0.0/model.json).
properties:
value:
description: 'The email address, such as `JohnBankCustomer@example.com`'
type: string
format: email
minLength: 8
maxLength: 120
example: JohnBankCustomer@example.com
type:
description: The kind of email address.
allOf:
- $ref: '#/components/schemas/emailType'
_id:
description: >-
An identifier for this email address, so that it can be referenced uniquely. The service will assign a unique `_id` if the client does not
provide one. The `_id` must be unique across all email addresses within the `emailAddresses` array.
type: string
minLength: 1
maxLength: 8
example: ha3
pattern: '^[-a-zA-Z0-9_]{1,8}$'
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/typedEmailAddress/v1.0.0/model.json'
x-apiture-namespace: contacts
type: object
x-apiture-flattened: true
phoneNumber:
title: Phone Number (v1.0.1)
description: |-
A phone number and its role.
This schema was resolved from [`contacts/phoneNumber`](https://production.api.apiture.com/schemas/contacts/phoneNumber/v1.0.1/model.json).
type: object
x-apiture-version: 1.0.1
required:
- type
- number
properties:
type:
description: The type or role of this phone number.
allOf:
- $ref: '#/components/schemas/phoneNumberType'
number:
description: >-
The phone number, as a string. The service strips all spaces, hyphens, periods and parentheses from input. The default country code prefix
is `+1`. Phone numbers are returned in responses in [E.164](https://en.wikipedia.org/wiki/E.164) format with a leading `+`, country code
(up to 3 digits) and subscriber number for a total of up to 15 digits. See [Phone Number
Representations](https://developer.apiture.com/docs/concepts/phone-numbers/) for more information.
type: string
example: '+19105550155'
minLength: 8
maxLength: 20
label:
description: 'A text label, suitable for presentation to the end user. This is also used if `type` is `other`.'
type: string
example: assistant
maxLength: 32
_id:
description: >-
An identifier for this phone number, so that it can be referenced uniquely. The service will assign a unique `_id` if the client does not
provide one. The `_id` must be unique across all phone numbers within the `phones` array.
type: string
minLength: 1
maxLength: 8
example: ha5
pattern: '^[-a-zA-Z0-9_]{1,8}$'
example:
_id: hp1
type: home
number: '+19105550155'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/phoneNumber/v1.0.1/model.json'
x-apiture-namespace: contacts
x-apiture-flattened: true
identifiedContact:
title: Identified Contact (v1.0.1)
description: >-
A contact with additional personally identifiable information data.
This schema was resolved from
[`contacts/identifiedContact`](https://production.api.apiture.com/schemas/contacts/identifiedContact/v1.0.1/model.json).
x-apiture-version: 1.0.1
x-apiture-fragment: true
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/identifiedContact/v1.0.1/model.json'
x-apiture-namespace: contacts
x-apiture-composition:
- $ref: '#/components/schemas/simpleContact'
- $ref: '#/components/schemas/identifiedContactFields'
properties:
firstName:
description: The person's first name (or given name).
type: string
middleName:
description: The person's middle name.
type: string
lastName:
description: The person's last name (or surname).
type: string
addresses:
description: An array of postal/mailing addresses.
type: array
items:
$ref: '#/components/schemas/address'
preferredMailingAddressId:
description: The preferred mailing address. This string is the `_id` of an address in the `addresses` array.
type: string
minLength: 1
maxLength: 4
emailAddresses:
description: An array of email addresses.
type: array
items:
$ref: '#/components/schemas/typedEmailAddress'
preferredEmailAddressId:
description: The preferred email address. This string is the `_id` of an email address in the `emailAddresses` array.
type: string
minLength: 1
maxLength: 4
phones:
description: An array of phone numbers.
type: array
items:
$ref: '#/components/schemas/phoneNumber'
preferredPhoneId:
description: The ID of preferred phone number. This string is the `_id` of a phone number in the `phones` array.
type: string
minLength: 1
maxLength: 4
prefix:
description: A title or honorific prefix such as Dr. or Fr.
type: string
maxLength: 20
suffix:
description: A title or honorific suffix such as PhD or DDS.
type: string
maxLength: 20
preferredName:
description: >-
The contact's preferred name. This is how the contact's name is presented to the user in the interface. The default is the contact's
`firstName`.
type: string
identification:
description: A collection of official identifying information associated with the contact.
x-apiture-pii: true
type: array
items:
$ref: '#/components/schemas/identification'
preferredContactMethod:
description: The contact's preferred method of communication.
allOf:
- $ref: '#/components/schemas/preferredContactMethod'
birthdate:
description: The contact's birth date in `YYYY-MM-DD` format.
type: string
format: date
citizenship:
description: This individual's citizenship or nationality status.
allOf:
- $ref: '#/components/schemas/citizenship'
residencyStatus:
description: This individual's residency status.
allOf:
- $ref: '#/components/schemas/residencyStatus'
occupation:
description: The occupation of this individual.
allOf:
- $ref: '#/components/schemas/occupation'
otherOccupation:
description: The actual occupation of this individual if their `occupation` is `other`. This is ignored if `occupation` is not `other`.
type: string
minLength: 4
maxLength: 32
yearsAtAddress:
description: The number of years the person has been at their present home address.
allOf:
- $ref: '#/components/schemas/yearsAtAddress'
type: object
x-apiture-flattened: true
yearsAtAddress:
title: Years at Address (v1.0.0)
description: >-
Categories for how long the person has been at their present home address.
This schema was resolved from
[`contacts/yearsAtAddress`](https://production.api.apiture.com/schemas/contacts/yearsAtAddress/v1.0.0/model.json).
type: string
enum:
- unknown
- oneOrFewer
- two
- three
- fourOrMore
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/yearsAtAddress/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-flattened: true
attributes:
x-apiture-version: 2.0.0
title: Attributes (v2.0.0)
description: |-
An optional map of name/value pairs which contains additional dynamic data about the resource.
This schema was resolved from [`common/attributes`](https://production.api.apiture.com/schemas/common/attributes/v2.0.0/model.json).
type: object
x-apiture-key: attributeName
additionalProperties:
$ref: '#/components/schemas/attributeValue'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/attributes/v2.0.0/model.json'
x-apiture-namespace: common
properties: {}
x-apiture-flattened: true
abstractRequest:
x-apiture-version: 2.0.0
title: Abstract Request (v2.0.0)
description: >-
An abstract schema used to define other request-only schemas. This is a [HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource
representation, minus the `_error` defined in `abstractResource`.
This schema was resolved from [`common/abstractRequest`](https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/model.json).
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
example:
_profile: '{uri of resource profile.json}'
_links:
self:
href: '{uri of current resource}'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/model.json'
x-apiture-namespace: common
type: object
x-apiture-flattened: true
encryptionMetadata:
title: Enryption Metadata (v1.0.1)
description: >-
Metadata about encrypted data within a JSON object in a request body.
This `_encryption` object is a peer of the encrypted data.
Each nested object that contains encrypted properties
has it's own `_encryption` object.
This object is a map of `string` property names → `string` encryption key alias.
The keys are names of the encrypted and Base64 encoded property.
Each value is the `alias` of the
rotating public encryption key that the client used to encrypt the named property.
See [Encryption](https://developer.apiture.com/docs/concepts/encryption) for additional details.
This schema was resolved from
[`common/encryptionMetadata`](https://production.api.apiture.com/schemas/common/encryptionMetadata/v1.0.1/model.json).
x-apiture-version: 1.0.1
x-apiture-key: encryptedPropertyName
additionalProperties:
type: string
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/encryptionMetadata/v1.0.1/model.json'
x-apiture-namespace: common
type: object
properties: {}
x-apiture-flattened: true
attributeValue:
x-apiture-version: 2.0.0
title: Attribute Value (v2.0.0)
description: |-
The data associated with this attribute.
This schema was resolved from [`common/attributeValue`](https://production.api.apiture.com/schemas/common/attributeValue/v2.0.0/model.json).
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/attributeValue/v2.0.0/model.json'
x-apiture-namespace: common
type: object
properties: {}
x-apiture-flattened: true
collection:
x-apiture-version: 2.0.0
title: Collection (v2.0.0)
description: |-
A collection of resources. This is an abstract model schema which is extended to define specific resource collections.
This schema was resolved from [`common/collection`](https://production.api.apiture.com/schemas/common/collection/v2.0.0/model.json).
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/collection/v2.0.0/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- properties:
- count
- start
- limit
- name
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
allOf:
- $ref: '#/components/schemas/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
_error:
description: An object which describes an error. This value is omitted if the operation succeeded without error.
type: object
allOf:
- $ref: '#/components/schemas/error'
count:
description: >-
The number of items in the collection. This value is _optional_ and may be omitted if the count is not computable efficiently. If a filter
is applied to the collection (either implicitly or explicitly), the count, if present, indicates the number of items that satisfy the
filter.
type: integer
start:
description: The start index of this page of items.
type: integer
limit:
description: The maximum number of items per page.
type: integer
name:
description: The name of the collection.
type: string
type: object
x-apiture-flattened: true
labelGroup:
title: Label Group (v1.0.0)
description: >-
A map that defines labels for the items in a group. This is a map from each item *name* → *a [`labelItem`](#schema-labelitem) object*.
For example, consider a JSON response that includes a property named `revenueEstimate`; the values for `revenueEstimate` must be one of the
items in the group named `estimatedAnnualRevenue`, with options ranging `under1Million`, to `over100Million`. The item name is used as the
selected value in an Apiture representation, such as `{ ..., "revenueEstimate" : "from10to100Million" , ...}`, and the item with the name
`from10to100Million` defines the presentation labels for that item, as well as other metadata about that choice: this is the range
`[10000000.00,100000000.00)`.
This allows the client to let the user select a value from a list, such as the following derivde from the labels in the example:
* Unknown
* Under $1M
* $1M to $10M
* $10M to $100M
* $100M or more
Note that the `other` item is hidden from the selection list, as that item is marked as `hidden`. For items which define numeric ranges, a
client may instead let the customer *directly* enter their estimated annual revenue as a number, such as 4,500,000.00. The client can then
match that number to one of ranges in the items and set the `revenueEstimate` to the corresponding item's name: `{ ..., "revenueEstimate" :
"from1to10Million", ... }`.
This schema was resolved from [`common/labelGroup`](https://production.api.apiture.com/schemas/common/labelGroup/v1.0.0/model.json).
x-apiture-key: labelName
x-apiture-version: 1.0.0
additionalProperties:
$ref: '#/components/schemas/labelItem'
example:
unknown:
label: Unknown
code: '0'
hidden: true
under1Million:
label: Under $1M
code: '1'
range: '[0,1000000.00)'
variants:
fr:
label: Moins de $1M
from1to10Million:
label: $1M to $10M
code: '2'
range: '[1000000.00,10000000.00)'
variants:
fr:
label: $1M \u00e0 $10M
from10to100Million:
label: $10M to $100M
code: '3'
range: '[10000000.00,100000000.00)'
variants:
fr:
- label $10M \u00e0 $100M
over100Million:
label: 'Over $100,000,000.00'
code: '4'
range: '[100000000.00,]'
variants:
fr:
label: Plus de $10M
other:
label: Other
code: 254
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/labelGroup/v1.0.0/model.json'
x-apiture-namespace: common
type: object
properties: {}
x-apiture-flattened: true
configurationGroupsEmbedded:
title: Configuration Groups Embedded Objects (v1.0.0)
description: >-
Objects embedded in the [`configurationGroups`](#schema-configurationGroups)collection.
This schema was resolved from
[`configurations/configurationGroupsEmbedded`](https://production.api.apiture.com/schemas/configurations/configurationGroupsEmbedded/v1.0.0/model.json).
type: object
properties:
items:
description: An array containing a page of configuration group items.
type: array
items:
$ref: '#/components/schemas/configurationGroupSummary'
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/configurations/configurationGroupsEmbedded/v1.0.0/model.json'
x-apiture-namespace: configurations
x-apiture-flattened: true
encryptionKey:
title: Encryption Key (v1.0.1)
description: |-
A rotating public encryption key. See [Encryption](https://developer.apiture.com/docs/concepts/encryption) for additional details.
This schema was resolved from [`common/encryptionKey`](https://production.api.apiture.com/schemas/common/encryptionKey/v1.0.1/model.json).
x-apiture-version: 1.0.1
type: object
properties:
name:
description: >-
The name of an encryption key; this identifies the type of data the key encrypts, such as `pii` for personally identifying information,
`secret` for passwords or other secret data. The type name is taken from the `x-apiture-encrypt` annotation on the property in the JSON
schema or chosen by the client when requesting encryption keys.
allOf:
- $ref: '#/components/schemas/encryptionKeyName'
publicKey:
description: >-
The ASCII encoded public encryption key that the client uses to encrypt data. This is half of the asymmetric public/private key pair. This
is a mult-line string with key bopokends and embedded line breaks.
type: string
alias:
description: >-
An alias for the actual rotating key. Keys rotate every few minutes. The alias identifies a specific instance of an active public/private
key pair. This alias must be set in the `_encryption` metadata (see [`encryptionMetadata`](#schema-encryptionMetadata)). The value of the
alias is the concatenation of the `name`, a dash `-`, and some additional characters which identify the specific key rotation.
type: string
pattern: '^[a-z][a-zA-Z0-9]{2,11}-.{2,8}$'
minLength: 6
maxLength: 19
example: secret-48729783
createdAt:
description: 'The date-time when the encryption key was created, in [RFC 3339](https://tools.ietf.org/html/rfc3339) date-time format.'
type: string
format: date-time
example: '2020-03-09T05:01:16.375Z'
expiresAt:
description: >-
The date-time when the encryption key will expire. If this expiration time has passed or is less than 60 seconds away, the client should
fetch updated encryption keys. [RFC 3339](https://tools.ietf.org/html/rfc3339) date-time format.
type: string
format: date-time
example: '2020-03-09T05:01:16.375Z'
example:
name: secret
publicKey: '-----BEGIN RSA PUBLIC KEY-----\nMIIBCgKCAQEAl2/fCtf69EnMqw6O/6Wh9wFvKW80jjNfXEWbHh0cnWKW1i0Heg0B...\n-----END RSA PUBLIC KEY-----'
alias: secret-48729783
createdAt: '2020-03-09T05:01:16.375Z'
expiresAt: '2020-03-09T05:01:53.375Z'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/encryptionKey/v1.0.1/model.json'
x-apiture-namespace: common
x-apiture-flattened: true
configurationGroupSummary:
x-apiture-version: 2.0.0
title: Configuration Group Summary (v2.0.0)
description: >-
A summary of the data contained within a configuration group resource.
This schema was resolved from
[`configurations/configurationGroupSummary`](https://production.api.apiture.com/schemas/configurations/configurationGroupSummary/v2.0.0/model.json).
example:
_profile: 'https://api.apiture.com/schemas/configurations/configurationGroupSummary/v2.0.0/profile.json'
_links:
self:
href: /configurations/groups/basic
name: basic
label: Basic Settings
description: The basic settings for the Transfers API
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/configurations/configurationGroupSummary/v2.0.0/model.json'
x-apiture-namespace: configurations
x-apiture-composition:
- $ref: '#/components/schemas/abstractResource'
- properties:
- name
- label
- description
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'
name:
description: 'The name of this configuration group, must be unique within the set of all resources of this type.'
type: string
maxLength: 48
minLength: 1
pattern: '[a-zA-Z][-\w_]*'
example: transfers
label:
description: 'The text label for this resource, suitable for presentation to the client.'
type: string
maxLength: 128
minLength: 1
example: Transfers Configuration
description:
description: 'The full description for this resource, suitable for presentation to the client.'
type: string
maxLength: 4096
minLength: 1
example: The configuration for the Transfers API.
type: object
x-apiture-flattened: true
configurationValue:
x-apiture-version: 2.0.0
title: Configuration Value (v2.0.0)
description: >-
The data associated with this configuration.
This schema was resolved from
[`configurations/configurationValue`](https://production.api.apiture.com/schemas/configurations/configurationValue/v2.0.0/model.json).
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/configurations/configurationValue/v2.0.0/model.json'
x-apiture-namespace: configurations
type: object
properties: {}
x-apiture-flattened: true
configurationSchemaValue:
x-apiture-version: 2.0.0
title: Configuration Schema Value (v2.0.0)
description: >-
The data associated with this configuration schema.
This schema was resolved from
[`configurations/configurationSchemaValue`](https://production.api.apiture.com/schemas/configurations/configurationSchemaValue/v2.0.0/model.json).
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/configurations/configurationSchemaValue/v2.0.0/model.json'
x-apiture-namespace: configurations
type: object
properties: {}
x-apiture-flattened: true
challengeError:
title: Challenge Error (v1.0.0)
description: |-
The operation error description with an embedded identity challenge.
This schema was resolved from [`auth/challengeError`](https://production.api.apiture.com/schemas/auth/challengeError/v1.0.0/model.json).
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
simpleAddress:
title: Simple Address (v1.0.0)
description: |-
A postal address.
This schema was resolved from [`contacts/simpleAddress`](https://production.api.apiture.com/schemas/contacts/simpleAddress/v1.0.0/model.json).
type: object
properties:
addressLine1:
description: 'The first street address line of the address, normally a house number and street name.'
type: string
minLength: 4
maxLength: 128
addressLine2:
description: The optional second street address line of the address.
type: string
maxLength: 128
city:
description: The name of the city or municipality.
type: string
minLength: 2
maxLength: 128
regionCode:
description: 'The mailing address region code, such as state in the US, or a province in Canada. This is normalized to uppercase.'
type: string
example: NC
minLength: 2
maxLength: 2
pattern: '^[a-zA-Z]{2}$'
postalCode:
description: 'The mailing address postal code, such as a US Zip or Zip+4 code, or a Canadian postal code.'
type: string
example: 28401-5405
minLength: 5
maxLength: 10
pattern: '^[0-9]{5}(?:-[0-9]{4})?$'
countryCode:
description: 'The [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. This is normalized to uppercase.'
type: string
minLength: 2
maxLength: 2
pattern: '^[a-zA-Z]{2}$'
example:
addressLine1: 555 N Front Street
addressLine2: Suite 5555
city: Wilmington
regionCode: NC
postalCode: 28401-5405
countryCode: US
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/simpleAddress/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-flattened: true
addressType:
title: Address Type (v1.0.0)
description: |-
The type of a postal address.
**Warning**: The `enum` list will be removed in a future release.
The allowed values for this property are defined at runtime in the
[label group](https://developer.apiture.com/concepts/label-groups) named `addressType`
in the response from the [`getLabels`](#op-getLabels) operation.
This schema was resolved from [`contacts/addressType`](https://production.api.apiture.com/schemas/contacts/addressType/v1.0.0/model.json).
type: string
x-apiture-choice: addressType
enum:
- unknown
- home
- prior
- work
- school
- mailing
- vacation
- shipping
- billing
- headquarters
- commercial
- site
- property
- other
- notApplicable
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/addressType/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-flattened: true
error:
x-apiture-version: 2.0.0
title: Error (v2.0.0)
description: |-
Describes an error in an API request or in a service called via the API.
This schema was resolved from [`common/error`](https://production.api.apiture.com/schemas/common/error/v2.0.0/model.json).
required:
- message
properties:
message:
type: string
description: A localized message string describing the error condition.
_id:
description: >-
A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at
the source of the error). This is is an opaque string.
readOnly: true
type: string
statusCode:
description: The HTTP status code associate with this error.
type: integer
minimum: 100
maximum: 599
example: 422
type:
type: string
description: >-
An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to
render an appropriate message or hint. This provides a finer level of granularity than the `statusCode`. For example, instead of just 400
Bad Request, the `type` may be much more specific. such as `integerValueNotInAllowedRange` or `numericValueExceedsMaximum` or
`stringValueNotInAllowedSet`.
occurredAt:
type: string
format: date-time
description: 'An [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC time stamp indicating when the error occurred.'
example: '2018-02-02T03:37:15.375Z'
attributes:
description: >-
Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the
`minimum` and `maximum` values. This allows clients to present error messages as they see fit (the API does not assume the
client/presentation tier). The set of attributes varies by error `type`.
allOf:
- $ref: '#/components/schemas/attributes'
remediation:
type: string
description: An optional localized string which provides hints for how the user or client can resolve the error.
errors:
description: An optional array of nested error objects. This property is not always present.
type: array
items:
$ref: '#/components/schemas/error'
_links:
$ref: '#/components/schemas/links'
example:
_id: 2eae46e1575c0a7b0115a4b3
message: Descriptive error message...
statusCode: 422
type: errorType1
remediation: Remediation string...
occurredAt: '2018-01-25T05:50:52.375Z'
errors:
- _id: ccdbe2c5c938a230667b3827
message: An optional embedded error
- _id: dbe9088dcfe2460f229338a3
message: Another optional embedded error
_links:
describedby:
href: 'https://developer.apiture.com/errors/errorType1'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/error/v2.0.0/model.json'
x-apiture-namespace: common
type: object
x-apiture-flattened: true
phoneNumberType:
title: Phone Number Type (v1.0.0)
description: >-
The type or role of this phone number.
**Warning**: The `enum` list will be removed in a future release.
The allowed values for this property are defined at runtime in the
[label group](https://developer.apiture.com/concepts/label-groups) named `phoneNumberType`
in the response from the [`getLabels`](#op-getLabels) operation.
This schema was resolved from
[`contacts/phoneNumberType`](https://production.api.apiture.com/schemas/contacts/phoneNumberType/v1.0.0/model.json).
type: string
x-apiture-choice: phoneNumberType
enum:
- unknown
- home
- work
- mobile
- fax
- other
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/phoneNumberType/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-flattened: true
simpleContact:
title: Simple Contact (v1.0.1)
description: >-
Basic contact and identification information for a person, consisting of the name, mailing address, phone numbers, email addresses, and
government identification.
This schema was resolved from [`contacts/simpleContact`](https://production.api.apiture.com/schemas/contacts/simpleContact/v1.0.1/model.json).
x-apiture-version: 1.0.1
example:
firstName: John
middleName: Daniel
lastName: Smith
preferredName: John
suffix: MD
identification:
- type: taxId
value: '*****3333'
addresses:
- _id: ha1
type: home
addressLine1: 555 N Front Street
addressLine2: Suite 5555
city: Wilmington
regionCode: NC
postalCode: 28401-5405
countryCode: US
preferredMailingAddressId: ha1
emailAddresses:
- id: pe0
value: api@apiture.com
type: personal
- id: wp1
value: support@apiture.com
type: work
preferredEmailAddressId: pe0
phones:
- _id: hp1
type: home
number: '+19105550155'
- _id: mp1
type: mobile
number: '+19105550159'
preferredPhoneId: hp1
preferredContactMethod: email
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/simpleContact/v1.0.1/model.json'
x-apiture-namespace: contacts
x-apiture-composition:
- $ref: '#/components/schemas/contactName'
- $ref: '#/components/schemas/addresses'
- $ref: '#/components/schemas/emailAddresses'
- $ref: '#/components/schemas/phoneNumbers'
- $ref: '#/components/schemas/simpleContactFields'
properties:
firstName:
description: The person's first name (or given name).
type: string
middleName:
description: The person's middle name.
type: string
lastName:
description: The person's last name (or surname).
type: string
addresses:
description: An array of postal/mailing addresses.
type: array
items:
$ref: '#/components/schemas/address'
preferredMailingAddressId:
description: The preferred mailing address. This string is the `_id` of an address in the `addresses` array.
type: string
minLength: 1
maxLength: 4
emailAddresses:
description: An array of email addresses.
type: array
items:
$ref: '#/components/schemas/typedEmailAddress'
preferredEmailAddressId:
description: The preferred email address. This string is the `_id` of an email address in the `emailAddresses` array.
type: string
minLength: 1
maxLength: 4
phones:
description: An array of phone numbers.
type: array
items:
$ref: '#/components/schemas/phoneNumber'
preferredPhoneId:
description: The ID of preferred phone number. This string is the `_id` of a phone number in the `phones` array.
type: string
minLength: 1
maxLength: 4
prefix:
description: A title or honorific prefix such as Dr. or Fr.
type: string
maxLength: 20
suffix:
description: A title or honorific suffix such as PhD or DDS.
type: string
maxLength: 20
preferredName:
description: >-
The contact's preferred name. This is how the contact's name is presented to the user in the interface. The default is the contact's
`firstName`.
type: string
identification:
description: A collection of official identifying information associated with the contact.
x-apiture-pii: true
type: array
items:
$ref: '#/components/schemas/identification'
preferredContactMethod:
description: The contact's preferred method of communication.
allOf:
- $ref: '#/components/schemas/preferredContactMethod'
type: object
x-apiture-flattened: true
identifiedContactFields:
title: Identified Contact Fields (v1.0.0)
description: >-
Properties which provide additional identification of a person.
This schema was resolved from
[`contacts/identifiedContactFields`](https://production.api.apiture.com/schemas/contacts/identifiedContactFields/v1.0.0/model.json).
x-apiture-fragment: true
type: object
properties:
birthdate:
description: The contact's birth date in `YYYY-MM-DD` format.
type: string
format: date
citizenship:
description: This individual's citizenship or nationality status.
allOf:
- $ref: '#/components/schemas/citizenship'
residencyStatus:
description: This individual's residency status.
allOf:
- $ref: '#/components/schemas/residencyStatus'
occupation:
description: The occupation of this individual.
allOf:
- $ref: '#/components/schemas/occupation'
otherOccupation:
description: The actual occupation of this individual if their `occupation` is `other`. This is ignored if `occupation` is not `other`.
type: string
minLength: 4
maxLength: 32
yearsAtAddress:
description: The number of years the person has been at their present home address.
allOf:
- $ref: '#/components/schemas/yearsAtAddress'
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/identifiedContactFields/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-flattened: true
links:
title: Links (v1.0.0)
x-apiture-version: 1.0.0
description: |-
An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.
This schema was resolved from [`common/links`](https://production.api.apiture.com/schemas/common/links/v1.0.0/model.json).
type: object
x-apiture-key: linkRelationName
additionalProperties:
$ref: '#/components/schemas/link'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/links/v1.0.0/model.json'
x-apiture-namespace: common
properties: {}
x-apiture-flattened: true
emailType:
title: Email Type (v1.0.0)
description: |-
The kind of email address.
**Warning**: The `enum` list will be removed in a future release.
The allowed values for this property are defined at runtime in the
[label group](https://developer.apiture.com/concepts/label-groups) named `emailType`
in the response from the [`getLabels`](#op-getLabels) operation.
This schema was resolved from [`contacts/emailType`](https://production.api.apiture.com/schemas/contacts/emailType/v1.0.0/model.json).
type: string
x-apiture-choice: emailType
enum:
- unknown
- personal
- work
- school
- other
- notApplicable
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/emailType/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-flattened: true
labelItem:
title: Label Item (v1.0.0)
description: >-
An item in a [`labelGroup`](#schema-labelgroup), with a set of `variants` which contains different localized labels for the item. Each
([`simpleLabel`](#schema-simpleLabel)) variant defines the presentation text label and optional description for a language. Items may also
have a lookup `code` to map to external syststems, a numeric range, and a `hidden` boolean to indicate the item is normally hidden in the UI.
This schema was resolved from [`common/labelItem`](https://production.api.apiture.com/schemas/common/labelItem/v1.0.0/model.json).
x-apiture-version: 1.0.0
example:
over100Million:
label: 'Over $100,000,000.00'
code: '4'
range: '[100000000.00,]'
variants:
fr:
label: Plus de $10M
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/labelItem/v1.0.0/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/components/schemas/simpleLabel'
- properties:
- variants
- code
- hidden
- range
properties:
label:
type: string
description: A label or title which may be used as labels or other UI controls which present a value.
example: Board of Directors
description:
type: string
description: A more detailed localized description of a localizable label.
variants:
description: >-
The language-specific variants of this label. The keys in this object are [RFC 7231](https://tools.ietf.org/html/rfc7231#section-3.1.3.1)
language codes.
x-apiture-key: languageCode
type: object
additionalProperties:
$ref: '#/components/schemas/simpleLabel'
example:
en:
label: More then $10M
es:
label: Mas de $10M
fr:
label: Plus de $10M
code:
type: string
description: 'If the localized value is associated with an external standard or definition, this is a lookup code or key or URI for that value.'
example: '3'
minLength: 1
hidden:
type: boolean
description: 'If `true`, this item is normally hidden from the User Interface.'
range:
description: >-
The range of values, if the item describes a bounded numeric value. This is range notation such as `[min,max]`, `(exclusiveMin,max]`,
`[min,exclusiveMax)`, or `(exclusiveMin,exclusiveMax)`. For example, `[0,100)` is the range greater than or equal to 0 and less than 100.
If the *min* or *max* value are omitted, that end of the range is unbounded. For example, `(,1000.00)` means less than 1000.00 and
`[20000.00,]` means 20000.00 or more. The ranges do not overlap or have gaps.
type: string
pattern: '^[\[\(](-?(0|[1-9][0-9]*)(\.[0-9]+)?)?,(-?(0|[1-9][0-9]*)(\.[0-9]+)?)?[\]\)]$'
type: object
x-apiture-flattened: true
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).
Links
Response and request bodies using this challenge
schema may contain
the following links:
This schema was resolved from [`auth/challenge`](https://production.api.apiture.com/schemas/auth/challenge/v1.0.1/model.json).
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
encryptionKeyName:
title: Encryption Key Name (v1.0.1)
description: >-
An encryption key name identifies the type of data that the client wishes to encrypt, such as `pii` for personally identifying information,
`secret` for passwords or other secret data. The type name is taken from the `x-apiture-encrypt` annotation on the property in the JSON schema
or chosen by the client when requesting encryption keys.
This schema was resolved from
[`common/encryptionKeyName`](https://production.api.apiture.com/schemas/common/encryptionKeyName/v1.0.1/model.json).
x-apiture-version: 1.0.1
type: string
minLength: 3
maxLength: 10
pattern: '^[a-z][a-zA-Z0-9]{2,9}$'
example: secret
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/encryptionKeyName/v1.0.1/model.json'
x-apiture-namespace: common
x-apiture-flattened: true
contactName:
title: Name (v1.0.0)
description: |-
A person's name.
This schema was resolved from [`contacts/contactName`](https://production.api.apiture.com/schemas/contacts/contactName/v1.0.0/model.json).
x-apiture-fragment: true
properties:
firstName:
description: The person's first name (or given name).
type: string
middleName:
description: The person's middle name.
type: string
lastName:
description: The person's last name (or surname).
type: string
example:
firstName: John
middleName: Daniel
lastName: Smith
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/contactName/v1.0.0/model.json'
x-apiture-namespace: contacts
type: object
x-apiture-flattened: true
addresses:
title: Addresses (v1.0.0)
description: |-
A list of postal addresses and the preferred mailing address.
This schema was resolved from [`contacts/addresses`](https://production.api.apiture.com/schemas/contacts/addresses/v1.0.0/model.json).
x-apiture-fragment: true
properties:
addresses:
description: An array of postal/mailing addresses.
type: array
items:
$ref: '#/components/schemas/address'
preferredMailingAddressId:
description: The preferred mailing address. This string is the `_id` of an address in the `addresses` array.
type: string
minLength: 1
maxLength: 4
example:
addresses:
- _id: ha1
type: home
addressLine1: 555 N Front Street
addressLine2: Suite 5555
city: Wilmington
regionCode: NC
postalCode: 28401-5405
countryCode: US
- _id: wa1
type: work
addressLine1: 123 S 3rd Street
addressLine2: Apt 42
city: Wilmington
regionCode: NC
postalCode: 28411-5405
countryCode: US
preferredMailingAddressId: ha1
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/addresses/v1.0.0/model.json'
x-apiture-namespace: contacts
type: object
x-apiture-flattened: true
emailAddresses:
title: Email Addresses (v1.0.0)
description: >-
A list of email addresses and the preferred email address.
This schema was resolved from
[`contacts/emailAddresses`](https://production.api.apiture.com/schemas/contacts/emailAddresses/v1.0.0/model.json).
x-apiture-fragment: true
properties:
emailAddresses:
description: An array of email addresses.
type: array
items:
$ref: '#/components/schemas/typedEmailAddress'
preferredEmailAddressId:
description: The preferred email address. This string is the `_id` of an email address in the `emailAddresses` array.
type: string
minLength: 1
maxLength: 4
example:
emailAddresses:
- id: pe0
value: api@apiture.com
type: personal
- id: wp1
value: support@apiture.com
type: work
preferredEmailAddressId: pe0
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/emailAddresses/v1.0.0/model.json'
x-apiture-namespace: contacts
type: object
x-apiture-flattened: true
phoneNumbers:
title: Phone Numbers (v1.0.1)
description: |-
A list of phone numbers and the preferred phone number.
This schema was resolved from [`contacts/phoneNumbers`](https://production.api.apiture.com/schemas/contacts/phoneNumbers/v1.0.1/model.json).
x-apiture-fragment: true
x-apiture-version: 1.0.1
properties:
phones:
description: An array of phone numbers.
type: array
items:
$ref: '#/components/schemas/phoneNumber'
preferredPhoneId:
description: The ID of preferred phone number. This string is the `_id` of a phone number in the `phones` array.
type: string
minLength: 1
maxLength: 4
example:
phones:
- _id: hp1
type: home
number: '+19105550155'
- _id: mp1
type: mobile
number: '+19105550159'
preferredPhoneId: hp1
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/phoneNumbers/v1.0.1/model.json'
x-apiture-namespace: contacts
type: object
x-apiture-flattened: true
simpleContactFields:
title: Simple Contact Fields (v1.0.0)
description: >-
Additional properties for a person or contact.
This schema was resolved from
[`contacts/simpleContactFields`](https://production.api.apiture.com/schemas/contacts/simpleContactFields/v1.0.0/model.json).
x-apiture-fragment: true
type: object
properties:
prefix:
description: A title or honorific prefix such as Dr. or Fr.
type: string
maxLength: 20
suffix:
description: A title or honorific suffix such as PhD or DDS.
type: string
maxLength: 20
preferredName:
description: >-
The contact's preferred name. This is how the contact's name is presented to the user in the interface. The default is the contact's
`firstName`.
type: string
identification:
description: A collection of official identifying information associated with the contact.
x-apiture-pii: true
type: array
items:
$ref: '#/components/schemas/identification'
preferredContactMethod:
description: The contact's preferred method of communication.
allOf:
- $ref: '#/components/schemas/preferredContactMethod'
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/simpleContactFields/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-flattened: true
link:
x-apiture-version: 1.0.0
title: Link (v1.0.0)
description: >-
Describes a hypermedia link within a `_links` object in HAL representations. In Apiture APIs, links are [HAL
links](https://developer.apiture.com/docs/concepts/links), but Apiture APIs do not use the `name` or `hreflang` properties of HAL. Apiture
links _may_ include a `method` property.
This schema was resolved from [`common/link`](https://production.api.apiture.com/schemas/common/link/v1.0.0/model.json).
required:
- href
properties:
href:
type: string
format: uri
description: The URI or URI template for the resource/operation this link refers to.
type:
type: string
description: The media type for the resource.
templated:
type: boolean
description: 'If true, the link''s href is a [URI template](https://tools.ietf.org/html/rfc6570).'
title:
type: string
description: An optional human-readable localized title for the link.
deprecation:
type: string
format: uri
description: 'If present, the containing link is deprecated and the value is a URI which provides human-readable text information about the deprecation.'
profile:
type: string
format: uri
description: 'The URI of a profile document, a JSON document which describes the target resource/operation.'
example:
href: /contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f
title: Applicant
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/link/v1.0.0/model.json'
x-apiture-namespace: common
type: object
x-apiture-flattened: true
citizenship:
title: Citizenship (v1.0.0)
description: |-
Citizenship or nationality status.
This schema was resolved from [`contacts/citizenship`](https://production.api.apiture.com/schemas/contacts/citizenship/v1.0.0/model.json).
type: array
items:
type: object
required:
- countryCode
- state
properties:
countryCode:
description: The ISO 3166-1 country code for the individual's citizenship.
x-apiture-pii: true
type: string
minLength: 2
maxLength: 2
state:
description: The individual's citizenship status.
x-apiture-pii: true
type: string
enum:
- citizen
- other
example:
- countryCode: US
state: citizen
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/citizenship/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-flattened: true
residencyStatus:
title: Residency (v1.0.0)
description: >-
Residency status.
**Warning**: The `enum` list will be removed in a future release.
The allowed values for this property are defined at runtime in the
[label group](https://developer.apiture.com/concepts/label-groups) named `residencyStatus`
in the response from the [`getLabels`](#op-getLabels) operation.
This schema was resolved from
[`contacts/residencyStatus`](https://production.api.apiture.com/schemas/contacts/residencyStatus/v1.0.0/model.json).
type: string
x-apiture-choice: residencyStatus
enum:
- unknown
- resident
- nonresident
- residentAlien
- nonresidentAlien
- other
- notApplicable
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/residencyStatus/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-flattened: true
occupation:
title: Occupation (v1.0.0)
description: |-
The person's occupation.
**Warning**: The `enum` list will be removed in a future release.
The allowed values for this property are defined at runtime in the
[label group](https://developer.apiture.com/concepts/label-groups) named `occupation`
in the response from the [`getLabels`](#op-getLabels) operation.
This schema was resolved from [`contacts/occupation`](https://production.api.apiture.com/schemas/contacts/occupation/v1.0.0/model.json).
type: string
x-apiture-choice: occupation
enum:
- unknown
- architectureAndEngineering
- artsDesignEntertainmentSportsAndMedia
- buildingAndGroundsCleaningAndMaintenance
- businessAndFinancialOperations
- communityAndSocialService
- computerAndMathematical
- constructionAndExtraction
- educationTrainingAndLibrary
- farmingFishingAndForestry
- foodPreparationAndServingRelated
- healthcarePractitionersAndTechnical
- healthcareSupport
- installationMaintenanceAndRepair
- legal
- lifePhysicalAndSciences
- management
- militarySpecific
- officeAndAdministrativeSupport
- personalCareAndService
- production
- protectiveServices
- salesAndRelated
- transportationAndMaterialMoving
- other
- notApplicable
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/occupation/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-flattened: true
summaryChallenge:
title: Summary Challenge (v1.0.0)
description: |-
Summary representation of a challenge, used in the challenge collection.
This schema was resolved from [`auth/summaryChallenge`](https://production.api.apiture.com/schemas/auth/summaryChallenge/v1.0.0/model.json).
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.
Links
Response and request bodies using this authenticator
schema may contain
the following links:
This schema was resolved from [`auth/authenticator`](https://production.api.apiture.com/schemas/auth/authenticator/v1.0.1/model.json).
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
simpleLabel:
title: Simple Label (v1.0.0)
description: |-
A text label and optional description.
This schema was resolved from [`common/simpleLabel`](https://production.api.apiture.com/schemas/common/simpleLabel/v1.0.0/model.json).
x-apiture-version: 1.0.0
type: object
required:
- label
properties:
label:
type: string
description: A label or title which may be used as labels or other UI controls which present a value.
example: Board of Directors
description:
type: string
description: A more detailed localized description of a localizable label.
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/simpleLabel/v1.0.0/model.json'
x-apiture-namespace: common
x-apiture-flattened: true
identification:
title: Identification (v1.0.0)
description: >-
Official identifying information associated with the contact.
This schema was resolved from
[`contacts/identification`](https://production.api.apiture.com/schemas/contacts/identification/v1.0.0/model.json).
type: object
required:
- type
- value
properties:
value:
description: >-
The value of this form of identification, such as tax ID as a string. The caller should pass the full `value` (for example
`"112-22-3333"`) when creating a contact or user. The input `value` may include `'-'` formatting characters. This is a _masked_ value in
API responses, with one or more leading `'*'` characters and only the last four characters unmasked, such as `"*****3333"`.
type: string
x-apiture-pii: true
type:
description: The type of this form of identification.
type: string
allOf:
- $ref: '#/components/schemas/identificationType'
enum:
- taxId
- passportNumber
expiration:
description: 'The date when the form of identification expires, in [RFC 3339](https://tools.ietf.org/html/rfc3339) `YYYY-MM-DD` format.'
type: string
format: date
example:
type: taxId
value: 112-22-3333
expiration: '2024-12-01'
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/identification/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-flattened: true
preferredContactMethod:
title: Preferred Contact Method (v1.0.0)
description: >-
The contact's preferred method of communication.
**Warning**: The `enum` list will be removed in a future release.
The allowed values for this property are defined at runtime in the
[label group](https://developer.apiture.com/concepts/label-groups) named `preferredContactMethod`
in the response from the [`getLabels`](#op-getLabels) operation.
This schema was resolved from
[`contacts/preferredContactMethod`](https://production.api.apiture.com/schemas/contacts/preferredContactMethod/v1.0.0/model.json).
type: string
enum:
- unknown
- sms
- email
- other
- notApplicable
x-apiture-choice: preferredContactMethod
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/preferredContactMethod/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-flattened: true
authenticatorFields:
title: Authenticator Fields (v1.0.0)
description: >-
Common fields of an authenticator.
This schema was resolved from
[`auth/authenticatorFields`](https://production.api.apiture.com/schemas/auth/authenticatorFields/v1.0.0/model.json).
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):
Value | Description |
pending | Pending: The authenticator is created but not yet started. |
started | Started: The user has started the authenticator. |
verified | Verified: The user corresponding verified the authenticator. |
failed | Failed: The user failed the authenticators criteria. |
expired | Expired: The authenticator expired before the user completed the criteria. |
These enumeration values are further described by the [label group](https://developer.apiture.com/concepts/label-groups)
named `authenticatorState` in the response from the [`getLabels`](#op-getLabels) operation.
This schema was resolved from
[`auth/authenticatorState`](https://production.api.apiture.com/schemas/auth/authenticatorState/v1.0.0/model.json).
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
challengeFields:
title: Challenge Fields (v1.0.0)
description: |-
Properties of challenge objects.
This schema was resolved from [`auth/challengeFields`](https://production.api.apiture.com/schemas/auth/challengeFields/v1.0.0/model.json).
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):
Value | Description |
pending | Pending: The challenge is created but not yet started. |
started | Started: The user has started the challenge and associated authenticator(s). |
verified | Verified: The user correctly verified the corresponding authenticator(s), marking the challenge as verified. |
failed | Failed: The challenge has failed, often because the user failed one or more of the authenticators. |
redeemed | Redeemed: The user has redeemed (used) the challenge. |
expired | Expired: The challenge has expired without being verified. |
These enumeration values are further described by the [label group](https://developer.apiture.com/concepts/label-groups)
named `challengeState` in the response from the [`getLabels`](#op-getLabels) operation.
This schema was resolved from [`auth/challengeState`](https://production.api.apiture.com/schemas/auth/challengeState/v1.0.0/model.json).
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
identificationType:
title: Identification Type (v1.0.0)
description: >-
The type of this form of identification.
identificationType
strings may have one of the following
[enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations):
Value | Description |
taxId | Tax ID: The government tax ID, such as a Social Security Number |
passportNumber | Passport Number |
These enumeration values are further described by the [label group](https://developer.apiture.com/concepts/label-groups)
named `identificationType` in the response from the [`getLabels`](#op-getLabels) operation.
This schema was resolved from
[`contacts/identificationType`](https://production.api.apiture.com/schemas/contacts/identificationType/v1.0.0/model.json).
type: string
x-apiture-enum: identificationType
enum:
- taxId
- passportNumber
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/identificationType/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-flattened: true
authenticatorType:
title: Authenticator Type (v1.0.0)
description: |-
An authenticator type description.
This schema was resolved from [`auth/authenticatorType`](https://production.api.apiture.com/schemas/auth/authenticatorType/v1.0.0/model.json).
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):
Value | Description |
knowledge | Knowledge: Authenticate with information the user knows, such as a password or answers to personal questions. |
biometric | Biometric: Authenticate with physical characteristics of the user, such as fingerprints, voiceprint, or faceprint. |
device | Device: Authenticate with a device that the user has, such as a mobile phone or an electronic key. |
These enumeration values are further described by the [label group](https://developer.apiture.com/concepts/label-groups)
named `authenticatorCategory` in the response from the [`getLabels`](#op-getLabels) operation.
This schema was resolved from
[`auth/authenticatorCategory`](https://production.api.apiture.com/schemas/auth/authenticatorCategory/v1.0.0/model.json).
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.
This error response may have one of the following `type` values:
* [`invalidAddressType`](#err-invalidAddressType)
* [`invalidPhoneType`](#err-invalidPhoneType)
* [`cannotChangeId`](#err-cannotChangeId)
x-apiture-errors:
- invalidAddressType
- invalidPhoneType
- cannotChangeId
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'
404PhoneNumber:
description: >-
Not Found. There is no such phone number resource at the specified `{phoneNumberId}`. 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'
404EmailAddress:
description: >-
Not Found. There is no such email address resource at the specified `{emailAddressId}`. 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'
404Address:
description: >-
Not Found. There is no such address resource at the specified `{addressId}`. 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.
409Challenge:
description: Conflict. The operation requires an additional Apiture-Challenge identity verification in the request header.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/challengeErrorResponse'
application/json:
schema:
$ref: '#/components/schemas/challengeErrorResponse'
409AddressConflict:
description: Conflict. The selected address cannot be deleted because it is currently the user's preferred address.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
409EmailAddressConflict:
description: Conflict. The selected email address cannot be deleted because it is currently the user's preferred email address.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
409PhoneNumberConflict:
description: Conflict. The selected phone number cannot be deleted because it is currently the user's preferred phone number.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
409PreferredConflict:
description: >-
Conflict. The selected profile value cannot be set as the preferred because it is still `pending`, or no `Apiture-Challenge` request header
was passed when expected, or the challenge has not been verified, has expired, or has been redeemed too many times.
This error response may have one of the following `type` values:
* [`itemStillPending`](#err-itemStillPending)
* [`missingApitureChallengeHeader`](#err-missingApitureChallengeHeader)
* [`challengedNotVerified`](#err-challengedNotVerified)
* [`challengedExpired`](#err-challengedExpired)
* [`challengedAlreadyRedeemed`](#err-challengedAlreadyRedeemed)
x-apiture-errors:
- itemStillPending
- missingApitureChallengeHeader
- challengedNotVerified
- challengedExpired
- challengedAlreadyRedeemed
content:
application/hal+json:
schema:
$ref: '#/components/schemas/challengeErrorResponse'
application/json:
schema:
$ref: '#/components/schemas/challengeErrorResponse'
422PreferredUnprocessable:
description: >-
Unprocessable Entity. The request to set a preferred profile value cannot be processed because no such profile value value exists, or the
passed challenge does not exist.
This error response may have one of the following `type` values:
* [`noSuchProfileValue`](#err-noSuchProfileValue)
* [`noSuchChallenge`](#err-noSuchChallenge)
x-apiture-errors:
- noSuchProfileValue
- noSuchChallenge
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
404ConfigurationGroup:
description: >-
Not Found. There is no such configuration group resource at the specified `{groupName}` 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'
404ConfigurationGroupOrValue:
description: >-
Not Found. There is either no such configuration group resource at the specified `{groupName}` or no such value at the specified
`{valueName}`. 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'
409UserConflict:
description: |-
Conflict. There is a conflict between the request and the current state of the resource. It may be one of the following:
* The `state` of a `removed` user may not be changed.
* The `state` cannot be updated via a `PUT` or `POST` request. Please use the appropriate endpoint to change the state.
* Some key fields of the user record may not be changed or removed, such as their government id
This error response may have one of the following `type` values:
* [`updateUserError`](#err-updateUserError)
* [`duplicateUsername`](#err-duplicateUsername)
* [`duplicateTaxId`](#err-duplicateTaxId)
* [`cannotUpdateState`](#err-cannotUpdateState)
* [`invalidStateChange`](#err-invalidStateChange)
x-apiture-errors:
- updateUserError
- duplicateUsername
- duplicateTaxId
- cannotUpdateState
- invalidStateChange
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
404User:
description: >-
Not Found. There is no such user resource at the specified `{userId}` The `_error` field in the response will contain details about the
request error.
This error response may have one of the following `type` values:
* [`invalidUserId`](#err-invalidUserId)
x-apiture-errors:
- invalidUserId
content:
application/hal+json:
schema:
$ref: '#/components/schemas/errorResponse'
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
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
phoneNumberIdPathParam:
name: phoneNumberId
description: The unique identifier of this phone number. This is an opaque string.
in: path
required: true
schema:
type: string
filterQueryParam:
name: filter
in: query
description: 'Optional filter criteria. See [filtering](https://developer.apiture.com/docs/concepts/filtering).'
schema:
type: string
qQueryParam:
name: q
in: query
description: 'Optional search string. See [searching](https://developer.apiture.com/docs/concepts/searching).'
schema:
type: string
emailAddressIdPathParam:
name: emailAddressId
description: The unique identifier of this email address. This is an opaque string.
in: path
required: true
schema:
type: string
addressIdPathParam:
name: addressId
description: The unique identifier of this address. 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. If used, this must match the current entity tag of the resource.'
in: header
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
userIdPathParam:
name: userId
description: The unique identifier of the user. This is an opaque string.
in: path
required: true
schema:
type: string
stateQueryParam:
name: state
in: query
description: >-
Subset the users collection to those whose `state` matches this value. Use `|` to separate multiple values. For example, `?state=pending`
matches only items whose `state` is `pending`; `?state=removed|inactive` matches items whose `state` is `removed` or `inactive`. This is
combined with an implicit `and` with other filters if they are used. See [filtering](https://developer.apiture.com/docs/concepts/filtering).
schema:
type: string
enum:
- locked
- frozen
- active
- inactive
- removed
customerIdQueryParam:
name: customerId
in: query
description: >-
Subset the users collection to those whose `customerId` matches this value. This is combined with an implicit `and` with other filters if they
are used. See [filtering](https://developer.apiture.com/docs/concepts/filtering).
schema:
type: string
occupationQueryParam:
name: occupation
in: query
description: >-
Subset the users collection to those with this name value. Use `|` to separate multiple values. For example,
?occupation=officeAndAdministrativeSupport will match only items whose occupation is officeAndAdministrativeSupport;
?occupation=officeAndAdministrativeSupport|transportationAndMaterialMoving will match items whose occupation is officeAndAdministrativeSupport
or transportationAndMaterialMoving. This is combined with an implicit and with other filters if they are used. See
[filtering](https://developer.apiture.com/docs/concepts/filtering).
schema:
type: string
configurationGroupNamePathParam:
name: groupName
description: The unique name of this configuration group.
in: path
required: true
schema:
type: string
configurationGroupValueNamePathParam:
name: valueName
description: >-
The unique name of a value in a configuration group. This is the name of the value in the `schema`. A `{valueName}` must be a simple
identifier following the pattern _`letter [letter | digit | '-' | '_']*`_
in: path
required: true
schema:
type: string
requestBodies:
user:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/user'
application/json:
schema:
$ref: '#/components/schemas/user'
required: true
updateConstraints:
content:
application/hal+json:
schema:
$ref: '#/components/schemas/updateConstraints'
application/json:
schema:
$ref: '#/components/schemas/updateConstraints'
required: true
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.devbank.apiture.com/auth/oauth2/authorize'
tokenUrl: 'https://api.devbank.apiture.com/auth/oauth2/token'
scopes:
profiles/read: Read access to user and contact related resources.
profiles/write: Write (update) access to user and contact related resources.
profiles/delete: Delete access to user and contact related resources.
profiles/readPii: >-
Read access to personally identifiable information such as tax ID numbers, phone numbers, email and postal addresses. This must be
granted in addition to the `profiles/read` scope in order to read such data, but is included in the `profiles/full` scope.
profiles/full: Full access to user and contact related resources.
admin/read: Read access to system configuration or profile data.
admin/write: Write (update) access to user and contact related resources just for administrative roles.
admin/delete: Delete access to system configuration.
admin/full: Full access to system configuration.