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: <uri of current resource>
    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,
        ]
