Document email_verified on the contact object

descriptions/0/api.intercom.io.yaml

@@ -8878,6 +8878,7 @@ paths:
                     external_id: '70'
                     role: user
                     email: joebloggs@intercom.io
+                    email_verified: false
                     phone:
                     formatted_phone:
                     name: joe bloggs
@@ -8967,6 +8968,7 @@ paths:
                     external_id: '70'
                     role: user
                     email: joebloggs@intercom.io
+                    email_verified: false
                     phone:
                     formatted_phone:
                     name: joe bloggs
@@ -9161,6 +9163,7 @@ paths:
                     external_id: '70'
                     role: user
                     email: joe@bloggs.com
+                    email_verified: false
                     phone:
                     formatted_phone:
                     name: Joe Bloggs
@@ -9375,6 +9378,7 @@ paths:
                     external_id: '70'
                     role: user
                     email: joe@bloggs.com
+                    email_verified: false
                     phone:
                     formatted_phone:
                     name: Joe Bloggs
@@ -10014,6 +10018,7 @@ paths:
                     external_id:
                     role: user
                     email: joebloggs@intercom.io
+                    email_verified: false
                     phone:
                     formatted_phone:
                     name:
@@ -10175,6 +10180,7 @@ paths:
                     external_id: '70'
                     role: user
                     email: joe@bloggs.com
+                    email_verified: false
                     phone:
                     formatted_phone:
                     name: Joe Bloggs
@@ -25955,6 +25961,7 @@ paths:
                     external_id:
                     role: user
                     email: foo@bar.com
+                    email_verified: false
                     phone:
                     formatted_phone:
                     name:
@@ -31460,6 +31467,11 @@ components:
           type: string
           description: The contact's email domain.
           example: example.com
+        email_verified:
+          type: boolean
+          description: >-
+            Whether the contact has proved they own their current email address. `true` only when this address was marked verified through the Contacts API (`email_verified: true` on create or update) and has not changed since; it becomes `false` again if the contact's email changes, until the new address is verified. Intercom reuses a lead with a verified email when it later matches an inbound email, or an outbound conversation or ticket, to that address, instead of creating a new lead. Only returned on the Preview version; not present on any released API version.
+          example: true
         phone:
           type: string
           nullable: true
@@ -34837,7 +34849,14 @@ components:
         email_verified:
           type: boolean
           nullable: true
-          description: Whether the contact's email address has been verified. Set to true to indicate you have verified the contact owns this email address, or false to mark it as unverified. Must be supplied together with an email in the same request; sending it without an email returns a 400. Verifying a lead's email also makes that lead reusable whenever Intercom matches an email address to a contact. When inbound email arrives from an address no user has, or an outbound conversation or ticket is created for one, Intercom reuses a lead with that address whose email is verified, instead of creating a new lead. Leads with an unverified email are not matched this way.
+          description: |-
+            Whether the contact has proved they own this email address, for example by completing a confirmation link or one-time code you sent to it. Send `email_verified` in the same request as `email`, for example `{"email": "jane@example.com", "email_verified": true}`. A request that includes `email_verified` without `email` fails with a `400`.
+
+            - `true`: ownership is proved.
+            - `false`: ownership is not proved.
+            - Omitted: the current verification status stays the same.
+
+            New contacts start unverified. If you change a verified contact's email, the new address is unverified until you verify it. Only send `true` when you have that proof. When an inbound email, outbound conversation, or ticket matches a verified address, Intercom reuses that lead instead of creating a new one.
           example: true
         phone:
           type: string
@@ -43113,7 +43132,14 @@ components:
         email_verified:
           type: boolean
           nullable: true
-          description: Whether the contact's email address has been verified. Set to true to indicate you have verified the contact owns this email address, or false to mark it as unverified. Must be supplied together with an email in the same request; sending it without an email returns a 400. Verifying a lead's email also makes that lead reusable whenever Intercom matches an email address to a contact. When inbound email arrives from an address no user has, or an outbound conversation or ticket is created for one, Intercom reuses a lead with that address whose email is verified, instead of creating a new lead. Leads with an unverified email are not matched this way.
+          description: |-
+            Whether the contact has proved they own this email address, for example by completing a confirmation link or one-time code you sent to it. Send `email_verified` in the same request as `email`, for example `{"email": "jane@example.com", "email_verified": true}`. A request that includes `email_verified` without `email` fails with a `400`.
+
+            - `true`: ownership is proved.
+            - `false`: ownership is not proved.
+            - Omitted: the current verification status stays the same.
+
+            New contacts start unverified. If you change a verified contact's email, the new address is unverified until you verify it. Only send `true` when you have that proof. When an inbound email, outbound conversation, or ticket matches a verified address, Intercom reuses that lead instead of creating a new one.
           example: true
         phone:
           type: string

descriptions/2.16/api.intercom.io.yaml

@@ -28100,7 +28100,14 @@ components:
         email_verified:
           type: boolean
           nullable: true
-          description: Whether the contact's email address has been verified. Set to true to indicate you have verified the contact owns this email address, or false to mark it as unverified. Must be supplied together with an email in the same request; sending it without an email returns a 400. Verifying a lead's email also makes that lead reusable whenever Intercom matches an email address to a contact. When inbound email arrives from an address no user has, or an outbound conversation or ticket is created for one, Intercom reuses a lead with that address whose email is verified, instead of creating a new lead. Leads with an unverified email are not matched this way.
+          description: |-
+            Whether the contact has proved they own this email address, for example by completing a confirmation link or one-time code you sent to it. Send `email_verified` in the same request as `email`, for example `{"email": "jane@example.com", "email_verified": true}`. A request that includes `email_verified` without `email` fails with a `400`.
+
+            - `true`: ownership is proved.
+            - `false`: ownership is not proved.
+            - Omitted: the current verification status stays the same.
+
+            New contacts start unverified. If you change a verified contact's email, the new address is unverified until you verify it. Only send `true` when you have that proof. When an inbound email, outbound conversation, or ticket matches a verified address, Intercom reuses that lead instead of creating a new one.
           example: true
         email:
           type: string
@@ -34839,7 +34846,14 @@ components:
         email_verified:
           type: boolean
           nullable: true
-          description: Whether the contact's email address has been verified. Set to true to indicate you have verified the contact owns this email address, or false to mark it as unverified. Must be supplied together with an email in the same request; sending it without an email returns a 400. Verifying a lead's email also makes that lead reusable whenever Intercom matches an email address to a contact. When inbound email arrives from an address no user has, or an outbound conversation or ticket is created for one, Intercom reuses a lead with that address whose email is verified, instead of creating a new lead. Leads with an unverified email are not matched this way.
+          description: |-
+            Whether the contact has proved they own this email address, for example by completing a confirmation link or one-time code you sent to it. Send `email_verified` in the same request as `email`, for example `{"email": "jane@example.com", "email_verified": true}`. A request that includes `email_verified` without `email` fails with a `400`.
+
+            - `true`: ownership is proved.
+            - `false`: ownership is not proved.
+            - Omitted: the current verification status stays the same.
+
+            New contacts start unverified. If you change a verified contact's email, the new address is unverified until you verify it. Only send `true` when you have that proof. When an inbound email, outbound conversation, or ticket matches a verified address, Intercom reuses that lead instead of creating a new one.
           example: true
         phone:
           type: string