swagger: '2.0'
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}`).
The user can be unlocked by resetting their password.
Unlocking a user is done by reactivating them
(`POST /activeUsers?user={userId}`).
* Deactivate - If the financial institution wishes to suspend a user's activity.
(`POST /inactiveUsers?user={userId}`).
Inactive users can be reactivated
(`POST /activeUsers?user={userId}`)`.
* Freeze - If the financial institution suspects fraudulent use of a user's account,
they can freeze a user.
(`POST /frozenUsers?user={userId}`).
Unfreezing a user is done by reactivating them
(`POST /activeUsers?user={userId}`)`.
* Remove - The financial institution can remove a user when they leave the financial institution.
(`POST /removedUsers?user={userId}`).
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.
## 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` operation
1. `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, contains a `challenge` resource which includes
one or more _authenticators_. 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.
## accessDenied
**Description**: The credentials supplied in the request are insufficient to grant access.
**Remediation**: Check the supplied credentials for validity.
## 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, /frozenUsers and
/mergedUsers 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.
## mergeUserDoesNotExist
**Description**: One of the users in the merge does not exist.
**Remediation**: Resubmit the operation with two users that exist.
## arrayRequired
**Description**: The property must be an array.
**Remediation**: Resubmit the operation with the property being in the proper format.
## invalidDate
**Description**: The date of birth that was specified is not valid.
**Remediation**: Resubmit the operation with a valid date in the RFC 3339 format.
## 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.
##
**Description**: Precondition Required. The request did not include the required if-Match header.
**Remediation**: Resubmit with the operation, supplying the value of the ETag and the most recent state of the resource.
##
**Description**: The supplied `if-Match` header value does not match the most recent `ETag` response header value. The resource has changed in the
interim.
**Remediation**: Resubmit the operation, supplying the value of the ETag and the most recent state of the resource.
## requestError
**Description**: There was a server side error when executing the API request.
**Remediation**: Check your parameters and resubmit the request.
## 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.
## invalidAddressType
**Description**: An invalid address type was given.
**Remediation**: Resubmit the operation with a valid address type according to the Users API documentation.
## invalidGroupName
**Description**: No configurationGroup was found for the specified groupName.
**Remediation**: Check to make sure that the supplied groupName corresponds to an apiture transfer configuration group resource.
## invalidValueName
**Description**: No configurationName was found for the specified valueName.
**Remediation**: Check to make sure that the supplied valueName corresponds to an apiture transfer configuration value resource.
## invalidConfigurationGroup
**Description**: The request body did not conform to the schema for this configuration group.
**Remediation**: Check the schema for the configuration group and resubmit the operation.
## invalidConfigurationValue
**Description**: The request body did not conform to the schema for this configuration group value.
**Remediation**: Check the schema for the configuration group value and resubmit the operation.
## configurationAccessDenied
**Description**: The credentials supplied in the request are insufficient to grant access.
**Remediation**: Check the supplied credentials for validity.
## 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.
##
**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.
version: 0.18.7
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.
schemes:
- https
basePath: /users
consumes:
- application/hal+json
- application/json
produces:
- application/hal+json
- application/json
tags:
- name: API
description: Endpoints which describe this API
- name: User
description: Endpoints to manage users
- name: User Actions
description: Actions on users
securityDefinitions:
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
flow: accessCode
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.
authorizationUrl: /auth/oauth2/authorize
tokenUrl: /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.
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.
paths:
'/users/{userId}/addresses':
parameters:
- $ref: '#/parameters/userIdPathParam'
get:
summary: Get user's addresses
description: Return the list of the user's addresses.
operationId: getAddresses
x-apiture-implemented: true
tags:
- Address
responses:
'200':
description: OK
schema:
$ref: '#/definitions/userAddresses'
'400':
$ref: '#/responses/400'
'422':
$ref: '#/responses/422'
security:
- apiKey: []
accessToken:
- profiles/read
parameters: []
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:
- Address
parameters:
- name: address
in: body
description: The data necessary to create a new address.
required: true
schema:
$ref: '#/definitions/userAddress'
- name: replaceId
in: query
type: string
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`
- $ref: '#/parameters/apitureChallengeHeaderParam'
responses:
'201':
description: Created
schema:
$ref: '#/definitions/userAddress'
headers:
Location:
description: >-
The URI of the new resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with
*`scheme`*`://host`
type: string
format: uri
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update the resource.
type: string
'400':
$ref: '#/responses/400'
'409':
$ref: '#/responses/409PreferredConflict'
security:
- apiKey: []
accessToken:
- profiles/write
'/users/{userId}/addresses/{addressId}':
parameters:
- $ref: '#/parameters/userIdPathParam'
- $ref: '#/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:
- Address
parameters:
- $ref: '#/parameters/ifNoneMatchHeaderParam'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/userAddress'
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.
type: string
'304':
$ref: '#/responses/304'
'404':
$ref: '#/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:
- Address
responses:
'204':
$ref: '#/responses/204Deleted'
'409':
$ref: '#/responses/409AddressConflict'
security:
- apiKey: []
accessToken:
- profiles/delete
parameters: []
'/users/{userId}/emailAddresses':
parameters:
- $ref: '#/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 Address
responses:
'200':
description: OK
schema:
$ref: '#/definitions/userEmailAddresses'
'400':
$ref: '#/responses/400'
'422':
$ref: '#/responses/422'
security:
- apiKey: []
accessToken:
- profiles/read
parameters: []
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 Address
parameters:
- name: emailAddress
in: body
description: The data necessary to create a new email address.
required: true
schema:
$ref: '#/definitions/userEmailAddress'
- name: replaceId
in: query
type: string
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`
- $ref: '#/parameters/apitureChallengeHeaderParam'
responses:
'201':
description: Created
schema:
$ref: '#/definitions/userEmailAddress'
headers:
Location:
description: >-
The URI of the new resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with
*`scheme`*`://host`
type: string
format: uri
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update the resource.
type: string
'400':
$ref: '#/responses/400'
'409':
$ref: '#/responses/409PreferredConflict'
security:
- apiKey: []
accessToken:
- profiles/write
'/users/{userId}/emailAddresses/{emailAddressId}':
parameters:
- $ref: '#/parameters/userIdPathParam'
- $ref: '#/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 Address
parameters:
- $ref: '#/parameters/ifNoneMatchHeaderParam'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/userEmailAddress'
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.
type: string
'304':
$ref: '#/responses/304'
'404':
$ref: '#/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 Address
responses:
'204':
$ref: '#/responses/204Deleted'
'409':
$ref: '#/responses/409EmailAddressConflict'
security:
- apiKey: []
accessToken:
- profiles/delete
parameters: []
'/users/{userId}/phoneNumbers':
parameters:
- $ref: '#/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 Number
responses:
'200':
description: OK
schema:
$ref: '#/definitions/userPhoneNumbers'
'400':
$ref: '#/responses/400'
'422':
$ref: '#/responses/422'
security:
- apiKey: []
accessToken:
- profiles/read
parameters: []
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 Number
parameters:
- name: phoneNumber
in: body
description: The data necessary to create a new phone number.
required: true
schema:
$ref: '#/definitions/userPhoneNumber'
- name: replaceId
in: query
type: string
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`
- $ref: '#/parameters/apitureChallengeHeaderParam'
responses:
'201':
description: Created
schema:
$ref: '#/definitions/userPhoneNumber'
headers:
Location:
description: >-
The URI of the new resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with
*`scheme`*`://host`
type: string
format: uri
ETag:
description: >-
The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`* or *`PATCH`*
operations which update the resource.
type: string
'400':
$ref: '#/responses/400'
'409':
$ref: '#/responses/409PreferredConflict'
security:
- apiKey: []
accessToken:
- profiles/write
'/users/{userId}/phoneNumbers/{phoneNumberId}':
parameters:
- $ref: '#/parameters/userIdPathParam'
- $ref: '#/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 Number
parameters:
- $ref: '#/parameters/ifNoneMatchHeaderParam'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/userPhoneNumber'
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.
type: string
'304':
$ref: '#/responses/304'
'404':
$ref: '#/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 Number
responses:
'204':
$ref: '#/responses/204Deleted'
'409':
$ref: '#/responses/409PhoneNumberConflict'
security:
- apiKey: []
accessToken:
- profiles/delete
parameters: []
'/users/{userId}/preferredAddress':
parameters:
- $ref: '#/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:
- Address
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
type: string
- $ref: '#/parameters/apitureChallengeHeaderParam'
responses:
'200':
description: OK. The user's `preferredAddressId` is updated to the passed value.
schema:
$ref: '#/definitions/user'
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.
type: string
'409':
$ref: '#/responses/409PreferredConflict'
'422':
$ref: '#/responses/422PreferredUnprocessable'
'/users/{userId}/preferredEmailAddress':
parameters:
- $ref: '#/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 Address
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
type: string
- $ref: '#/parameters/apitureChallengeHeaderParam'
responses:
'200':
description: OK. The user's `preferredEmailAddressId` is updated to the passed value.
schema:
$ref: '#/definitions/user'
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.
type: string
'409':
$ref: '#/responses/409PreferredConflict'
'422':
$ref: '#/responses/422PreferredUnprocessable'
'/users/{userId}/preferredPhoneNumber':
parameters:
- $ref: '#/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 Number
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
type: string
- $ref: '#/parameters/apitureChallengeHeaderParam'
responses:
'200':
description: OK. The user's `preferredPhoneNumberId` is updated to the passed value.
schema:
$ref: '#/definitions/user'
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.
type: string
'409':
$ref: '#/responses/409PreferredConflict'
'422':
$ref: '#/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:users`* : A link to the collection of all users.
* *`apiture:createUser`* : A link to create a new user (via `POST`)
operationId: getApi
x-apiture-implemented: true
responses:
'200':
description: OK
schema:
$ref: '#/definitions/root'
tags:
- API
security:
- apiKey: []
parameters: []
/apiDoc:
get:
summary: Return API definition document
description: Return the OpenAPI document that describes this API.
operationId: getApiDoc
produces:
- application/json
- application/openapi+json;version=2.0
- application/openapi+yaml;version=2.0
responses:
'200':
description: OK
schema:
type: object
tags:
- API
security:
- apiKey: []
parameters: []
/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
type: string
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).
responses:
'200':
description: OK
schema:
$ref: '#/definitions/labelGroups'
tags:
- API
/users:
get:
summary: Return a collection of users
description: >-
Use this endpoint 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 collecton pagination links. Each
resource in the `_embedded.items` array is a summary representation of a user; use the `getUser` opertion 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.'
type: integer
format: int64
default: 0
- name: limit
in: query
description: The maximum number of user representations to return in this page.
type: integer
format: int32
default: 100
- name: sortBy
in: query
type: string
description: 'Optional sort criteria. See [sort criteria format](https://developer.apiture.com/docs/concepts/sorting), such as `?sortBy=field1,-field2`.'
- $ref: '#/parameters/filterQueryParam'
- $ref: '#/parameters/qQueryParam'
- $ref: '#/parameters/stateQueryParam'
- $ref: '#/parameters/customerIdQueryParam'
- $ref: '#/parameters/occupationQueryParam'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/users'
'400':
$ref: '#/responses/400'
'422':
$ref: '#/responses/422'
post:
summary: Create a new user
operationId: createUser
security:
- apiKey: []
accessToken:
- profiles/write
tags:
- User
parameters:
- name: user
in: body
description: The data necessary to create a new user.
required: true
schema:
$ref: '#/definitions/createUser'
responses:
'201':
description: Created
schema:
$ref: '#/definitions/user'
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`
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.
type: string
'202':
description: Accepted
schema:
$ref: '#/definitions/user'
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`
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.
type: string
'/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: '#/parameters/userIdPathParam'
- $ref: '#/parameters/ifNoneMatchHeaderParam'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/user'
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.
type: string
'302':
$ref: '#/responses/302UserMerged'
'404':
$ref: '#/responses/404User'
put:
summary: Update this user
description: Perform a complete replacement of this user.
operationId: updateUser
security:
- apiKey: []
accessToken:
- profiles/write
x-apiture-implemented: true
tags:
- User
parameters:
- $ref: '#/parameters/userIdPathParam'
- name: user
in: body
required: true
schema:
$ref: '#/definitions/user'
- $ref: '#/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/user'
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.
type: string
'400':
$ref: '#/responses/400'
'404':
$ref: '#/responses/404User'
'409':
$ref: '#/responses/409UserConflict'
'412':
$ref: '#/responses/412'
'422':
$ref: '#/responses/422'
patch:
summary: Update this user
description: Perform a partial update of this user. Fields which are omitted are not updated.
operationId: patchUser
security:
- apiKey: []
accessToken:
- profiles/write
x-apiture-implemented: true
tags:
- User
parameters:
- $ref: '#/parameters/userIdPathParam'
- name: user
in: body
required: true
schema:
$ref: '#/definitions/user'
- $ref: '#/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/user'
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.
type: string
'400':
$ref: '#/responses/400'
'404':
$ref: '#/responses/404User'
'409':
$ref: '#/responses/409UserConflict'
'412':
$ref: '#/responses/412'
'422':
$ref: '#/responses/422'
/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.
type: string
in: query
required: false
- $ref: '#/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/user'
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.
type: string
'400':
description: Bad Request. The `user` was malformed or does not refer to a user.
'409':
$ref: '#/responses/409UserConflict'
'412':
$ref: '#/responses/412'
'422':
$ref: '#/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.
type: string
in: query
required: false
- $ref: '#/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/user'
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.
type: string
'400':
description: Bad Request. The `user` was malformed or does not refer to a user.
'409':
$ref: '#/responses/409UserConflict'
'412':
$ref: '#/responses/412'
'422':
$ref: '#/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.
type: string
in: query
required: false
- $ref: '#/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/user'
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.
type: string
'400':
description: Bad Request. The `user` was malformed or does not refer to a user.
'409':
$ref: '#/responses/409UserConflict'
'412':
$ref: '#/responses/412'
'422':
$ref: '#/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.
type: string
in: query
required: false
- $ref: '#/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/user'
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.
type: string
'400':
description: Bad Request. The `user` was malformed or does not refer to a user.
'409':
$ref: '#/responses/409UserConflict'
'412':
$ref: '#/responses/412'
'422':
$ref: '#/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.
type: string
in: query
required: false
- $ref: '#/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/user'
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.
type: string
'400':
description: Bad Request. The `user` was malformed or does not refer to a user.
'409':
$ref: '#/responses/409UserConflict'
'412':
$ref: '#/responses/412'
'422':
$ref: '#/responses/422'
/mergedUsers:
post:
summary: Merge a set of users
tags:
- User Actions
description: |-
Merge a collection of users from an active, inactive or locked state
into the user specified via the `apiture:master` link.
This operation is invoked from the `apiture:merge` link on a user
resource when that user is eligible to be merged.
This changes the `state` to `merged`.
operationId: mergeUsers
security:
- apiKey: []
accessToken:
- profiles/write
parameters:
- name: users
in: body
description: The data necessary to merge users.
required: true
schema:
$ref: '#/definitions/mergeUsers'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/user'
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.
type: string
'409':
$ref: '#/responses/409UserConflict'
'412':
$ref: '#/responses/412'
'422':
$ref: '#/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: '#/parameters/userIdPathParam'
- $ref: '#/parameters/ifNoneMatchHeaderParam'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/constraints'
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.
type: string
'404':
$ref: '#/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: '#/parameters/userIdPathParam'
- name: constraints
in: body
required: true
schema:
$ref: '#/definitions/updateConstraints'
- $ref: '#/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/constraints'
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.
type: string
'404':
$ref: '#/responses/404User'
'412':
$ref: '#/responses/412'
'422':
$ref: '#/responses/422'
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: '#/parameters/userIdPathParam'
- name: constraints
in: body
required: true
schema:
$ref: '#/definitions/updateConstraints'
- $ref: '#/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/constraints'
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.
type: string
'404':
$ref: '#/responses/404User'
'412':
$ref: '#/responses/412'
'422':
$ref: '#/responses/422'
/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
parameters:
- name: start
in: query
description: The zero-based index of the first configuration group item to include in this page. The default 0 denotes the beginning of the collection.
type: integer
format: int64
default: 0
- name: limit
in: query
description: The maximum number of configuration group representations to return in this page.
type: integer
format: int32
default: 100
- name: sortBy
in: query
type: string
description: 'Optional sort criteria. See [sort criteria format](https://developer.apiture.com/docs/concepts/sorting), such as `?sortBy=field1,-field2`.'
- $ref: '#/parameters/filterQueryParam'
- $ref: '#/parameters/qQueryParam'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/configurationGroups'
'400':
$ref: '#/responses/400'
'422':
$ref: '#/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: '#/parameters/configurationGroupNamePathParam'
- $ref: '#/parameters/ifNoneMatchHeaderParam'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/configurationGroup'
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.
type: string
'304':
$ref: '#/responses/304'
'404':
$ref: '#/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: '#/parameters/configurationGroupNamePathParam'
- $ref: '#/parameters/ifNoneMatchHeaderParam'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/configurationSchema'
headers:
ETag:
description: The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`*
type: string
'304':
$ref: '#/responses/304'
'404':
$ref: '#/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: '#/parameters/configurationGroupNamePathParam'
- $ref: '#/parameters/ifNoneMatchHeaderParam'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/configurationValues'
headers:
ETag:
description: The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`*
type: string
'304':
$ref: '#/responses/304'
'404':
$ref: '#/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: '#/parameters/configurationGroupNamePathParam'
- name: configuration group values
in: body
required: true
schema:
$ref: '#/definitions/configurationValues'
- $ref: '#/parameters/ifMatchHeaderParam'
responses:
'200':
description: OK
schema:
$ref: '#/definitions/configurationSchema'
headers:
ETag:
description: The `ETag` response header specifies an entity tag which may be provided in an `If-Match` request header for *`PUT`*
type: string
'400':
$ref: '#/responses/400'
'403':
description: |-
Access denied. Only user allowed to update configurations is an admin.
This error response may have one of the following `type` values:
* [`configurationAccessDenied`](#err-configurationAccessDenied)
schema:
$ref: '#/definitions/errorResponse'
x-apiture-errors:
- configurationAccessDenied
'404':
$ref: '#/responses/404ConfigurationGroup'
'412':
$ref: '#/responses/412'
'/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: '#/parameters/configurationGroupNamePathParam'
- $ref: '#/parameters/configurationGroupValueNamePathParam'
responses:
'200':
description: 'OK. The value of the named configuration value as a JSON string, number, boolean, array, or object.'
schema:
type: string
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.
type: string
'404':
$ref: '#/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: '#/parameters/configurationGroupNamePathParam'
- $ref: '#/parameters/configurationGroupValueNamePathParam'
- name: value
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.
in: body
required: true
schema:
type: string
responses:
'200':
description: OK
schema:
type: string
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.
type: string
'403':
description: |-
Access denied. Only user allowed to update configurations is an admin.
This error response may have one of the following `type` values:
* [`configurationAccessDenied`](#err-configurationAccessDenied)
schema:
$ref: '#/definitions/errorResponse'
x-apiture-errors:
- configurationAccessDenied
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
type: string
required: false
phoneNumberIdPathParam:
name: phoneNumberId
description: The unique identifier of this phone number. This is an opaque string.
in: path
type: string
required: true
filterQueryParam:
name: filter
in: query
description: 'Optional filter criteria. See [filtering](https://developer.apiture.com/docs/concepts/filtering).'
type: string
qQueryParam:
name: q
in: query
description: 'Optional search string. See [searching](https://developer.apiture.com/docs/concepts/searching).'
type: string
emailAddressIdPathParam:
name: emailAddressId
description: The unique identifier of this email address. This is an opaque string.
in: path
type: string
required: true
addressIdPathParam:
name: addressId
description: The unique identifier of this address. This is an opaque string.
in: path
type: string
required: true
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
type: string
ifNoneMatchHeaderParam:
name: If-None-Match
description: >-
The entity tag that was returned in the `ETag` response. If the resource's current entity tag matches, the `GET` will return 304 (Not Modified)
and no response body, else the resource representation will be returned.
in: header
type: string
userIdPathParam:
name: userId
description: The unique identifier of the user. This is an opaque string.
in: path
type: string
required: true
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).
type: string
enum:
- locked
- frozen
- merged
- 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).
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).
type: string
configurationGroupNamePathParam:
name: groupName
description: The unique name of this configuration group.
in: path
type: string
required: true
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
type: string
required: 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.
schema:
$ref: '#/definitions/errorResponse'
'412':
description: >-
Precondition Failed. The supplied `If-Match` header value does not match the most recent `ETag` response header value. The resource has changed
in the interim.
This error response may have one of the following `type` values:
* [`invalidAddressType`](#err-invalidAddressType)
* [`invalidPhoneType`](#err-invalidPhoneType)
* [`cannotChangeId`](#err-cannotChangeId)
schema:
$ref: '#/definitions/errorResponse'
x-apiture-errors:
- invalidAddressType
- invalidPhoneType
- cannotChangeId
'422':
description: >-
Unprocessable Entity. One or more of the query parameters was well formed but otherwise invalid. The `_error` field in the response will contain
details about the request error.
schema:
$ref: '#/definitions/errorResponse'
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.
schema:
$ref: '#/definitions/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.
schema:
$ref: '#/definitions/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.
schema:
$ref: '#/definitions/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.
schema:
$ref: '#/definitions/challengeErrorResponse'
409AddressConflict:
description: Conflict. The selected address cannot be deleted because it is currently the user's preferred address.
schema:
$ref: '#/definitions/errorResponse'
409EmailAddressConflict:
description: Conflict. The selected email address cannot be deleted because it is currently the user's preferred email address.
schema:
$ref: '#/definitions/errorResponse'
409PhoneNumberConflict:
description: Conflict. The selected phone number cannot be deleted because it is currently the user's preferred phone number.
schema:
$ref: '#/definitions/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)
schema:
$ref: '#/definitions/challengeErrorResponse'
x-apiture-errors:
- itemStillPending
- missingApitureChallengeHeader
- challengedNotVerified
- challengedExpired
- challengedAlreadyRedeemed
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)
schema:
$ref: '#/definitions/errorResponse'
x-apiture-errors:
- noSuchProfileValue
- noSuchChallenge
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.
schema:
$ref: '#/definitions/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.
schema:
$ref: '#/definitions/errorResponse'
302UserMerged:
description: Redirect. The specified user has a state of `merged` and will be redirected to the master user resource.
schema:
$ref: '#/definitions/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` of a `merged` 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)
* [`mergeUserDoesNotExist`](#err-mergeUserDoesNotExist)
schema:
$ref: '#/definitions/errorResponse'
x-apiture-errors:
- updateUserError
- duplicateUsername
- duplicateTaxId
- cannotUpdateState
- invalidStateChange
- mergeUserDoesNotExist
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)
schema:
$ref: '#/definitions/errorResponse'
x-apiture-errors:
- invalidUserId
definitions:
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: '#/definitions/address'
- properties:
- state
- $ref: '#/definitions/abstractResource'
properties:
type:
description: The type of this address.
allOf:
- $ref: '#/definitions/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
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}$'
_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.'
$ref: '#/definitions/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](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: '#/definitions/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: '#/definitions/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:
- _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:
- properties:
- items
- $ref: '#/definitions/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.'
$ref: '#/definitions/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](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: '#/definitions/error'
items:
description: An array containing address items.
type: array
items:
$ref: '#/definitions/userAddress'
type: object
x-apiture-flattened: true
userEmailAddress:
title: Email Address (v1.0.0)
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-links:
- rel: delete
operationId: deleteEmailAddress
- rel: 'apiture:setAsPreferred'
operationId: setPreferredEmailAddress
example:
_id: pe1
_profile: 'https://api.apiture.com/schemas/users/userEmailAddress/v1.0.0/profile.json'
type: personal
number: 555-555-5555
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-version: 1.0.0
x-apiture-composition:
- $ref: '#/definitions/typedEmailAddress'
- properties:
- state
- $ref: '#/definitions/abstractResource'
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: '#/definitions/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}$'
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
$ref: '#/definitions/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](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: '#/definitions/error'
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: '#/definitions/profileItemState'
type: object
x-apiture-flattened: true
preferredResource:
title: Preferred Resource (v1.0.0)
description: >-
The `_id` of an address, email address, or phone number resource to set as the user's preferred item. The `_id` is represented as a JSON string.
(Note: the value *must* be quoted.)
type: string
minLength: 1
maxLength: 4
example: pe0
x-apiture-version: 1.0.0
x-apiture-flattened: true
userEmailAddresses:
title: The user's email addresses (v1.0.0)
description: The list of the user's email addresses.
example:
_profile: 'https://api.apiture.com/schemas/users/userEmailAddresses/v1.0.0/profile.json'
items:
- _id: pe0
type: personal
label: Personal
number: user7838@example.com
state: approved
_profile: 'https://api.apiture.com/schemas/users/userEmailAddress/v1.0.0/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.0/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-version: 1.0.0
x-apiture-composition:
- properties:
- items
- $ref: '#/definitions/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.'
$ref: '#/definitions/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](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: '#/definitions/error'
items:
description: An array containing email address items.
type: array
items:
$ref: '#/definitions/userEmailAddress'
type: object
x-apiture-flattened: true
userPhoneNumber:
title: Phone Number (v1.0.0)
description: >
Representation of phone number resources.
Links
Response and request bodies using this userPhoneNumber
schema may contain
the following links:
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.0/profile.json'
type: home
number: 555-555-5555
state: approved
_links:
self:
href: /users/users/9b0387db-8705-469a-852c-ead8bfd872ba/phoneNumbers/hp1
x-apiture-version: 1.0.0
x-apiture-composition:
- $ref: '#/definitions/phoneNumber'
- properties:
- state
- $ref: '#/definitions/abstractResource'
properties:
type:
description: The type or role of this phone number.
allOf:
- $ref: '#/definitions/phoneNumberType'
number:
description: 'The phone number, as a string.'
type: string
example: 555-555-5555
minLength: 8
maxLength: 16
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.'
$ref: '#/definitions/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](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: '#/definitions/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: '#/definitions/profileItemState'
type: object
x-apiture-flattened: true
userPhoneNumbers:
title: The user's phone numbers (v1.0.0)
description: The list of the user's phone numbers.
example:
_profile: 'https://api.apiture.com/schemas/users/userPhoneNumbers/v1.0.0/profile.json'
items:
- _id: mp0
type: mobile
label: Mobile
number: 555-555-5555
state: approved
_profile: 'https://api.apiture.com/schemas/users/userPhoneNumber/v1.0.0/profile.json'
_links:
self:
href: /users/users/9b0387db-8705-469a-852c-ead8bfd872ba/phoneNumbers/mp0
- _id: mp2
type: home
label: Home
number: 555-444-4444
state: approved
_profile: 'https://api.apiture.com/schemas/users/userPhoneNumber/v1.0.0/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-version: 1.0.0
x-apiture-composition:
- properties:
- items
- $ref: '#/definitions/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.'
$ref: '#/definitions/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](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: '#/definitions/error'
items:
description: An array containing phone number items.
type: array
items:
$ref: '#/definitions/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.0.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
properties:
kycAnswers:
description: This user's answers Know Your Customer (KYC) questions.
x-apiture-pii: true
readOnly: true
allOf:
- $ref: '#/definitions/kycAnswers'
identityVerification:
description: >-
The identity verification data for this person. These fields are derived from the results of any identity verification processes executed
against the personally identifiable information (PII) contained in this record.
type: object
readOnly: true
allOf:
- $ref: '#/definitions/identityVerification'
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: '#/definitions/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: '#/definitions/foreignPoliticalFigureAssociation'
x-apiture-version: 1.0.0
type: object
x-apiture-flattened: true
foreignPoliticalFigureAssociation:
title: foreign Political Figure Association (v1.0.0)
description: >
The type of association to a foreign political figure. This eumeration 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) values
(described by the named foreignPoliticalFigureAssociation)
Value | Description |
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.
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 |
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.0.0)
description: 'Data points on the identity verification process that tells if a user has passed, failed or expired the identity check.'
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
x-apiture-version: 1.0.0
type: object
x-apiture-flattened: true
userFields:
title: Common fields of a user (v1.0.0)
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
type: object
example:
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
phones:
- _id: hp0
type: home
number: (555) 555-5555
- _id: mp0
type: mobile
number: (999) 555-5555
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: US
state: active
attributes: {}
preferredContactMethod: email
x-apiture-version: 1.0.0
x-apiture-composition:
- $ref: '#/definitions/identifiedContact'
- $ref: '#/definitions/contactName'
- $ref: '#/definitions/simpleContactFields'
- $ref: '#/definitions/userVerificationFields'
- properties:
- username
- state
- addresses
- 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:
type: object
$ref: '#/definitions/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: '#/definitions/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: '#/definitions/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: '#/definitions/identification'
preferredContactMethod:
description: The contact's preferred method of communication.
allOf:
- $ref: '#/definitions/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: '#/definitions/citizenship'
residencyStatus:
description: This individual's residency status.
allOf:
- $ref: '#/definitions/residencyStatus'
occupation:
description: The occupation of this individual.
allOf:
- $ref: '#/definitions/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: '#/definitions/yearsAtAddress'
kycAnswers:
description: This user's answers Know Your Customer (KYC) questions.
x-apiture-pii: true
readOnly: true
allOf:
- $ref: '#/definitions/kycAnswers'
identityVerification:
description: >-
The identity verification data for this person. These fields are derived from the results of any identity verification processes executed
against the personally identifiable information (PII) contained in this record.
type: object
readOnly: true
allOf:
- $ref: '#/definitions/identityVerification'
username:
description: The unique username for the user.
type: string
state:
description: |
The state of this user record. The default is `active`.
* Users may not be deleted, but Users with a `state` of `active`, `inactive` or `locked`
may be removed by `POST`ing to the `/removedUsers` endpoint via the `apiture:remove`
endpoint. Removed users may not be reactivated.
* Users with a `state` of `active` or `locked` may be deactivated by `POST`ing to
the `/inactiveUsers` endpoint via the `apiture:deactivate` endpoint.
* Users with a `state` of `inactive` or `locked` may be activated by `POST`ing to
the `/activeUsers` endpoint via the `apiture:activate` endpoint.
* Users with a `state` of `active` or `inactive` may be locked by `POST`ing to
the `/lockedUsers` endpoint via the `apiture:lock` endpoint. A `state` of `locked`
indicates a user has entered the password incorrectly too many times.
* Users with a `state` of `active`, `inactive` or locked may be frozen by
`POST`ing to the `/frozenUsers` endpoint via the `apiture:freeze` endpoint.
A `state` of `frozen` indicates a user can no longer access online banking until
the financial institution re-activates the user.
* Users with a `state` of `active`, `inactive`, or `locked` may be
merged by `POST`ing to the `/mergedUsers` endpoint via the `apiture:merge` endpoint.
Merged users may not have their state changed.
state
strings may have one of the following
[enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations) values
(described by the named userState)
Value | Description |
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.
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. |
merged | merged: The user has been merged with another one. Merged users may not have their state changed. |
removed | removed: The user has been removed can not be reactivated, for example an old user account not being used anymore. |
type: string
enum:
- active
- inactive
- locked
- frozen
- merged
- removed
x-apiture-enum: userState
phoneNumbers:
description: An array of phone numbers. Add or delete phoneNumbers with the `createPhoneNumber` and `deletePhoneNumber` operations.
type: array
items:
$ref: '#/definitions/userPhoneNumber'
readOnly: true
x-apiture-flattened: true
createUser:
title: Create User (v1.0.0)
description: Representation used to create a new user.
required:
- username
- firstName
- lastName
- birthdate
- identification
x-apiture-version: 1.0.0
x-apiture-composition:
- $ref: '#/definitions/abstractResource'
- $ref: '#/definitions/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.'
$ref: '#/definitions/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](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: '#/definitions/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:
type: object
$ref: '#/definitions/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: '#/definitions/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: '#/definitions/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: '#/definitions/identification'
preferredContactMethod:
description: The contact's preferred method of communication.
allOf:
- $ref: '#/definitions/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: '#/definitions/citizenship'
residencyStatus:
description: This individual's residency status.
allOf:
- $ref: '#/definitions/residencyStatus'
occupation:
description: The occupation of this individual.
allOf:
- $ref: '#/definitions/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: '#/definitions/yearsAtAddress'
kycAnswers:
description: This user's answers Know Your Customer (KYC) questions.
x-apiture-pii: true
readOnly: true
allOf:
- $ref: '#/definitions/kycAnswers'
identityVerification:
description: >-
The identity verification data for this person. These fields are derived from the results of any identity verification processes executed
against the personally identifiable information (PII) contained in this record.
type: object
readOnly: true
allOf:
- $ref: '#/definitions/identityVerification'
username:
description: The unique username for the user.
type: string
state:
description: |
The state of this user record. The default is `active`.
* Users may not be deleted, but Users with a `state` of `active`, `inactive` or `locked`
may be removed by `POST`ing to the `/removedUsers` endpoint via the `apiture:remove`
endpoint. Removed users may not be reactivated.
* Users with a `state` of `active` or `locked` may be deactivated by `POST`ing to
the `/inactiveUsers` endpoint via the `apiture:deactivate` endpoint.
* Users with a `state` of `inactive` or `locked` may be activated by `POST`ing to
the `/activeUsers` endpoint via the `apiture:activate` endpoint.
* Users with a `state` of `active` or `inactive` may be locked by `POST`ing to
the `/lockedUsers` endpoint via the `apiture:lock` endpoint. A `state` of `locked`
indicates a user has entered the password incorrectly too many times.
* Users with a `state` of `active`, `inactive` or locked may be frozen by
`POST`ing to the `/frozenUsers` endpoint via the `apiture:freeze` endpoint.
A `state` of `frozen` indicates a user can no longer access online banking until
the financial institution re-activates the user.
* Users with a `state` of `active`, `inactive`, or `locked` may be
merged by `POST`ing to the `/mergedUsers` endpoint via the `apiture:merge` endpoint.
Merged users may not have their state changed.
state
strings may have one of the following
[enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations) values
(described by the named userState)
Value | Description |
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.
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. |
merged | merged: The user has been merged with another one. Merged users may not have their state changed. |
removed | removed: The user has been removed can not be reactivated, for example an old user account not being used anymore. |
type: string
enum:
- active
- inactive
- locked
- frozen
- merged
- removed
x-apiture-enum: userState
phoneNumbers:
description: An array of phone numbers. Add or delete phoneNumbers with the `createPhoneNumber` and `deletePhoneNumber` operations.
type: array
items:
$ref: '#/definitions/userPhoneNumber'
readOnly: true
type: object
x-apiture-flattened: true
summaryUser:
title: Summary User (v1.0.0)
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.0.0
x-apiture-composition:
- properties:
- _id
- customerId
- $ref: '#/definitions/userFields'
- $ref: '#/definitions/abstractResource'
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:
type: object
$ref: '#/definitions/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: '#/definitions/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: '#/definitions/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: '#/definitions/identification'
preferredContactMethod:
description: The contact's preferred method of communication.
allOf:
- $ref: '#/definitions/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: '#/definitions/citizenship'
residencyStatus:
description: This individual's residency status.
allOf:
- $ref: '#/definitions/residencyStatus'
occupation:
description: The occupation of this individual.
allOf:
- $ref: '#/definitions/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: '#/definitions/yearsAtAddress'
kycAnswers:
description: This user's answers Know Your Customer (KYC) questions.
x-apiture-pii: true
readOnly: true
allOf:
- $ref: '#/definitions/kycAnswers'
identityVerification:
description: >-
The identity verification data for this person. These fields are derived from the results of any identity verification processes executed
against the personally identifiable information (PII) contained in this record.
type: object
readOnly: true
allOf:
- $ref: '#/definitions/identityVerification'
username:
description: The unique username for the user.
type: string
state:
description: |
The state of this user record. The default is `active`.
* Users may not be deleted, but Users with a `state` of `active`, `inactive` or `locked`
may be removed by `POST`ing to the `/removedUsers` endpoint via the `apiture:remove`
endpoint. Removed users may not be reactivated.
* Users with a `state` of `active` or `locked` may be deactivated by `POST`ing to
the `/inactiveUsers` endpoint via the `apiture:deactivate` endpoint.
* Users with a `state` of `inactive` or `locked` may be activated by `POST`ing to
the `/activeUsers` endpoint via the `apiture:activate` endpoint.
* Users with a `state` of `active` or `inactive` may be locked by `POST`ing to
the `/lockedUsers` endpoint via the `apiture:lock` endpoint. A `state` of `locked`
indicates a user has entered the password incorrectly too many times.
* Users with a `state` of `active`, `inactive` or locked may be frozen by
`POST`ing to the `/frozenUsers` endpoint via the `apiture:freeze` endpoint.
A `state` of `frozen` indicates a user can no longer access online banking until
the financial institution re-activates the user.
* Users with a `state` of `active`, `inactive`, or `locked` may be
merged by `POST`ing to the `/mergedUsers` endpoint via the `apiture:merge` endpoint.
Merged users may not have their state changed.
state
strings may have one of the following
[enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations) values
(described by the named userState)
Value | Description |
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.
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. |
merged | merged: The user has been merged with another one. Merged users may not have their state changed. |
removed | removed: The user has been removed can not be reactivated, for example an old user account not being used anymore. |
type: string
enum:
- active
- inactive
- locked
- frozen
- merged
- removed
x-apiture-enum: userState
phoneNumbers:
description: An array of phone numbers. Add or delete phoneNumbers with the `createPhoneNumber` and `deletePhoneNumber` operations.
type: array
items:
$ref: '#/definitions/userPhoneNumber'
readOnly: true
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
$ref: '#/definitions/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](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: '#/definitions/error'
_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
mergeUsers:
title: Merge Users (v1.0.0)
description: Representation used to merge a set of users into a master user.
example:
_links:
'apiture:master':
href: /users/users/5150d4f2-0d94-4602-8ca8-f68d00815f63
items:
- _id: 9604e5f8-da29-4197-b6fb-60a1cfecfba8
_profile: 'https://api.apiture.com/schemas/users/user/v1.0.0/profile.json'
_links:
self:
href: /users/users/9604e5f8-da29-4197-b6fb-60a1cfecfba8
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
phones:
- _id: hp0
type: home
number: (555) 555-5555
- _id: mp0
type: mobile
number: (999) 555-5555
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: US
state: active
- _id: d1fabf13-31d1-4351-89ad-877ac4d1220a
_profile: 'https://api.apiture.com/schemas/users/user/v1.0.0/profile.json'
_links:
self:
href: /users/users/d1fabf13-31d1-4351-89ad-877ac4d1220a
username: LAS15
firstName: Johnathan
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
phones:
- _id: hp0
type: home
number: (555) 555-5555
- _id: mp0
type: mobile
number: (999) 555-5555
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: US
state: active
x-apiture-version: 1.0.0
x-apiture-composition:
- properties:
- items
- _links
properties:
items:
type: array
description: Array of users to merge.
items:
$ref: '#/definitions/user'
_links:
$ref: '#/definitions/links'
type: object
x-apiture-flattened: true
user:
title: User (v1.0.0)
description: |-
Representation of a user resource. A user may have the following links:
* *`self`*: A link to the user resource.
* *`apiture:remove`*: A link to remove the current user (via `POST`). This
link only exists if the user resource is not `removed` and if the caller is authorized to remove users.
* *`apiture:activate`*: A link to activate the current user (via `POST`). This
link only exists if the user resource is `inactive`, `locked`, or `frozen` and the caller is authorized to activate users.
* *`apiture:deactivate`*: A link to deactivate the current user (via `POST`). This
link only exists if the user resource is `active` or `locked` and the caller is authorized to deactivate users.
* *`apiture:lock`*: A link to lock the current user (via `POST`). This
link only exists if the user resource is `active` or `inactive` and the caller is authorized to lock users.
* *`apiture:freeze`*: A link to freeze the current user (via `POST`). This
link only exists if the user resource is `active` , `inactive` or `locked` and the caller is authorized to freeze users.
* *`apiture:merge`*: A link to merge the current user (or a collection of users) with a specified master user (via `POST`). This
link only exists if the user resource is `active`, `inactive`, or `locked` and the caller is authorized to merge users.
example:
_id: 9604e5f8-da29-4197-b6fb-60a1cfecfba8
_profile: 'https://api.apiture.com/schemas/users/user/v1.0.0/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
customerId: 00047294723672
phones:
- _id: hp0
type: home
number: (555) 555-5555
- _id: mp0
type: mobile
number: (999) 555-5555
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
state: active
preferences:
smsNotifications: true
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-version: 1.0.0
x-apiture-composition:
- $ref: '#/definitions/summaryUser'
- properties:
- createdAt
- lastContactedAt
- lastLoggedInAt
- preferences
- attributes
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:
type: object
$ref: '#/definitions/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: '#/definitions/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: '#/definitions/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: '#/definitions/identification'
preferredContactMethod:
description: The contact's preferred method of communication.
allOf:
- $ref: '#/definitions/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: '#/definitions/citizenship'
residencyStatus:
description: This individual's residency status.
allOf:
- $ref: '#/definitions/residencyStatus'
occupation:
description: The occupation of this individual.
allOf:
- $ref: '#/definitions/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: '#/definitions/yearsAtAddress'
kycAnswers:
description: This user's answers Know Your Customer (KYC) questions.
x-apiture-pii: true
readOnly: true
allOf:
- $ref: '#/definitions/kycAnswers'
identityVerification:
description: >-
The identity verification data for this person. These fields are derived from the results of any identity verification processes executed
against the personally identifiable information (PII) contained in this record.
type: object
readOnly: true
allOf:
- $ref: '#/definitions/identityVerification'
username:
description: The unique username for the user.
type: string
state:
description: |
The state of this user record. The default is `active`.
* Users may not be deleted, but Users with a `state` of `active`, `inactive` or `locked`
may be removed by `POST`ing to the `/removedUsers` endpoint via the `apiture:remove`
endpoint. Removed users may not be reactivated.
* Users with a `state` of `active` or `locked` may be deactivated by `POST`ing to
the `/inactiveUsers` endpoint via the `apiture:deactivate` endpoint.
* Users with a `state` of `inactive` or `locked` may be activated by `POST`ing to
the `/activeUsers` endpoint via the `apiture:activate` endpoint.
* Users with a `state` of `active` or `inactive` may be locked by `POST`ing to
the `/lockedUsers` endpoint via the `apiture:lock` endpoint. A `state` of `locked`
indicates a user has entered the password incorrectly too many times.
* Users with a `state` of `active`, `inactive` or locked may be frozen by
`POST`ing to the `/frozenUsers` endpoint via the `apiture:freeze` endpoint.
A `state` of `frozen` indicates a user can no longer access online banking until
the financial institution re-activates the user.
* Users with a `state` of `active`, `inactive`, or `locked` may be
merged by `POST`ing to the `/mergedUsers` endpoint via the `apiture:merge` endpoint.
Merged users may not have their state changed.
state
strings may have one of the following
[enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations) values
(described by the named userState)
Value | Description |
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.
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. |
merged | merged: The user has been merged with another one. Merged users may not have their state changed. |
removed | removed: The user has been removed can not be reactivated, for example an old user account not being used anymore. |
type: string
enum:
- active
- inactive
- locked
- frozen
- merged
- removed
x-apiture-enum: userState
phoneNumbers:
description: An array of phone numbers. Add or delete phoneNumbers with the `createPhoneNumber` and `deletePhoneNumber` operations.
type: array
items:
$ref: '#/definitions/userPhoneNumber'
readOnly: true
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
$ref: '#/definitions/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](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: '#/definitions/error'
_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: '#/definitions/userPreferences'
attributes:
description: Additional unstructured application metadata about the user.
allOf:
- $ref: '#/definitions/attributes'
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 mult-factor authentication if
`smsNotifications` is `false`.
type: boolean
default: true
additionalProperties:
$ref: '#/definitions/attributeValue'
x-apiture-version: 1.0.0
x-apiture-flattened: true
users:
title: Users collection (v1.0.0)
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`).
example:
_profile: 'https://api.apiture.com/schemas/users/users/v1.0.0/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:
- _id: 9604e5f8-da29-4197-b6fb-60a1cfecfba8
_profile: 'https://api.apiture.com/schemas/users/user/v1.0.0/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
'apiture:merge':
href: /users/mergedUsers
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: (555) 555-5555
- _id: mp0
type: mobile
number: (999) 555-5555
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
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/user/v1.0.0/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
'apiture:merge':
href: /users/mergedUsers
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: (555) 555-5555
- _id: mp0
type: mobile
number: (999) 555-5555
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
lastContactedAt: '2018-07-29T11:13:54Z'
lastLoggedInAt: '2017-12-29T15:19:41Z'
state: active
createdAt: '2018-07-29T11:13:54Z'
x-apiture-version: 1.0.0
x-apiture-composition:
- $ref: '#/definitions/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.'
$ref: '#/definitions/links'
_embedded:
type: object
description: Embedded objects.
properties:
items:
type: array
items:
$ref: '#/definitions/summaryUser'
_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: '#/definitions/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: '#/definitions/abstractResource'
- $ref: '#/definitions/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.'
$ref: '#/definitions/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](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: '#/definitions/error'
transfers:
description: Constraints on the user's money transfers.
allOf:
- $ref: '#/definitions/transferConstraints'
checkDeposits:
description: Constraints on the user's remote check deposits.
allOf:
- $ref: '#/definitions/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: '#/definitions/transferConstraints'
checkDeposits:
description: Constraints on the user's remote check deposits.
allOf:
- $ref: '#/definitions/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
description: 'A HAL response, with hypermedia `_links` for the top-level resources and operations in API.'
example:
id: apiName
name: API name
apiVersion: 1.0.0
_profile: 'https://production.api.apiture.com/schemas/common/root/v2.0.0/profile.json'
_links: {}
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/root/v2.0.0/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/definitions/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.'
$ref: '#/definitions/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](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: '#/definitions/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
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)`.
example:
_profile: 'https://production.api.apiture.com/schemas/common/labelGroups/v1.0.0/model.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.0/model.json'
x-apiture-namespace: common
x-apiture-version: 1.0.0
x-apiture-composition:
- $ref: '#/definitions/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.'
$ref: '#/definitions/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](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: '#/definitions/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: '#/definitions/labelGroup'
type: object
x-apiture-flattened: true
configurationGroups:
x-apiture-version: 2.0.0
title: Configuration Group Collection
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`).
example:
_profile: 'https://production.api.apiture.com/schemas/configurations/configurationGroups/v2.0.0/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:
- _profile: 'https://api.apiture.com/schemas/configurations/configurationGroup/v2.0.0/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.0/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.0/model.json'
x-apiture-namespace: configurations
x-apiture-composition:
- $ref: '#/definitions/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.'
$ref: '#/definitions/links'
_embedded:
description: Embedded objects.
type: object
properties:
items:
description: An array containing a page of configuration group items.
type: array
items:
$ref: '#/definitions/configurationGroupSummary'
_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: '#/definitions/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.0
title: Configuration Group
description: Represents a configuration group.
example:
_profile: 'https://api.apiture.com/schemas/configurations/configurationGroup/v2.0.0/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.0/model.json'
x-apiture-namespace: configurations
x-apiture-composition:
- $ref: '#/definitions/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.'
$ref: '#/definitions/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](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: '#/definitions/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: '#/definitions/configurationSchema'
values:
$ref: '#/definitions/configurationValues'
type: object
x-apiture-flattened: true
configurationSchema:
x-apiture-version: 2.0.1
title: Configuration Schema
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).
type: object
additionalProperties:
$ref: '#/definitions/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
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.
type: object
additionalProperties:
$ref: '#/definitions/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
description: 'Describes an error response, typically returned on 4xx or 5xx errors from API operations. The `_error` object contains the error details.'
example:
_profile: 'https://api.apiture.com/schemas/common/errorResponse/v2.0.0/profile.json'
_error:
_id: 2eae46e1-575c-4d69-8a8f-0a7b0115a4b3
message: The value for deposit must be greater than 0.
statusCode: 422
type: positiveNumberRequired
attributes:
value: -125.5
remediation: Provide a value which is greater than 0
occurredAt: '2018-01-25T05:50:52.375Z'
_links:
describedby:
href: 'https://api.apiture.com/errors/positiveNumberRequired'
_embedded:
errors: []
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/errorResponse/v2.0.0/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/definitions/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.'
$ref: '#/definitions/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](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: '#/definitions/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`.
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: '#/definitions/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.'
$ref: '#/definitions/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](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: '#/definitions/challengeError'
type: object
x-apiture-flattened: true
address:
title: Address
description: A postal address.
type: object
required:
- type
properties:
type:
description: The type of this address.
allOf:
- $ref: '#/definitions/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
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}$'
_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}$'
example:
_id: ha5
type: home
addressLine1: 555 N Front Street
addressLine2: Suite 5555
city: Wilmington
regionCode: NC
postalCode: 28401-5405
countryCode: US
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/address/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-version: 1.0.0
x-apiture-flattened: true
abstractResource:
x-apiture-version: 2.0.0
title: Abstract Resource
description: >-
An abstract schema used to define other schemas for request and response bodies. This is a
[HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource representation. This model contains hypermedia `_links`, and either optional
domain object data with `_profile` and optional `_embedded` objects, or an `_error` object. In responses, if the operation was successful, this
object will not include the `_error`, but if the operation was a 4xx or 5xx error, this object will not include `_embedded` or any data fields,
only `_error` and optionally `_links`.
example:
_profile: '{uri of resource profile.json}'
_links:
self:
href: '{uri of current resource}'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/abstractResource/v2.0.0/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/definitions/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.'
$ref: '#/definitions/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](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: '#/definitions/error'
type: object
x-apiture-flattened: true
typedEmailAddress:
title: Email Address
description: An email address and the email address type.
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: '#/definitions/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-resolved-from: 'https://production.api.apiture.com/schemas/contacts/typedEmailAddress/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-version: 1.0.0
type: object
x-apiture-flattened: true
phoneNumber:
title: Phone Number
description: A phone number and its role.
type: object
required:
- type
- number
properties:
type:
description: The type or role of this phone number.
allOf:
- $ref: '#/definitions/phoneNumberType'
number:
description: 'The phone number, as a string.'
type: string
example: 555-555-5555
minLength: 8
maxLength: 16
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: 555-555-5555
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/phoneNumber/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-version: 1.0.0
x-apiture-flattened: true
employmentStatus:
title: Employment Status
description: |-
The employment status of a contact, located in `kycAnswers`.
**Warning**: the `enum` list will be removed in a future release.
and the values defined at runtime via the `employmentStatus`
label group in the response from the [`getLabels`](#op-getLabels) operation.
type: string
x-apiture-choice: employmentStatus
enum:
- unknown
- fullTime
- partTime
- paidLeave
- retired
- unemployed
- other
- notApplicable
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/employmentStatus/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-version: 1.0.0
x-apiture-flattened: true
identifiedContact:
title: Identified Contact
description: A contact with additional personally identifiable information data.
x-apiture-fragment: true
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/identifiedContact/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-version: 1.0.0
x-apiture-composition:
- $ref: '#/definitions/simpleContact'
- $ref: '#/definitions/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:
type: object
$ref: '#/definitions/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: '#/definitions/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: '#/definitions/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: '#/definitions/identification'
preferredContactMethod:
description: The contact's preferred method of communication.
allOf:
- $ref: '#/definitions/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: '#/definitions/citizenship'
residencyStatus:
description: This individual's residency status.
allOf:
- $ref: '#/definitions/residencyStatus'
occupation:
description: The occupation of this individual.
allOf:
- $ref: '#/definitions/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: '#/definitions/yearsAtAddress'
type: object
x-apiture-flattened: true
contactName:
title: Name
description: A person's name.
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-resolved-from: 'https://production.api.apiture.com/schemas/contacts/contactName/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-version: 1.0.0
type: object
x-apiture-flattened: true
simpleContactFields:
title: Simple Contact Fields
description: Additional properties for a person or contact.
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: '#/definitions/identification'
preferredContactMethod:
description: The contact's preferred method of communication.
allOf:
- $ref: '#/definitions/preferredContactMethod'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/simpleContactFields/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-version: 1.0.0
x-apiture-flattened: true
links:
title: Links
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
type: object
x-apiture-key: linkRelationName
additionalProperties:
$ref: '#/definitions/link'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/links/v1.0.0/model.json'
x-apiture-namespace: common
x-apiture-version: 1.0.0
properties: {}
x-apiture-flattened: true
attributes:
x-apiture-version: 2.0.0
title: Attributes
description: An optional map of name/value pairs which contains additional dynamic data about the resource.
type: object
x-apiture-key: attributeName
additionalProperties:
$ref: '#/definitions/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
attributeValue:
x-apiture-version: 2.0.0
title: Attribute Value
description: The data associated with this attribute.
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/attributeValue/v2.0.0/model.json'
x-apiture-namespace: common
type: object
properties: {}
x-apiture-flattened: true
collection:
x-apiture-version: 2.0.0
title: Collection
description: A collection of resources. This is an abstract model schema which is extended to define specific resource collections.
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/collection/v2.0.0/model.json'
x-apiture-namespace: common
x-apiture-composition:
- $ref: '#/definitions/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.'
$ref: '#/definitions/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](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: '#/definitions/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
emailType:
title: Email Type
description: |-
The kind of email address.
**Warning**: the `enum` list will be removed in a future release.
and the values defined at runtime via the `emailType`
label group in the response from the [`getLabels`](#op-getLabels) operation.
type: string
x-apiture-choice: emailType
enum:
- unknown
- personal
- work
- school
- other
- notApplicable
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/emailType/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-version: 1.0.0
x-apiture-flattened: true
labelGroup:
title: Label Group
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", ... }`.
x-apiture-key: labelName
additionalProperties:
$ref: '#/definitions/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
x-apiture-version: 1.0.0
type: object
properties: {}
x-apiture-flattened: true
challengeError:
title: Challenge Error (v1.0.0)
description: The operation error description with an embedded identity challenge.
type: object
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/challengeError/v1.0.0/model.json'
x-apiture-namespace: auth
x-apiture-composition:
- $ref: '#/definitions/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: '#/definitions/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: '#/definitions/error'
_links:
$ref: '#/definitions/links'
_embedded:
description: Embedded objects
type: object
properties:
challenge:
description: The details of the identity verification challenge.
allOf:
- $ref: '#/definitions/challenge'
x-apiture-flattened: true
configurationSchemaValue:
x-apiture-version: 2.0.0
title: Configuration Schema Value
description: The data associated with this configuration schema.
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
configurationGroupSummary:
x-apiture-version: 2.0.0
title: Configuration Group Summary
description: A summary of the data contained within a configuration group resource.
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: '#/definitions/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.'
$ref: '#/definitions/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](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: '#/definitions/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
description: The data associated with this configuration.
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
addressType:
title: Address Type
description: >-
The type of a postal address.
**Warning**: the `enum` list will be removed in a future release. and the values defined at runtime via the `addressType` label group in the
response from the [`getLabels`](#op-getLabels) operation.
type: string
x-apiture-choice: addressType
enum:
- unknown
- home
- prior
- work
- school
- mailing
- vacation
- shipping
- billing
- headquarters
- commercial
- site
- property
- other
- notApplicable
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/addressType/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-version: 1.0.0
x-apiture-flattened: true
phoneNumberType:
title: Phone Number Type
description: >-
The type or role of this phone number.
**Warning**: the `enum` list will be removed in a future release. and the values defined at runtime via the `phoneNumberType` label group in the
response from the [`getLabels`](#op-getLabels) operation.
type: string
x-apiture-choice: phoneNumberType
enum:
- unknown
- home
- work
- mobile
- fax
- other
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/phoneNumberType/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-version: 1.0.0
x-apiture-flattened: true
abstractRequest:
x-apiture-version: 2.0.0
title: Abstract Request
description: >-
An abstract schema used to define other request-only schemas. This is a [HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource
representation, minus the `_error` defined in `abstractResource`.
properties:
_links:
description: 'An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations.'
$ref: '#/definitions/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](https://developer.apiture.com/docs/concepts/profiles/) which describes the representation.'
type: string
format: uri
example:
_profile: '{uri of resource profile.json}'
_links:
self:
href: '{uri of current resource}'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/abstractRequest/v2.0.0/model.json'
x-apiture-namespace: common
type: object
x-apiture-flattened: true
error:
x-apiture-version: 2.0.0
title: Error
description: Describes an error in an API request or in a service called via the API.
required:
- message
properties:
message:
type: string
description: A localized message string describing the error condition.
_id:
description: >-
A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at
the source of the error). This is is an opaque string.
readOnly: true
type: string
statusCode:
description: The HTTP status code associate with this error.
type: integer
minimum: 100
maximum: 599
example: 422
type:
type: string
description: >-
An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to
render an appropriate message or hint. This provides a finer level of granularity than the `statusCode`. For example, instead of just 400
Bad Request, the `type` may be much more specific. such as `integerValueNotInAllowedRange` or `numericValueExceedsMaximum` or
`stringValueNotInAllowedSet`.
occurredAt:
type: string
format: date-time
description: 'An [RFC 3339](https://tools.ietf.org/html/rfc3339) UTC time stamp indicating when the error occurred.'
example: '2018-02-02T03:37:15.375Z'
attributes:
description: >-
Informative values or constraints which describe the error. For example, for a value out of range error, the attributes may specify the
`minimum` and `maximum` values. This allows clients to present error messages as they see fit (the API does not assume the
client/presentation tier). The set of attributes varies by error `type`.
allOf:
- $ref: '#/definitions/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: '#/definitions/error'
_links:
$ref: '#/definitions/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
identification:
title: Identification
description: Official identifying information associated with the contact.
type: object
required:
- type
- value
properties:
value:
description: 'The value of this form of identification (the tax ID as a string, for example)'
type: string
x-apiture-pii: true
type:
description: The type of this form of identification.
type: string
x-apiture-enum: 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: 111-11-1111
expiration: {}
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/identification/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-version: 1.0.0
x-apiture-flattened: true
preferredContactMethod:
title: Preferred Contact Method
description: The contact's preferred method of communication.
type: string
enum:
- unknown
- sms
- email
- other
- notApplicable
x-apiture-enum: preferredContactMethod
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/preferredContactMethod/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-version: 1.0.0
x-apiture-flattened: true
link:
x-apiture-version: 1.0.0
title: Link
description: >-
Describes a hypermedia link within a `_links` object in HAL representations. In Apiture APIs, links are [HAL
links](https://developer.apiture.com/docs/concepts/links), but Apiture APIs do not use the `name` or `hreflang` properties of HAL. Apiture links
_may_ include a `method` property.
required:
- href
properties:
href:
type: string
format: uri
description: The URI or URI template for the resource/operation this link refers to.
type:
type: string
description: The media type for the resource.
templated:
type: boolean
description: 'If true, the link''s href is a [URI template](https://tools.ietf.org/html/rfc6570).'
title:
type: string
description: An optional human-readable localized title for the link.
deprecation:
type: string
format: uri
description: 'If present, the containing link is deprecated and the value is a URI which provides human-readable text information about the deprecation.'
profile:
type: string
format: uri
description: 'The URI of a profile document, a JSON document which describes the target resource/operation.'
example:
href: /contacts/contacts/328f6bf6-d762-422f-a077-ab91ca4d0b6f
title: Applicant
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/common/link/v1.0.0/model.json'
x-apiture-namespace: common
type: object
x-apiture-flattened: true
simpleContact:
title: Simple Contact
description: >-
Basic contact and identification information for a person, consisting of the name, mailing address, phone numbers, email addresses, and
government identification.
example:
firstName: John
middleName: Daniel
lastName: Smith
preferredName: John
suffix: MD
identification:
- type: taxId
value: 111-11-1111
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: (555) 555-5555
- _id: mp1
type: mobile
number: (999) 555-5555
preferredPhoneId: hp1
preferredContactMethod: email
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/simpleContact/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-version: 1.0.0
x-apiture-composition:
- $ref: '#/definitions/contactName'
- $ref: '#/definitions/addresses'
- $ref: '#/definitions/emailAddresses'
- $ref: '#/definitions/phoneNumbers'
- $ref: '#/definitions/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:
type: object
$ref: '#/definitions/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: '#/definitions/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: '#/definitions/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: '#/definitions/identification'
preferredContactMethod:
description: The contact's preferred method of communication.
allOf:
- $ref: '#/definitions/preferredContactMethod'
type: object
x-apiture-flattened: true
identifiedContactFields:
title: Identified Contact Fields
description: Properties which provide additional identification of a person.
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: '#/definitions/citizenship'
residencyStatus:
description: This individual's residency status.
allOf:
- $ref: '#/definitions/residencyStatus'
occupation:
description: The occupation of this individual.
allOf:
- $ref: '#/definitions/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: '#/definitions/yearsAtAddress'
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/identifiedContactFields/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-version: 1.0.0
x-apiture-flattened: true
challenge:
title: Challenge (v1.0.0)
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:
example:
_id: 0399abed-fd3d-4830-a88b-30f38b8a365c
_profile: 'https://api.apiture.com/schemas/challenges/challenge/v1.0.0/profile.json'
reason: Transfer amount much higher than normal
contextUri: 'https://fi.apiture.com/users/50b9df19-d6bf-4ac0-b5f4-3e6448b7dacd/addresses/ha1'
minimumAuthenticatorCount: 1
authenticators:
- _id: 7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3
_profile: 'https://api.apiture.com/schemas/challenges/authenticator/v1.0.0/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-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/challenge/v1.0.0/model.json'
x-apiture-namespace: auth
x-apiture-composition:
- $ref: '#/definitions/abstractResource'
- $ref: '#/definitions/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.'
$ref: '#/definitions/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](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: '#/definitions/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: '#/definitions/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: '#/definitions/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
addresses:
title: Addresses
description: A list of postal addresses and the preferred mailing address.
x-apiture-fragment: true
properties:
addresses:
description: An array of postal/mailing addresses.
type: array
items:
type: object
$ref: '#/definitions/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-resolved-from: 'https://production.api.apiture.com/schemas/contacts/addresses/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-version: 1.0.0
type: object
x-apiture-flattened: true
emailAddresses:
title: Email Addresses
description: A list of email addresses and the preferred email address.
x-apiture-fragment: true
properties:
emailAddresses:
description: An array of email addresses.
type: array
items:
$ref: '#/definitions/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-resolved-from: 'https://production.api.apiture.com/schemas/contacts/emailAddresses/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-version: 1.0.0
type: object
x-apiture-flattened: true
phoneNumbers:
title: Phone Numbers
description: A list of phone numbers and the preferred phone number.
x-apiture-fragment: true
properties:
phones:
description: An array of phone numbers.
type: array
items:
$ref: '#/definitions/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: (555) 555-5555
- _id: mp1
type: mobile
number: (999) 555-5555
preferredPhoneId: hp1
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/phoneNumbers/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-version: 1.0.0
type: object
x-apiture-flattened: true
citizenship:
title: Citizenship
description: Citizenship or nationality status.
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-resolved-from: 'https://production.api.apiture.com/schemas/contacts/citizenship/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-version: 1.0.0
x-apiture-flattened: true
residencyStatus:
title: Residency
description: |-
Residency status.
**Warning**: the `enum` list will be removed in a future release.
and the values defined at runtime via the `residencyStatus`
label group in the response from the [`getLabels`](#op-getLabels) operation.
type: string
x-apiture-choice: residencyStatus
enum:
- unknown
- resident
- nonresident
- residentAlien
- nonresidentAlien
- other
- notApplicable
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/residencyStatus/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-version: 1.0.0
x-apiture-flattened: true
occupation:
title: Occupation
description: |-
The person's occupation.
**Warning**: the `enum` list will be removed in a future release.
and the values defined at runtime via the `occupation`
label group in the response from the [`getLabels`](#op-getLabels) operation.
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-resolved-from: 'https://production.api.apiture.com/schemas/contacts/occupation/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-version: 1.0.0
x-apiture-flattened: true
yearsAtAddress:
title: Years at Address
description: Categories for how long the person has been at their present home address.
type: string
enum:
- unknown
- oneOrFewer
- two
- three
- fourOrMore
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/contacts/yearsAtAddress/v1.0.0/model.json'
x-apiture-namespace: contacts
x-apiture-version: 1.0.0
x-apiture-flattened: true
labelItem:
title: Label Item
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.
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-version: 1.0.0
x-apiture-composition:
- $ref: '#/definitions/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: '#/definitions/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
summaryChallenge:
title: Summary Challenge (v1.0.0)
description: 'Summary representation of a challenge, used in the challenge collection.'
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/summaryChallenge/v1.0.0/model.json'
x-apiture-namespace: auth
x-apiture-composition:
- $ref: '#/definitions/abstractResource'
- $ref: '#/definitions/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.'
$ref: '#/definitions/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](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: '#/definitions/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: '#/definitions/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.0)
description: >
Representation of authenticators which verify a user's identity.
Links
Response and request bodies using this authenticator
schema may contain
the following links:
example:
_id: 7fadd35b-6f6b-4901-b1ba-d3b91c9dcee3
_profile: 'https://api.apiture.com/schemas/challenges/authenticator/v1.0.0/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-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/authenticator/v1.0.0/model.json'
x-apiture-namespace: auth
x-apiture-composition:
- $ref: '#/definitions/abstractResource'
- $ref: '#/definitions/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.'
$ref: '#/definitions/links'
_embedded:
description: 'An optional map of nested resources, mapping each nested resource name to a nested resource representation.'
type: object
_profile:
description: 'The URI of a [resource profile](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: '#/definitions/error'
type:
description: The type of this authenticator. This must be one of the items in the `/authenticatorTypes` resource.
allOf:
- $ref: '#/definitions/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: '#/definitions/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
description: A text label and optional description.
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-version: 1.0.0
x-apiture-flattened: true
challengeFields:
title: Challenge Fields (v1.0.0)
description: Properties of challenge objects.
x-apiture-fragment: true
properties:
reason:
description: >-
The reason the application or service has issued a challenge requesting the user verify their identity. This is for labeling or
informational purposes.
type: string
x-apiture-todo:
- Should this be a reasonCode (non-localizable identifier and reason label?
contextUri:
description: >-
The URI of a resource that establishes the context in which the user is asked to authenticate their identity. For example, for this may be
for a pending transfer, a user's mailing address, or an account if adding a joint owner.
type: string
format: uri
maxLength: 2048
userId:
description: >-
The user ID of the user who is requested to verify their identity. The default is the userID of the authenticated person creating the
challenge.
type: string
minimumAuthenticatorCount:
description: The minimum number of different authenticators the user must verify in order to satisfy the identity challenge. The default is 1.
type: integer
minimum: 0
maximum: 4
maximumRedemptionCount:
description: The maximum number of times the challenge may be used or redeemed. The default is 1.
type: integer
minimum: 1
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/challengeFields/v1.0.0/model.json'
x-apiture-namespace: auth
type: object
x-apiture-flattened: true
challengeState:
title: Challenge States (v1.0.0)
description: |
The state of an identity challenge resource. This is derived based on the state of the challenge's authenticators.
challengeState
strings may have one of the following
[enumerated values](https://developer.apiture.com/concepts/label-groups#enumerations) values
(described by the named challengeState)
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. |
x-apiture-enum: challengeState
type: string
enum:
- pending
- started
- verified
- failed
- redeemed
- expired
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/challengeState/v1.0.0/model.json'
x-apiture-namespace: auth
x-apiture-flattened: true
authenticatorFields:
title: Authenticator Fields (v1.0.0)
description: Common fields of an authenticator.
x-apiture-fragment: true
properties:
type:
description: The type of this authenticator. This must be one of the items in the `/authenticatorTypes` resource.
allOf:
- $ref: '#/definitions/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) values
(described by the named authenticatorState)
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. |
x-apiture-enum: authenticatorState
type: string
enum:
- pending
- started
- verified
- failed
- expired
x-apiture-version: 1.0.0
x-apiture-resolved-from: 'https://production.api.apiture.com/schemas/auth/authenticatorState/v1.0.0/model.json'
x-apiture-namespace: auth
x-apiture-flattened: true
authenticatorType:
title: Authenticator Type (v1.0.0)
description: An authenticator type description.
properties:
name:
type: string
description: The name of this authenticator; also the key in the `authenticatorTypes` object.
example: sms
label:
type: string
description: A localized label or title which may be used labels or other UI controls which present a value.
example: SMS code
description:
type: string
description: A more detailed localized description of an authenticator type.
language:
type: string
description: >-
The actual natural language tag to which this authentication type description is associated, as per [RFC
7231](https://tools.ietf.org/html/rfc7231#section-3.1.3.1). If omitted, this serves as the _default_.
example: en-us
category:
type: string
description: The authentication category.
allOf:
- $ref: '#/definitions/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) values
(described by the named authenticatorCategory)
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. |
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
x-apiture-errors:
accessDenied:
description: The credentials supplied in the request are insufficient to grant access
remediation: Check the supplied credentials for validity
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, /frozenUsers and /mergedUsers
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:
- active
- inactive
- locked
- merged
- removed
mergeUserDoesNotExist:
description: One of the users in the merge does not exist
remediation: Resubmit the operation with two users that exist
arrayRequired:
description: The property must be an array
remediation: Resubmit the operation with the property being in the proper format
attributes:
properties:
property: addresses
invalidDate:
description: The date of birth that was specified is not valid
remediation: Resubmit the operation with a valid date in the RFC 3339 format
attributes:
properties:
date: '2018-09-27'
malformedRequestBody:
description: The supplied request body was malformed
remediation: Check to make sure that your request body exists and that it does not contain syntax errors
ifMatchHeaderMissing:
description: Precondition Required. The request did not include the required if-Match header
remediation: 'Resubmit with the operation, supplying the value of the ETag and the most recent state of the resource'
ifMatchHeaderDoesntMatch:
description: The supplied `if-Match` header value does not match the most recent `ETag` response header value. The resource has changed in the interim
remediation: 'Resubmit the operation, supplying the value of the ETag and the most recent state of the resource'
requestError:
description: There was a server side error when executing the API request
remediation: Check your parameters and resubmit the request
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:
- home
- work
- mobile
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:
- home
- work
- school
- other
invalidGroupName:
description: No configurationGroup was found for the specified groupName
remediation: Check to make sure that the supplied groupName corresponds to an apiture transfer configuration group resource
invalidValueName:
description: No configurationName was found for the specified valueName
remediation: Check to make sure that the supplied valueName corresponds to an apiture transfer configuration value resource
invalidConfigurationGroup:
description: The request body did not conform to the schema for this configuration group
remediation: Check the schema for the configuration group and resubmit the operation
invalidConfigurationValue:
description: The request body did not conform to the schema for this configuration group value
remediation: Check the schema for the configuration group value and resubmit the operation
configurationAccessDenied:
description: The credentials supplied in the request are insufficient to grant access
remediation: Check the supplied credentials for validity
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-05-28T16:37:02.078Z'
host: api.devbank.apiture.com