STF-2255: Clarify minFraud verification input descriptions

components/minfraud-request.yaml

@@ -208,19 +208,27 @@ schemas:
       verification_time:
         $ref: "#/schemas/DateTime"
         description: >-
-          The most recent date and time a verification of the email address was
-          attempted, if known, in RFC 3339 date-time format. The time must not
-          be before 1970-01-01T00:00:00Z or more than two days in the future.
-          For a time outside this range, MaxMind ignores the input and returns a
-          warning.
+          The date and time of the most recent completed verification of the
+          email address, if known, in RFC 3339 date-time format. The value must
+          reflect the verification state as of the time of the event. Use the
+          time the verification succeeded or failed, for example the time the
+          user clicked the link, not the time you sent the link. Do not include
+          this field if no verification was attempted or no verification is
+          complete. The time must not be before 1970-01-01T00:00:00Z or more
+          than two days in the future. For a time outside this range, MaxMind
+          ignores the input and returns a warning.
       was_verification_successful:
         type: boolean
         description: >-
-          Whether the most recent verification that the end user controls this
-          email address was successful (e.g. by confirming a link sent to the
-          email address). `true` if the email verification was successful, or
-          `false` if the user failed email verification. Do not include this
-          field if you have not performed this check.
+          Whether the most recent completed verification that the end user
+          controls this email address was successful (e.g. by confirming a link
+          sent to the email address). The value must reflect the verification
+          state as of the time of the event. `true` if the email verification
+          was successful, or `false` if the user failed email verification. A
+          pending, abandoned, or expired verification is not complete and is not
+          a failure. If no verification is complete, for example because the
+          user has not clicked the link yet, do not include this field. Do not
+          include this field if you have not performed this check.
   Address:
     type: object
     description: A billing or shipping address.
@@ -268,8 +276,10 @@ schemas:
           - delivered_code
           - other
         description: >-
-          The method used for the most recent verification attempt of the phone
-          number. Do not include this field if no verification was attempted.
+          The method used for the most recent completed verification of the
+          phone number. The value must reflect the verification state as of the
+          time of the event. Do not include this field if no verification was
+          attempted or no verification is complete.
 
 
           - `network`: carrier or SIM-based silent network authentication. No
@@ -285,18 +295,26 @@ schemas:
       phone_verification_time:
         $ref: "#/schemas/DateTime"
         description: >-
-          The most recent date and time a verification of the phone number was
-          attempted, if known, in RFC 3339 date-time format. The time must not
-          be before 1970-01-01T00:00:00Z or more than two days in the future.
-          For a time outside this range, MaxMind ignores the input and returns a
-          warning.
+          The date and time of the most recent completed verification of the
+          phone number, if known, in RFC 3339 date-time format. The value must
+          reflect the verification state as of the time of the event. Use the
+          time the verification succeeded or failed, for example the time the
+          user entered the code, not the time you sent the code. Do not include
+          this field if no verification was attempted or no verification is
+          complete. The time must not be before 1970-01-01T00:00:00Z or more
+          than two days in the future. For a time outside this range, MaxMind
+          ignores the input and returns a warning.
       phone_was_verification_successful:
         type: boolean
         description: >-
-          Whether the most recent verification that the end user controls this
-          phone number was successful, using the method named in
-          `phone_verification_method`. `true` if the phone verification was
-          successful, or `false` if the user failed phone verification. Do not
+          Whether the most recent completed verification that the end user
+          controls this phone number was successful, using the method named in
+          `phone_verification_method`. The value must reflect the verification
+          state as of the time of the event. `true` if the phone verification
+          was successful, or `false` if the user failed phone verification. A
+          pending, abandoned, or expired verification is not complete and is not
+          a failure. If no verification is complete, for example because the
+          user has not entered the code yet, do not include this field. Do not
           include this field if you have not performed this check.
       postal:
         type: string