swagger: '2.0' info: title: Identity description: >- This API manages the set of actions that allow financial institutions to verify the identity of their customers and applicants. 'Identity' is defined as a set of personally identifiable information (PII) that can potentially identify a specific individual. PII consists of the following attributes: * `taxId` The identity's tax or government ID * `firstName` The identity's first name * `lastName` The identity's last name * `address1` Line 1 of the identity's street address * `address2` Line 2 of the identity's street address * `city` The identity's city * `region` The identity's region * `postalCode` The identity's postal code * `phone` The identity's phone * `birthdate` The identity's birth date in `yyyy-mm-dd` format. * `email` The identity's email address * `ipAddress` The identity's IP address There are two major steps to the identity verification process - fraud-risk analysis and knowledge-base authentication (KBA) quizzes. A _fraud-risk report_ can be generated by specifying PII associated with an individual. Each report may contain a list of _fraud-risk attributes_ with a type and description describing the types of fraud that have been associated with the supplied PII. In order to generate a report, submit the PII via `POST` to `/fraudRiskReports`. This will return a `201` response containing a new `fraudRiskReport` resource which includes a set outputs with a collection of `fraudRiskCategories`. These categories are: * `personalInfoDoesNotMatch` The retrieved identity does not match the provided PII. * `addressIsPOBoxOrNonApproved` The provided address is a PO Box or other non-approved address * `addressIsHighRisk` The provided address is considered high-risk * `identityOnGovernmentWatchlist` The provided identity is located on one or more government watchlists * `identityOnAlertList` The provided identity is located on one or more alert lists * `ipRestricted` The provided IP address is restricted * `emailRestricted` The provided email address is restricted * `ageRestricted` The provided identity does not meet the required age. Example: US COPPA laws forbid conducting e-commerce with people under 14 years of age. * `nonStandardTaxId` The provided taxId is non-standard. Example: The provided SSN is an ITIN (Individual Taxpayer Identification Number) A _quiz_ containing a list of questions and their possible answers can be generated with a set of PII. This information can be used to assist in the verification of the identity, by presenting the customer or applicant with the questions and prompting them to choose the appropriate answers. These answers can then be submitted to verify their correctness, confirming the identity. In order to generate a quiz, submit the PII via `POST` to `/quizzes`. This will return a `201` response containing a new `quiz` resource with a state of `pending`. You can then `POST` to `/quizzes/{quizId}/questions` by following the `apiture:getQuestions` link to generate one-time-use (transient) set of questions. When you have collected the answers to these questions you can submit them to `/quizzes/{quizId}/answers` via `POST` by following the `apiture:score` link. This will return the quiz resource with an updated state, either `passed`, `failed` or `expired`. version: '0.1.0' termsOfService: Pending. contact: name: Apiture url: 'https://developer.aptiture.com' email: api@apiture.com schemes: - https basePath: /identity consumes: - application/hal+json - application/json produces: - application/hal+json - application/json tags: - name: API description: Endpoints which describe this API. - name: Fraud-Risk Reports description: Identity Fraud-Risk Reports - name: Quizzes description: Identity Verification Quizzes paths: /fraudRiskReports: get: summary: Returns a collection of fraud-risk analysis results description: >- Return a[ paginated](http://doc.apiture.com/api/concepts/pagination)[ sortable](http://doc.apiture.com/api/concepts/sorting)[ filterable](http://doc.apiture.com/api/concepts/filtering)[ searchable](http://doc.apiture.com/api/concepts/searchable) collection of fraud-risk analysis reports.The [links](http://doc.apiture.com/api/concepts/links) in the response include pagination links. operationId: getFraudRiskReports tags: - Fraud-Risk Reports parameters: - name: start in: query description: >- The zero-based index of the first fraud-risk analysis report in this page. The default, 0, represents the first report in the collection. type: integer format: int64 default: 0 - name: limit in: query description: >- The maximum number of fraud-risk analysis report representations to return in this page. type: integer format: int32 default: 100 - name: sortBy in: query type: string description: >- Optional sort criteria. See [sort criteria format](http://docs.apiture.com/api/concepts/sorting#criteria), such as `?sortBy=field1,-field2`. - $ref: '#/parameters/filterQueryParam' - $ref: '#/parameters/qQueryParam' responses: '200': description: OK schema: $ref: '#/definitions/fraudRiskReports' '400': $ref: '#/responses/400' '422': $ref: '#/responses/422' post: summary: Create a new fraud-risk analysis report description: >- Create a new fraud-risk analysis report in the fraud-risk analysis reports collection. If an `apiture:contact` link is specified in the request a verification token will be returned in the response. If an `apiture:contact` link is invalid a 400 Bad Request response will be returned. The following links will be included in a successful response under the `_links` property: * `self`: URI of the created fraud-risk report resource - `/fraudRiskReports/{fraudRiskReportId}` * `apiture:contact`: If the resource was created with an `apiture:contact` a link to the specified resource will be present operationId: createFraudRiskReport tags: - Fraud-Risk Reports parameters: - name: createFraudRiskReport in: body description: The identity required: true schema: $ref: '#/definitions/createFraudRiskReport' responses: '201': description: Created schema: $ref: '#/definitions/fraudRiskReport' 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 '400': $ref: '#/responses/400' '/fraudRiskReports/{fraudRiskReportId}': get: summary: Fetch a representation of this fraud-risk report description: >- Return a [HAL](http://docs.apiture.com/api/concepts/hal) representation of this fraud-risk analysis report resource. The following links will be included in a successful response under the `_links` property: * `self`: URI of the this fraud-risk report resource - `/fraudRiskReports/{fraudRiskReportId}` * `apiture:contact`: If the resource was created with an `apiture:contact` a link to the specified resource will be present operationId: getFraudRiskReport tags: - Fraud-Risk Reports parameters: - $ref: '#/parameters/fraudRiskReportIdPathParam' responses: '200': description: OK schema: $ref: '#/definitions/fraudRiskReport' '304': $ref: '#/responses/304' '404': $ref: '#/responses/404FraudRiskReport' /quizzes: get: summary: Returns a collection of quizzes description: >- Return a[ paginated](http://doc.apiture.com/api/concepts/pagination)[ sortable](http://doc.apiture.com/api/concepts/sorting)[ filterable](http://doc.apiture.com/api/concepts/filtering)[ searchable](http://doc.apiture.com/api/concepts/searchable) collection of quizzes. The [links](http://doc.apiture.com/api/concepts/links) in the response include pagination links. operationId: getQuizzes tags: - Quizzes parameters: - name: start in: query description: |- The zero-based index of the first quiz in this page. The default, 0, represents the first report in the collection. type: integer format: int64 default: 0 - name: limit in: query description: The maximum number of quiz representations to return in this page. type: integer format: int32 default: 100 - name: sortBy in: query type: string description: >- Optional sort criteria. See [sort criteria format](http://docs.apiture.com/api/concepts/sorting#criteria), such as `?sortBy=field1,-field2`. - $ref: '#/parameters/filterQueryParam' - $ref: '#/parameters/qQueryParam' responses: '200': description: OK schema: $ref: '#/definitions/quizzes' '400': $ref: '#/responses/400' '422': $ref: '#/responses/422' post: summary: Create a new quiz description: >- Create a new quiz in the quizzes collection for the specified identity. `state` defaults to `pending` If the apiture:contact` link is invalid a 400 Bad Request response will be returned. The following links will be included in a successful response under the `_links` property: * `self`: URI of the created quiz resource - `/quizzes/{quizId}` * `apiture:contact`: If the resource was created with an `apiture:contact` a link to the specified resource will be present operationId: createQuiz tags: - Quizzes parameters: - name: createQuiz in: body description: The identity required: true schema: $ref: '#/definitions/createQuiz' responses: '201': description: Created schema: $ref: '#/definitions/quiz' 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 '400': $ref: '#/responses/400' '/quizzes/{quizId}': get: summary: Fetch a representation of this quiz description: >- Return a [HAL](http://docs.apiture.com/api/concepts/hal) representation of this quiz resource. The following links will be included in a successful response under the `_links` property: * `self`: URI of the this quiz resource - `/quizzes/{quizId}` * `apiture:contact`: If the resource was created with an `apiture:contact` a link to the specified resource will be present operationId: getQuiz tags: - Quizzes parameters: - $ref: '#/parameters/quizIdPathParam' responses: '200': description: OK schema: $ref: '#/definitions/quiz' '304': $ref: '#/responses/304' '404': $ref: '#/responses/404Quiz' '/quizzes/{quizId}/questions': post: summary: Generate the questions for a quiz description: >- Generates the a set of questions for the quiz. Questions can only be generated if the state of the resource is `pending`. The following links will be included in a successful response under the `_links` property: * `up`: URI of the quiz resource - `/quizzes/{quizId}` * `apiture:score`: URI of the `/quizzes/{quizId}/answers` endpoint * `apiture:contact`: If the resource was created with a `apiture:contact` a link to the specified resource will be present operationId: createQuizQuestions tags: - Quizzes parameters: - $ref: '#/parameters/quizIdPathParam' responses: '201': description: Created schema: $ref: '#/definitions/quizQuestions' '400': $ref: '#/responses/400' '409': $ref: '#/responses/409QuizQuestionsConflict' '/quizzes/{quizId}/answers': post: summary: Submit the answers to a quiz description: >- Submits the answers for scoring and returns the quiz with a state of `passed`, `failed`, `scoring` or `expired`. Can only be processed if state is `asked`. The following links will be included in a successful response under the `_links` property: * `up`: URI of the quiz resource - `/quizzes/{quizId}` * `apiture:contact`: If the resource was created with a `apiture:contact` a link to the specified resource will be present operationId: scoreQuiz tags: - Quizzes parameters: - $ref: '#/parameters/quizIdPathParam' - name: scoreQuizAnswers in: body description: The identity required: true schema: $ref: '#/definitions/scoreQuizAnswers' responses: '201': description: Created schema: $ref: '#/definitions/quiz' '400': $ref: '#/responses/400' '409': $ref: '#/responses/409QuizAnswersConflict' /: get: summary: Top-level resources and operations in this API description: Return links to the top-level resources and operations in this API. operationId: getApi responses: '200': description: OK schema: $ref: '#/definitions/root' examples: application/hal+json: id: identity name: Identity apiVersion: 0.1.0 _profile: 'https://api.apiture.com/schemas/apiRoot/v.0.1.0/profile.json' _links: 'apiture:fraudRiskReports': href: /identity/fraudRiskReports 'apiture:quizzes': href: /identity/quizzes tags: - API /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 /contactVerification: get: summary: Retrieves contact verification resource. description: >- Retrieves the contact verification status. If the `contactUri` link is invalid a 400 Bad Request response will be returned. The following links will be included in a successful response under the _links property: * `apiture:contact`: If the specified contactUri param refers to a Contact resource a link to it will be present operationId: getContactVerification tags: - Verify parameters: - $ref: '#/parameters/contactUriParam' - name: type description: The identity method type. Possible values are `fraudRiskReport`, `quiz` or `adminApproval`. type: string in: query required: false responses: '200': description: OK schema: $ref: '#/definitions/contactVerification' '400': $ref: '#/responses/400' /approvals: post: summary: Create a new approval resource description: >- Create a new approval resource for the specified Contact. The following links may be included in a successful response under the `_links` property: * `self`: URI of the created approval resource - `/approvals/{approvalId}` * `apiture:contact`: If the specified contactUri param refers to a Contact resource a link to it will be present operationId: createApproval tags: - Approvals parameters: - $ref: '#/parameters/contactUriParam' - name: type description: The identity method type. Possible values are `fraudRiskReport`, `quiz` or `adminApproval`. type: string in: query required: false responses: '201': description: Created schema: $ref: '#/definitions/approval' headers: Location: description: >- The URI of the new resource. If the URI begins with / it is relative to the API root context. Else, it is a full URI starting with *`schema`*`://host` type: string format: uri '400': $ref: '#/responses/400Approval' '422': $ref: '#/responses/422Approval' '/approvals/{approvalId}': get: summary: Fetch a representation of this approval description: >- Return a [HAL](http://docs.apiture.com/api/concepts/hal) representation of this approval resource. The following links will be included in a successful response under the `_links` property: * `self`: URI of the this fraud-risk report resource - `/approvals/{approvalId}` * `apiture:contact`: If the specified contactUri param refers to a Contact resource a link to it will be present operationId: getApproval tags: - Approvals parameters: - $ref: '#/parameters/approvalIdPathParam' responses: '200': description: OK schema: $ref: '#/definitions/approval' '304': $ref: '#/responses/304' '404': $ref: '#/responses/404Approval' parameters: filterQueryParam: name: filter in: query description: >- Optional filter criteria. See [filtering](http://docs.apiture.com/api/concepts/filtering#criteria). type: string qQueryParam: name: q in: query description: >- Optional search string. See [searching](http://docs.apiture.com/api/concepts/searching). type: string fraudRiskReportIdPathParam: name: fraudRiskReportId description: The unique identifier of this fraud-risk report. This is an opaque string. in: path type: string required: true quizIdPathParam: name: quizId description: The unique identifier of this quiz. This is an opaque string. in: path type: string required: true approvalIdPathParam: name: approvalId description: The unique identifier of this approval. This is an opaque string. in: path type: string required: true contactUriParam: name: contactUri description: The `apiture:contact` URI. in: query type: string required: true definitions: collection: title: A collection of resources. description: A collection of resources. allOf: - $ref: '#/definitions/abstractResource' - type: object properties: count: description: The number of items 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 fraudRiskReports: title: Collection of fraud-risk reports. description: >- The items in the collection are ordered in the `_embedded` object with name `items`. The top-level `_links` object may contain pagination links (`self`, `next`, `prev`, `first`, `last`, `collection`.) allOf: - $ref: '#/definitions/collection' - type: object properties: _embedded: type: object properties: items: description: An array containg a page of fraud-risk analysis reports type: array items: $ref: '#/definitions/fraudRiskReport' example: _profile: >- https://api.apiture.com/schemas/collection/identity/fraudRiskReport/v1.0.0/profile.json start: 0 limit: 1 count: 1 name: fraudRiskReports _links: self: href: /identity/fraudRiskReports?start=0&limit=1 first: href: /identity/fraudRiskReports?start=0&limit=1 next: href: /identity/fraudRiskReports?start=1&limit=1 collection: href: /identity/fraudRiskReports _embedded: _profile: >- https://api.apiture.com/schemas/identity/fraudRiskReport/v1.0.0/profile.json _error: null items: - _profile: 'https://api.apiture.com/schemas/identity/fraudRiskReport/v1.0.0/profile.json' _links: self: href: /identity/fraudRiskReports/c6dbc32f-e0eb-4947-9819-c691bb9164a5 'apiture:contact': href: /contacts/contacts/6da5ccc7-727a-4256-bdd4-74023ae349c3 _id: c6dbc32f-e0eb-4947-9819-c691bb9164a5 type: fraudRiskReport inputs: identity: _profile: 'https://api.apiture.com/schemas/identity/identity/v1.0.0/profile.json' taxId: 555-55-5555 firstName: John lastName: Smith address1: 1741 Tiburon Dr city: Wilmington region: NC postalCode: '28403' phone: 555-555-5555 birthdate: '1940-10-15' email: api@apiture.com ipAddress: 127.0.0.1 outputs: fraudRiskCategories: - type: personalInfoDoesNotMatch description: The retrieved identity does not match the provided PII. - type: addressIsPOBoxOrNonApproved description: The provided address is a PO Box or other non-approved address - type: identityOnGovernmentWatchlist description: The provided identity is located on one or more government watchlists - type: identityOnAlertList description: The provided identity is located on one or more alert lists - type: ipRestricted description: The provided IP address is restricted - type: emailRestricted description: The provided email address is restricted fraudRiskReport: title: Fraud-risk Report allOf: - $ref: '#/definitions/abstractResource' - $ref: '#/definitions/identityVerification' - properties: inputs: $ref: '#/definitions/fraudRiskReportInputs' outputs: $ref: '#/definitions/fraudRiskReportOutputs' example: _profile: 'https://api.apiture.com/schemas/identity/fraudRiskReport/v1.0.0/profile.json' _links: self: href: /identity/fraudRiskReports/c6dbc32f-e0eb-4947-9819-c691bb9164a5 'apiture:contact': href: /contacts/contacts/6da5ccc7-727a-4256-bdd4-74023ae349c3 _id: c6dbc32f-e0eb-4947-9819-c691bb9164a5 type: fraudRiskReport inputs: identity: _profile: 'https://api.apiture.com/schemas/identity/identity/v1.0.0/profile.json' taxId: 555-55-5555 firstName: John lastName: Smith address1: 1741 Tiburon Dr city: Wilmington region: NC postalCode: '28403' phone: 555-555-5555 birthdate: '1940-10-15' email: api@apiture.com ipAddress: 127.0.0.1 outputs: fraudRiskCategories: - type: personalInfoDoesNotMatch description: The retrieved identity does not match the provided PII. - type: addressIsHighRisk description: The provided address is considered high-risk - type: addressIsPOBoxOrNonApproved description: The provided address is a PO Box or other non-approved address - type: identityOnGovernmentWatchlist description: The provided identity is located on one or more watchlists - type: ipRestricted description: The provided IP address is restricted - type: emailRestricted description: The provided email address is restricted - type: nonStandardTaxId description: 'The provided taxId is non-standard. Example: The provided SSN is an ITIN (Individual Taxpayer Identification Number)' - type: ageRestricted description: 'The provided identity does not meet the required age. Example: US COPPA laws forbid conducting e-commerce with people under 14 years of age.' token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.XbPfbIHMI6arZ3Y922BhjWgQzWXcXNrz0ogtVhfEd2o fraudRiskCategory: title: Fraud-risk Category description: Representation of a fraud-risk category properties: type: $ref: '#/definitions/fraudRiskCategoryType' description: description: The description of the fraud. type: string example: type: addressIsPOBoxOrNonApproved description: The provided address is a PO Box or other non-approved address fraudRiskCategoryType: title: Fraud Risk Category Type description: Represents the possible types of fraud-risk type: string enum: - ipRestricted - identityOnGovernmentWatchlist - identityOnAlertList - addressIsPOBoxOrNonApproved - addressIsHighRisk - ageRestricted - nonStandardTaxId - personalInfoDoesNotMatch - emailRestricted createFraudRiskReport: title: Create Fraud Risk Report description: >- Representation used to create a new fraud-risk analysis report allOf: - $ref: '#/definitions/abstractResource' - $ref: '#/definitions/identity' example: _links: 'apiture:contact': href: /contacts/contacts/6da5ccc7-727a-4256-bdd4-74023ae349c3 createQuiz: title: Create Quiz description: >- Representation used to create a new quiz allOf: - $ref: '#/definitions/identity' - $ref: '#/definitions/abstractResource' example: _links: 'apiture:contact': href: /contacts/contacts/6da5ccc7-727a-4256-bdd4-74023ae349c3 scoreQuizAnswers: title: Score Quiz Answers description: >- Representation used to provide answers to a quiz allOf: - $ref: '#/definitions/coreQuizAnswers' example: quizQuestions: title: Create Questions description: >- Representation used to create a new set of questions allOf: - $ref: '#/definitions/abstractResource' - $ref: '#/definitions/coreQuizQuestions' - $ref: '#/definitions/verificationToken' example: _links: up: href: /identity/quizzes/73be83af-9e64-4214-8e90-76da43610b31 'apiture:score': href: /identity/quizzes/73be83af-9e64-4214-8e90-76da43610b31/answers questions: - id: '1' question: Who have you lived with? choices: - Mary - Caleb - Angela - Elliott - id: '2' question: What's your mother's maiden name? choices: - Clark - Morris - Niffle - Bennett token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.XbPfbIHMI6arZ3Y922BhjWgQzWXcXNrz0ogtVhfEd2o verificationToken: title: Verification Token description: The token used to validate and track a contact for identity verification purposes. properties: token: type: string description: An opaque string that conveys the state of the contact's identity verification. contactVerification: title: Verification description: >- Representation used to verify a contact. May contain a link to `apiture:contact`. allOf: - $ref: '#/definitions/abstractResource' - type: object properties: verifications: type: array items: properties: _links: $ref: '#/definitions/links' state: type: string enum: - passed - failed verifiedAt: description: The date-time when the verification occurred. type: string format: date-time example: _links: 'apiture:contact': href: /contacts/contacts/6da5ccc7-727a-4256-bdd4-74023ae349c3 verifications: - type: fraudRiskReport _links: self: href: /identity/fraudRiskReports/c6dbc32f-e0eb-4947-9819-c691bb9164a5 state: passed verifiedAt: '2018-01-12T10:15:17Z' - type: quiz _links: self: href: /identity/quizzes/73be83af-9e64-4214-8e90-76da43610b31 state: passed verifiedAt: '2018-01-12T10:19:41Z' identity: title: Identity description: Information that describes the identity required: - taxId - firstName - lastName - address1 - city - region - postalCode - phone - birthdate properties: taxId: description: The identity's tax or government ID type: string maxLength: 128 minLength: 1 firstName: description: The identity's first name. type: string maxLength: 128 minLength: 1 lastName: description: The identity's last name. type: string maxLength: 128 minLength: 1 address1: description: Line 1 of the identity's street address. type: string maxLength: 512 minLength: 1 address2: description: Line 2 of the identity's street address. type: string maxLength: 512 minLength: 1 city: description: The identity's city. type: string maxLength: 64 minLength: 1 region: description: The identity's region. type: string maxLength: 128 minLength: 1 postalCode: description: The identity's postal code. type: string maxLength: 32 minLength: 1 phone: description: The identity's phone. type: string maxLength: 32 minLength: 1 birthdate: description: The identity's birth date in `yyyy-mm-dd` format. type: string format: date pattern: '^([12]\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01]))$' maxLength: 10 minLength: 10 email: description: The identity's email address type: string format: email maxLength: 256 ipAddress: description: The identity's IP address type: string format: ipv4 example: taxId: 555-55-5555 firstName: John lastName: Smith address1: 1741 Tiburon Dr city: Wilmington region: NC postalCode: '28403' phone: 555-555-5555 birthdate: '1940-10-15' email: api@apiture.com ipAddress: 127.0.0.1 quizzes: title: Quizzes description: Collection of quizzes allOf: - $ref: '#/definitions/collection' - type: object properties: _embedded: type: object properties: items: description: An array containg a page of quizzes type: array items: $ref: '#/definitions/quiz' example: _profile: >- https://api.apiture.com/schemas/collection/identity/quiz/v1.0.0/profile.json start: 0 limit: 1 count: 1 name: quizzes _links: self: href: /identity/quizzes?start=0&limit=1 first: href: /identity/quizzes?start=0&limit=1 next: href: /identity/quizzes?start=1&limit=1 collection: href: /identity/quizzes _embedded: _profile: 'https://api.apiture.com/schemas/identity/quiz/v1.0.0/profile.json' _error: null items: - createdAt: '2018-01-12T10:15:17Z' expiresAt: '2018-01-12T10:30:17Z' _links: self: href: /identity/quizzes/73be83af-9e64-4214-8e90-76da43610b31 'apiture:score': href: /identity/quizzes/73be83af-9e64-4214-8e90-76da43610b31/answers 'apiture:contacts': href: /contacts/contacts/6da5ccc7-727a-4256-bdd4-74023ae349c3 inputs: identity: _profile: 'https://api.apiture.com/schemas/identity/identity/v1.0.0/profile.json' taxId: 555-55-5555 firstName: John lastName: Smith address1: 1741 Tiburon Dr city: Wilmington region: NC postalCode: '28403' phone: 555-555-5555 birthdate: '1940-10-15' email: api@apiture.com ipAddress: 127.0.0.1 outputs: state: failed token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.XbPfbIHMI6arZ3Y922BhjWgQzWXcXNrz0ogtVhfEd2o - createdAt: '2018-01-02T12:11:47Z' expiresAt: '2018-01-02T12:26:47Z' _links: self: href: /identity/quizzes/a71c3843-32c2-4054-b7b2-fcf11a84532f inputs: identity: _profile: 'https://api.apiture.com/schemas/identity/identity/v1.0.0/profile.json' taxId: 111-11-1111 firstName: Mary lastName: Williams address1: 1741 Tiburon Dr city: Wilmington region: NC postalCode: '28403' phone: 555-555-5555 birthdate: '1960-03-05' email: api@apiture.com ipAddress: 127.0.0.1 outputs: state: passed token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.XbPfbIHMI6arZ3Y922BhjWgQzWXcXNrz0ogtVhfEd2o quiz: title: Quiz description: > A quiz containing a collection of questions and their possible answers. These questions can be used to present a multiple-choice quiz in order to verify the identity. allOf: - $ref: '#/definitions/abstractResource' - $ref: '#/definitions/identityVerification' - properties: inputs: $ref: '#/definitions/quizInputs' outputs: $ref: '#/definitions/quizOutputs' example: _id: 73be83af-9e64-4214-8e90-76da43610b31 type: quiz createdAt: '2018-01-12T10:15:17Z' expiresAt: '2018-01-12T10:30:17Z' _profile: 'https://api.apiture.com/schemas/identity/quiz/v1.00/profile.json' _links: self: href: /identity/quizzes/73be83af-9e64-4214-8e90-76da43610b31 'apiture:score': href: /identity/quizzes/73be83af-9e64-4214-8e90-76da43610b31/answers 'apiture:getQuestions': href: /identity/quizzes/73be83af-9e64-4214-8e90-76da43610b31/questions 'apiture:contact': href: /contacts/contacts/6da5ccc7-727a-4256-bdd4-74023ae349c3 inputs: identity: _profile: 'https://api.apiture.com/schemas/identity/identity/v1.0.0/profile.json' taxId: 555-55-5555 firstName: John lastName: Smith address1: 1741 Tiburon Dr city: Wilmington region: NC postalCode: '28403' phone: 555-555-5555 birthdate: '1940-10-15' email: api@apiture.com ipAddress: 127.0.0.1 outputs: state: passed token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.XbPfbIHMI6arZ3Y922BhjWgQzWXcXNrz0ogtVhfEd2o coreQuizQuestions: title: Quiz Questions description: The questions of a quiz properties: questions: description: An array containing a page of quiz question items type: array items: $ref: '#/definitions/coreQuizQuestion' example: questions: - id: '1' question: Who have you lived with? choices: - Mary - Caleb - Angela - Elliott - id: '2' question: What's your mother's maiden name? choices: - Clark - Morris - Niffle - Bennett coreQuizQuestion: title: Quiz Question description: A question of a quiz required: - id - question properties: id: description: >- The identifier for this question. A quiz answer is associated with the question via the `questionId`. type: string question: description: The question text type: string choices: description: An array containing a page of quiz question choice items type: array items: type: string example: id: '1' question: Who have you lived with? choices: - Mary - Caleb - Angela - Elliott quizAnswers: title: Quiz Answers description: A collection of answers to a quiz allOf: - $ref: '#/definitions/coreQuizAnswers' coreQuizAnswers: title: Quiz Answers description: A collection of answers to a quiz allOf: - properties: answers: type: array items: $ref: '#/definitions/coreAnswer' example: answers: - questionId: '1' answer: Honda Accord - questionId: '2' answer: Missouri coreAnswer: title: Quiz Answer description: An answer to a quiz question required: - questionId - answer properties: questionId: description: The ID corresponding to the question in the quiz type: string maxLength: 256 minLength: 1 answer: description: The answer to the question maxLength: 256 minLength: 1 type: string example: questionId: '1' answer: Honda Accord outputs: title: Outputs description: Base model schema for identity verification operations outputs allOf: - $ref: '#/definitions/verificationToken' inputs: title: Inputs description: Base model schema for identity verification operations inputs quizOutputs: title: Quiz Outputs description: The outputs of a quiz. Used for workflow allOf: - $ref: '#/definitions/outputs' - properties: state: description: >- The state of the quiz. Can be `pending`, `failedGetQuestions`, `asked`, `scoring`, `passed`, `failed` or `expired` enum: - pending - failedGetQuestions - asked - scoring - passed - failed - expired type: string fraudRiskReportOutputs: title: Fraud-risk Report Outputs description: The outputs of a fraud-risk report. Used for workflow allOf: - $ref: '#/definitions/outputs' - properties: fraudRiskCategories: type: array items: $ref: '#/definitions/fraudRiskCategory' quizInputs: title: Quiz Inputs. description: The inputs of a quiz. Used for workflow allOf: - $ref: '#/definitions/inputs' - properties: identity: $ref: '#/definitions/identity' fraudRiskReportInputs: title: Fraud-risk Report Inputs description: The inputs of a fraud-risk report. Used for workflow allOf: - $ref: '#/definitions/inputs' - properties: identity: $ref: '#/definitions/identity' identityVerification: title: Identity Verification Resource description: The core representation of an identity verification resource allOf: - $ref: '#/definitions/abstractResource' - $ref: '#/definitions/identityVerificationType' - properties: _id: type: string description: >- A unique identifier for this resource instance. This is is an opaque string. createdAt: description: The date-time when the resource was created. type: string format: date-time expiresAt: description: The date-time when the resource expires. type: string format: date-time identityVerificationType: title: Identity Verification Type description: Represents the possible types of identity verification properties: type: type: string enum: - fraudRiskReport - quiz - adminApproval approval: title: Approval description: >- The core representation of an Approval resource. This represents a manual approval and would typically be created by an FI admin when a Contact fails one or more steps of the identity verification workflow. allOf: - $ref: '#/definitions/abstractResource' - $ref: '#/definitions/identityVerification' example: _profile: 'https://api.apiture.com/schemas/identity/approval/v1.0.0/profile.json' _links: self: href: /identity/approval/a42234d9-b16a-439d-b464-55296a0b229a 'apiture:contact': href: /contacts/contacts/6da5ccc7-727a-4256-bdd4-74023ae349c3 _id: a42234d9-b16a-439d-b464-55296a0b229a type: adminApproval createdAt: '2018-01-12T10:15:17Z' abstractResource: title: Base model schema for resource representations description: >- An augmented [HAL](https://tools.ietf.org/html/draft-kelly-json-hal-08) resource representation. This model contains hypermedia `_links`, and either optional domain object data with `_profile` and optional `_embedded` objects, or an `_error` object. In responses, if the operation was successful, this object will not include the `_error`, but if the operation was a 4xx or 5xx error, this object will not include `_embedded` or any data fields, only `_error` and optionally `_links`. example: _profile: 'https://api.apiture.com/schemas/example/v.0.1.0/profile.json' _links: self: href: properties: _links: $ref: '#/definitions/links' _embedded: type: object description: >- An optional map of nested resources, mapping each nested resource name to a nested resource representation. _profile: type: string format: uri description: >- The URI of a [resource profile](http://doc.apiture.com/api/concepts/resource-profile) which describes the representation. _error: type: object description: >- An object which describes an error. This value is omitted if the operation succeeded without error. allOf: - $ref: '#/definitions/error' attributes: title: Dynamic attribute map description: >- An optional map of name/value pairs which contains additional dynamic data about the resource. type: object root: title: The root of this API description: >- A HAL response, with hypermedia `_links` for the top-level resources and operations in API. example: id: apiName name: API name apiVersion: 0.0.1-SNAPSHOT _profile: 'https://api.apiture.com/schemas/apiRoot/v1.0.0/profile.json' _links: null allOf: - $ref: '#/definitions/abstractResource' - type: object properties: _id: type: string description: This API's unique ID. name: type: string description: This API's name. apiVersion: type: string description: This API's version. errorResponse: title: Error Response description: >- Describes an error response, typically returned on 4xx or 5xx errors from API operations. The `_error` object contains the error details. allOf: - $ref: '#/definitions/abstractResource' example: _profile: 'https://api.apiture.com/schemas/error/v1.0.0/.json' _error: _id: 2eae46e1-575c-4d69-8a8f-0a7b0115a4b3 _profile: 'https://api.apiture.com/schemas/error/v1.0.0/profile.json' message: The value for deposit must be greater than 0. statusCode: 422 type: positiveNumberRequired attributes: value: -125.50 remediation: Provide a value which is greater than 0 occurredAt: 2018-01-25T05:50:52.375Z _links: describedby: href: 'http://doc.apiture.com/errors/positiveNumberRequired' _embedded: errors: [] error: title: Error description: >- An error description. Nested source errors are contained in the `_embedded` object with the key `"errors"`; this is an array of nested error objects. For example, an API which validates its request body may find multiple errors in the request, which may be detailed here. The `_links` may contain a `describedby` link which refers to a web page with details about the error. The `attributes` field An optional map of name/value pairs which provide structured data about the error. For example, if the error is a value out of range, the attributes may specify the range values `min` and `max`. This allows clients to present error messages as they see fit (the API does not assume the client/presentation tier). required: - message properties: message: type: string description: A localized message string describing the error condition. _id: type: string description: >- A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at the source of the error). This is is an opaque string. statusCode: description: The HTTP status code associate with this error. type: integer minimum: 100 maximum: 599 example: 422 type: type: string description: >- An error identifier which indicates the category of error and associate it with API support documentation or which the UI tier can use to render an appropriate message or hint. This provides a finer level of granularity than the `statusCode`. For example, instead of just 400 Bad Request, the `type` may be much more specific. such as `integerValueNotInAllowedRange` or `numericValueExceedsMaximum` or `stringValueNotInAllowedSet`. occurredAt: type: string format: date-time description: An ISO 8601 UTC time stamp indicating when the error occurred. example: '2018-02-02T03:37:15.375Z' attributes: description: Data attribute associated with the error, such as values or constraints. allOf: - $ref: '#/definitions/attributes' remediation: type: string description: An optional localized string which provides hints for how the user or client can resolve the error. _embedded: description: Optional embedded array of errors. This field may not exist if the error does not have nested errors. type: object properties: items: description: An array of error objects. type: array items: $ref: '#/definitions/errorResponse' example: _id: 2eae46e1-575c-4d69-8a8f-0a7b0115a4b3 _profile: 'https://api.apiture.com/schemas/error/v1.0.0/profile.json' message: The value for deposit must be greater than 0. statusCode: 422 type: positiveNumberRequired attributes: value: -125.50 remediation: Provide a value which is greater than 0 occurredAt: '2018-01-25T05:50:52.375Z' _links: describedby: href: 'http://doc.apiture.com/errors/positiveNumberRequired' _embedded: errors: [] links: title: A set of hypermedia links description: >- An optional map of links, mapping each link relation to a link object. This model defines the `_links` object of HAL representations. type: object additionalProperties: $ref: '#/definitions/link' link: title: A hypermedia links to a related resource or operation type: object description: >- Describes a hypermedia link withing a `_links` object in HAL representations. In Apiture APIs, links are [HAL links](https://tools.ietf.org/html/draft-kelly-json-hal-08#section-5), but Apiture APIs do not use the `name` or `hreflang` properties of HAL. Apiture links _may_ include a `method` property. required: - href properties: href: type: string format: uri description: >- The URI or URI template for the resource/operation this link refers to. type: type: string description: The media type for the resource. templated: type: boolean description: >- If true, the link's href is a [URI template](https://tools.ietf.org/html/rfc6570). title: type: string description: An optional human-readable localized title for the link. deprecation: type: string format: uri description: >- If present, the containing link is deprecated and the value is a URI which provides human-readable text information about the deprecation. profile: type: string format: uri description: >- The URI of a profile document, a JSON document which describes the target resource/operation. responses: '304': description: >- Not Modified. The resource has not been modified since it was last fetched. '400': description: >- Bad Request. 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' '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' 400Approval: description: >- Bad Request. The `{contactUri}` query parameter was not well formed. The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' 404FraudRiskReport: description: >- Not Found. There is no such fraud-risk report resource at the specified `{fraudRiskReportId}` The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' 422Approval: description: >- Unprocessable Entity. The `{contactUri}` parameter was well formed but otherwise invalid. The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' 404Quiz: description: >- Not Found. There is no such quiz resource at the specified `{quizId}` The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' 404Approval: description: >- Not Found. There is no such approval at the specified `{fraudRiskReportId}` The `_error` field in the response will contain details about the request error. schema: $ref: '#/definitions/errorResponse' 409QuizAnswersConflict: description: >- Conflict. Answers may only be submitted if the current state of the resource is `asked`. schema: $ref: '#/definitions/errorResponse' 409QuizQuestionsConflict: description: >- Conflict. Questions may only be retrieved if the current state of the resource is `pending`. schema: $ref: '#/definitions/errorResponse' x-apiture-errors: accessDenied: description: The credentials supplied in the request are insufficient to grant access remediation: Check the supplied credentials for validity identityAccessDenied: description: The credentials supplied in the request are insufficient to grant access remediation: Check the supplied credentials for validity x-apiture-traits: - api: links: [ getFraudRiskReports, createFraudRiskReport, getQuizzes, createQuiz, getApi, getApiDoc, createApproval, ]