From d03d544d1b73474f27ec919ce5e23123545eaaa2 Mon Sep 17 00:00:00 2001 From: dq Date: Tue, 22 Sep 2026 16:10:23 +0100 Subject: [PATCH 01/13] Document email_verified on the contact object The contact object now returns whether its email address has been verified. The field was already accepted on contact create and update. --- descriptions/0/api.intercom.io.yaml | 5 +++++ descriptions/2.16/api.intercom.io.yaml | 5 +++++ 2 files changed, 10 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 9538d528..53329b26 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -31289,6 +31289,11 @@ components: type: string description: The contact's email domain. example: example.com + email_verified: + type: boolean + description: Whether the contact's email address has been verified. This + is false if the contact's email has changed since it was last verified. + example: true phone: type: string nullable: true diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index 75272ea0..a8066198 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -25293,6 +25293,11 @@ components: type: string description: The contact's email domain. example: example.com + email_verified: + type: boolean + description: Whether the contact's email address has been verified. This + is false if the contact's email has changed since it was last verified. + example: true phone: type: string nullable: true From 99ccbee5dd9682078787ded0a4e3bb8e35d1220b Mon Sep 17 00:00:00 2001 From: dq Date: Tue, 22 Sep 2026 16:41:41 +0100 Subject: [PATCH 02/13] Show the new field in the full-shape contact response examples Only examples that spell out the whole contact object, and the visitor convert endpoint, which returns a contact rather than a visitor. --- descriptions/0/api.intercom.io.yaml | 7 +++++++ descriptions/2.16/api.intercom.io.yaml | 7 +++++++ 2 files changed, 14 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 53329b26..ec50cca7 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/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 @@ -25808,6 +25814,7 @@ paths: external_id: role: user email: foo@bar.com + email_verified: false phone: formatted_phone: name: diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index a8066198..45614d01 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -8070,6 +8070,7 @@ paths: external_id: '70' role: user email: joebloggs@intercom.io + email_verified: false phone: name: joe bloggs avatar: @@ -8158,6 +8159,7 @@ paths: external_id: '70' role: user email: joebloggs@intercom.io + email_verified: false phone: name: joe bloggs avatar: @@ -8351,6 +8353,7 @@ paths: external_id: '70' role: user email: joe@bloggs.com + email_verified: false phone: name: Joe Bloggs avatar: @@ -8558,6 +8561,7 @@ paths: external_id: '70' role: user email: joe@bloggs.com + email_verified: false phone: name: Joe Bloggs avatar: @@ -8983,6 +8987,7 @@ paths: external_id: role: user email: joebloggs@intercom.io + email_verified: false phone: name: avatar: @@ -9143,6 +9148,7 @@ paths: external_id: '70' role: user email: joe@bloggs.com + email_verified: false phone: name: Joe Bloggs avatar: @@ -21547,6 +21553,7 @@ paths: external_id: role: user email: foo@bar.com + email_verified: false phone: name: avatar: From 4ef718dbab4941fe20abb05d201b8c44de6612eb Mon Sep 17 00:00:00 2001 From: dq Date: Wed, 23 Sep 2026 12:59:51 +0100 Subject: [PATCH 03/13] Limit the response field to the Preview description The contact object returns email_verified on Preview only, so the released 2.16 description should not advertise it. --- descriptions/2.16/api.intercom.io.yaml | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index 45614d01..75272ea0 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -8070,7 +8070,6 @@ paths: external_id: '70' role: user email: joebloggs@intercom.io - email_verified: false phone: name: joe bloggs avatar: @@ -8159,7 +8158,6 @@ paths: external_id: '70' role: user email: joebloggs@intercom.io - email_verified: false phone: name: joe bloggs avatar: @@ -8353,7 +8351,6 @@ paths: external_id: '70' role: user email: joe@bloggs.com - email_verified: false phone: name: Joe Bloggs avatar: @@ -8561,7 +8558,6 @@ paths: external_id: '70' role: user email: joe@bloggs.com - email_verified: false phone: name: Joe Bloggs avatar: @@ -8987,7 +8983,6 @@ paths: external_id: role: user email: joebloggs@intercom.io - email_verified: false phone: name: avatar: @@ -9148,7 +9143,6 @@ paths: external_id: '70' role: user email: joe@bloggs.com - email_verified: false phone: name: Joe Bloggs avatar: @@ -21553,7 +21547,6 @@ paths: external_id: role: user email: foo@bar.com - email_verified: false phone: name: avatar: @@ -25300,11 +25293,6 @@ components: type: string description: The contact's email domain. example: example.com - email_verified: - type: boolean - description: Whether the contact's email address has been verified. This - is false if the contact's email has changed since it was last verified. - example: true phone: type: string nullable: true From 9a49f3e6b2e2ccfa40f8ce1695a226447db52785 Mon Sep 17 00:00:00 2001 From: dq Date: Wed, 23 Sep 2026 13:28:22 +0100 Subject: [PATCH 04/13] Say what a verified email actually means "Has been verified" read as though we had checked the address ourselves. It can equally be your own assertion, so the description now names both origins and says the field does not distinguish them. --- descriptions/0/api.intercom.io.yaml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index ec50cca7..c378077f 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -31298,8 +31298,7 @@ components: example: example.com email_verified: type: boolean - description: Whether the contact's email address has been verified. This - is false if the contact's email has changed since it was last verified. + description: Whether the contact's email address has been verified as belonging to them. Verification can come from either side. You set it yourself when you create or update the contact, or when you identify them to the Messenger or a mobile SDK with a signed identity. Intercom sets it when it sees the contact prove they control the address, such as entering a one-time code sent to it, or emailing in from it with passing sender domain authentication. This field does not say which of those happened, so treat a true value as only as strong as the verification behind it. It is false if the address has never been verified, and it returns to false if the contact's email changes, until the new address is verified. example: true phone: type: string From edcd1abdf373b96bb9be321525d29293d1a342e6 Mon Sep 17 00:00:00 2001 From: dq Date: Wed, 23 Sep 2026 13:30:29 +0100 Subject: [PATCH 05/13] Correct what inbound mail proves about a verified address Mail arriving from an address marks it verified on its own, so the previous wording overstated the evidence by tying it to sender domain authentication. Also names file import, and drops the signed-identity routes, which are not available to every workspace. --- descriptions/0/api.intercom.io.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index c378077f..8dc930f1 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -31298,7 +31298,7 @@ components: example: example.com email_verified: type: boolean - description: Whether the contact's email address has been verified as belonging to them. Verification can come from either side. You set it yourself when you create or update the contact, or when you identify them to the Messenger or a mobile SDK with a signed identity. Intercom sets it when it sees the contact prove they control the address, such as entering a one-time code sent to it, or emailing in from it with passing sender domain authentication. This field does not say which of those happened, so treat a true value as only as strong as the verification behind it. It is false if the address has never been verified, and it returns to false if the contact's email changes, until the new address is verified. + description: Whether the contact's email address is marked as verified. This can come from you, by setting email_verified to true when you create or update the contact or by importing the contact from a file, or from Intercom, when the contact confirms the address themselves, such as by entering a one-time code sent to it. Receiving mail from the address can also mark it verified, which is weaker evidence, because it reflects only who the message claimed to be from. The field does not say which route produced it, so treat a true value as a record that the address was verified somewhere rather than as proof the contact owns it. It is false if the address has never been verified, and it returns to false if the contact's email changes, until the new address is verified. example: true phone: type: string From 875cbffcea4f13b77bcc2ee2b7f9ec1ee0ea14b0 Mon Sep 17 00:00:00 2001 From: dq Date: Wed, 23 Sep 2026 13:42:06 +0100 Subject: [PATCH 06/13] Name only the routes that actually set the field The previous wording described routes that are not reachable today, which read as behaviour rather than intent. --- descriptions/0/api.intercom.io.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 8dc930f1..d67a75bb 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -31298,7 +31298,7 @@ components: example: example.com email_verified: type: boolean - description: Whether the contact's email address is marked as verified. This can come from you, by setting email_verified to true when you create or update the contact or by importing the contact from a file, or from Intercom, when the contact confirms the address themselves, such as by entering a one-time code sent to it. Receiving mail from the address can also mark it verified, which is weaker evidence, because it reflects only who the message claimed to be from. The field does not say which route produced it, so treat a true value as a record that the address was verified somewhere rather than as proof the contact owns it. It is false if the address has never been verified, and it returns to false if the contact's email changes, until the new address is verified. + description: Whether the contact's email address is marked as verified. It is set when the public API marks it as verified on contact create or update, when the contact is imported from a CSV in the help desk, or when the contact is created from mail arriving from that address. It is false if the address has never been verified, and it returns to false if the contact's email changes, until the new address is verified. example: true phone: type: string From 2a263bbad8b1ae9e6153815faa1750353b24dc56 Mon Sep 17 00:00:00 2001 From: dq Date: Mon, 28 Sep 2026 09:43:37 +0100 Subject: [PATCH 07/13] Rewrite email_verified request and response descriptions for accuracy Correct the request-side semantics on the create and update contact request schemas for the 2.16 and Preview specs, and correct the Preview-only response field description on the contact schema to drop the CSV-import and inbound-mail claims that no longer apply. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01X52yaGBxmKCTMiXQG8rBKe --- descriptions/0/api.intercom.io.yaml | 6 +++--- descriptions/2.16/api.intercom.io.yaml | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index d0d47394..80ccca58 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -31469,7 +31469,7 @@ components: example: example.com email_verified: type: boolean - description: Whether the contact's email address is marked as verified. It is set when the public API marks it as verified on contact create or update, when the contact is imported from a CSV in the help desk, or when the contact is created from mail arriving from that address. It is false if the address has never been verified, and it returns to false if the contact's email changes, until the new address is verified. + description: Whether the contact's current email address has been verified. True only when this address was verified through the Contacts API and has not changed since; a contact whose email came from another Intercom feature or another API, such as a lead created from inbound email or from the Conversations or Tickets APIs, reads false here even though Intercom may still match it by email. Becomes false again if the contact's email changes, until the new address is verified. Only returned on the Preview version; not present on any released API version. example: true phone: type: string @@ -34848,7 +34848,7 @@ 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's email address has been verified. Set to true, together with an email in the same request, to record that you have verified the contact owns that address; this replaces any earlier verification state for the contact. Set to false to mark the address as unverified. Omit it, or send null, to leave the contact's current verification state unchanged — a newly created contact starts unverified. A lead with a verified email is reused when Intercom later matches an inbound email, or an outbound conversation or ticket, to that address, instead of creating a new lead. Sending email_verified without an email in the same request returns a 400. example: true phone: type: string @@ -43124,7 +43124,7 @@ 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's email address has been verified. Set to true, together with an email in the same request, to record that you have verified the contact owns that address; this replaces any earlier verification state for the contact. Set to false to mark the address as unverified. Omit it, or send null, to leave the contact's current verification state unchanged — a newly created contact starts unverified. A lead with a verified email is reused when Intercom later matches an inbound email, or an outbound conversation or ticket, to that address, instead of creating a new lead. Sending email_verified without an email in the same request returns a 400. example: true phone: type: string diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index 339239b7..45d209b3 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -28100,7 +28100,7 @@ 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's email address has been verified. Set to true, together with an email in the same request, to record that you have verified the contact owns that address; this replaces any earlier verification state for the contact. Set to false to mark the address as unverified. Omit it, or send null, to leave the contact's current verification state unchanged — a newly created contact starts unverified. A lead with a verified email is reused when Intercom later matches an inbound email, or an outbound conversation or ticket, to that address, instead of creating a new lead. Sending email_verified without an email in the same request returns a 400. example: true email: type: string @@ -34839,7 +34839,7 @@ 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's email address has been verified. Set to true, together with an email in the same request, to record that you have verified the contact owns that address; this replaces any earlier verification state for the contact. Set to false to mark the address as unverified. Omit it, or send null, to leave the contact's current verification state unchanged — a newly created contact starts unverified. A lead with a verified email is reused when Intercom later matches an inbound email, or an outbound conversation or ticket, to that address, instead of creating a new lead. Sending email_verified without an email in the same request returns a 400. example: true phone: type: string From b6778a87398a3f500ac61ebb19410a762ad35d9e Mon Sep 17 00:00:00 2001 From: dq Date: Mon, 28 Sep 2026 11:16:13 +0100 Subject: [PATCH 08/13] Reframe email_verified descriptions around proof of ownership Describe the request and response fields in terms of proving ownership of an email address rather than a bare verified/unverified state, with a worked request-body example. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01X52yaGBxmKCTMiXQG8rBKe --- descriptions/0/api.intercom.io.yaml | 9 ++++++--- descriptions/2.16/api.intercom.io.yaml | 6 ++++-- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 80ccca58..c3d1183c 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -31469,7 +31469,8 @@ components: example: example.com email_verified: type: boolean - description: Whether the contact's current email address has been verified. True only when this address was verified through the Contacts API and has not changed since; a contact whose email came from another Intercom feature or another API, such as a lead created from inbound email or from the Conversations or Tickets APIs, reads false here even though Intercom may still match it by email. Becomes false again if the contact's email changes, until the new address is verified. Only returned on the Preview version; not present on any released API version. + 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 @@ -34848,7 +34849,8 @@ components: email_verified: type: boolean nullable: true - description: Whether the contact's email address has been verified. Set to true, together with an email in the same request, to record that you have verified the contact owns that address; this replaces any earlier verification state for the contact. Set to false to mark the address as unverified. Omit it, or send null, to leave the contact's current verification state unchanged — a newly created contact starts unverified. A lead with a verified email is reused when Intercom later matches an inbound email, or an outbound conversation or ticket, to that address, instead of creating a new lead. Sending email_verified without an email in the same request returns a 400. + 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. To record that proof, send `email_verified: true` together with `email` in the same request, for example `{"email": "jane@example.com", "email_verified": true}`. Send `email_verified: false` to record that ownership is not proved. `email_verified` must be sent alongside `email` in the same request; a request that includes `email_verified` without `email` fails with a `400`. Omit the field to leave the contact's current state unchanged. Only send `true` when you hold that proof: 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. example: true phone: type: string @@ -43124,7 +43126,8 @@ components: email_verified: type: boolean nullable: true - description: Whether the contact's email address has been verified. Set to true, together with an email in the same request, to record that you have verified the contact owns that address; this replaces any earlier verification state for the contact. Set to false to mark the address as unverified. Omit it, or send null, to leave the contact's current verification state unchanged — a newly created contact starts unverified. A lead with a verified email is reused when Intercom later matches an inbound email, or an outbound conversation or ticket, to that address, instead of creating a new lead. Sending email_verified without an email in the same request returns a 400. + 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. To record that proof, send `email_verified: true` together with `email` in the same request, for example `{"email": "jane@example.com", "email_verified": true}`. Send `email_verified: false` to record that ownership is not proved. `email_verified` must be sent alongside `email` in the same request; a request that includes `email_verified` without `email` fails with a `400`. Omit the field to leave the contact's current state unchanged. Only send `true` when you hold that proof: 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. example: true phone: type: string diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index 45d209b3..c78e9aab 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -28100,7 +28100,8 @@ components: email_verified: type: boolean nullable: true - description: Whether the contact's email address has been verified. Set to true, together with an email in the same request, to record that you have verified the contact owns that address; this replaces any earlier verification state for the contact. Set to false to mark the address as unverified. Omit it, or send null, to leave the contact's current verification state unchanged — a newly created contact starts unverified. A lead with a verified email is reused when Intercom later matches an inbound email, or an outbound conversation or ticket, to that address, instead of creating a new lead. Sending email_verified without an email in the same request returns a 400. + 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. To record that proof, send `email_verified: true` together with `email` in the same request, for example `{"email": "jane@example.com", "email_verified": true}`. Send `email_verified: false` to record that ownership is not proved. `email_verified` must be sent alongside `email` in the same request; a request that includes `email_verified` without `email` fails with a `400`. Omit the field to leave the contact's current state unchanged. Only send `true` when you hold that proof: 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. example: true email: type: string @@ -34839,7 +34840,8 @@ components: email_verified: type: boolean nullable: true - description: Whether the contact's email address has been verified. Set to true, together with an email in the same request, to record that you have verified the contact owns that address; this replaces any earlier verification state for the contact. Set to false to mark the address as unverified. Omit it, or send null, to leave the contact's current verification state unchanged — a newly created contact starts unverified. A lead with a verified email is reused when Intercom later matches an inbound email, or an outbound conversation or ticket, to that address, instead of creating a new lead. Sending email_verified without an email in the same request returns a 400. + 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. To record that proof, send `email_verified: true` together with `email` in the same request, for example `{"email": "jane@example.com", "email_verified": true}`. Send `email_verified: false` to record that ownership is not proved. `email_verified` must be sent alongside `email` in the same request; a request that includes `email_verified` without `email` fails with a `400`. Omit the field to leave the contact's current state unchanged. Only send `true` when you hold that proof: 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. example: true phone: type: string From 63dfc4059f68c8acc6ffbd04fa385ab1971b20b4 Mon Sep 17 00:00:00 2001 From: dq Date: Mon, 28 Sep 2026 11:19:09 +0100 Subject: [PATCH 09/13] Drop email_verified from the visitor convert response example The convert visitor endpoint does not return the field, so its example should not show it. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01X52yaGBxmKCTMiXQG8rBKe --- descriptions/0/api.intercom.io.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index c3d1183c..007b1049 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -25961,7 +25961,6 @@ paths: external_id: role: user email: foo@bar.com - email_verified: false phone: formatted_phone: name: From 1b5420e4cf7a0aff6ce7cda6725ebe09ebb78028 Mon Sep 17 00:00:00 2001 From: dq Date: Mon, 28 Sep 2026 11:38:19 +0100 Subject: [PATCH 10/13] Say what omitting email_verified means on create as well as update Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01X52yaGBxmKCTMiXQG8rBKe --- descriptions/0/api.intercom.io.yaml | 4 ++-- descriptions/2.16/api.intercom.io.yaml | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 007b1049..d1250c7d 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -34849,7 +34849,7 @@ components: type: boolean nullable: true 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. To record that proof, send `email_verified: true` together with `email` in the same request, for example `{"email": "jane@example.com", "email_verified": true}`. Send `email_verified: false` to record that ownership is not proved. `email_verified` must be sent alongside `email` in the same request; a request that includes `email_verified` without `email` fails with a `400`. Omit the field to leave the contact's current state unchanged. Only send `true` when you hold that proof: 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. + 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. To record that proof, send `email_verified: true` together with `email` in the same request, for example `{"email": "jane@example.com", "email_verified": true}`. Send `email_verified: false` to record that ownership is not proved. `email_verified` must be sent alongside `email` in the same request; a request that includes `email_verified` without `email` fails with a `400`. Omit the field to leave the contact's verification state unchanged; a newly created contact starts unverified. Only send `true` when you hold that proof: 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. example: true phone: type: string @@ -43126,7 +43126,7 @@ components: type: boolean nullable: true 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. To record that proof, send `email_verified: true` together with `email` in the same request, for example `{"email": "jane@example.com", "email_verified": true}`. Send `email_verified: false` to record that ownership is not proved. `email_verified` must be sent alongside `email` in the same request; a request that includes `email_verified` without `email` fails with a `400`. Omit the field to leave the contact's current state unchanged. Only send `true` when you hold that proof: 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. + 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. To record that proof, send `email_verified: true` together with `email` in the same request, for example `{"email": "jane@example.com", "email_verified": true}`. Send `email_verified: false` to record that ownership is not proved. `email_verified` must be sent alongside `email` in the same request; a request that includes `email_verified` without `email` fails with a `400`. Omit the field to leave the contact's verification state unchanged; a newly created contact starts unverified. Only send `true` when you hold that proof: 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. example: true phone: type: string diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index c78e9aab..05be0253 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -28101,7 +28101,7 @@ components: type: boolean nullable: true 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. To record that proof, send `email_verified: true` together with `email` in the same request, for example `{"email": "jane@example.com", "email_verified": true}`. Send `email_verified: false` to record that ownership is not proved. `email_verified` must be sent alongside `email` in the same request; a request that includes `email_verified` without `email` fails with a `400`. Omit the field to leave the contact's current state unchanged. Only send `true` when you hold that proof: 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. + 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. To record that proof, send `email_verified: true` together with `email` in the same request, for example `{"email": "jane@example.com", "email_verified": true}`. Send `email_verified: false` to record that ownership is not proved. `email_verified` must be sent alongside `email` in the same request; a request that includes `email_verified` without `email` fails with a `400`. Omit the field to leave the contact's verification state unchanged; a newly created contact starts unverified. Only send `true` when you hold that proof: 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. example: true email: type: string @@ -34841,7 +34841,7 @@ components: type: boolean nullable: true 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. To record that proof, send `email_verified: true` together with `email` in the same request, for example `{"email": "jane@example.com", "email_verified": true}`. Send `email_verified: false` to record that ownership is not proved. `email_verified` must be sent alongside `email` in the same request; a request that includes `email_verified` without `email` fails with a `400`. Omit the field to leave the contact's current state unchanged. Only send `true` when you hold that proof: 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. + 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. To record that proof, send `email_verified: true` together with `email` in the same request, for example `{"email": "jane@example.com", "email_verified": true}`. Send `email_verified: false` to record that ownership is not proved. `email_verified` must be sent alongside `email` in the same request; a request that includes `email_verified` without `email` fails with a `400`. Omit the field to leave the contact's verification state unchanged; a newly created contact starts unverified. Only send `true` when you hold that proof: 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. example: true phone: type: string From 6a435efcfa8c178c99f580a443c0b5880fd3554c Mon Sep 17 00:00:00 2001 From: dq Date: Mon, 28 Sep 2026 11:41:52 +0100 Subject: [PATCH 11/13] Say what happens to email_verified when a verified contact's email changes Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01X52yaGBxmKCTMiXQG8rBKe --- descriptions/0/api.intercom.io.yaml | 4 ++-- descriptions/2.16/api.intercom.io.yaml | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index d1250c7d..d88cfb02 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -34849,7 +34849,7 @@ components: type: boolean nullable: true 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. To record that proof, send `email_verified: true` together with `email` in the same request, for example `{"email": "jane@example.com", "email_verified": true}`. Send `email_verified: false` to record that ownership is not proved. `email_verified` must be sent alongside `email` in the same request; a request that includes `email_verified` without `email` fails with a `400`. Omit the field to leave the contact's verification state unchanged; a newly created contact starts unverified. Only send `true` when you hold that proof: 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. + 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. To record that proof, send `email_verified: true` together with `email` in the same request, for example `{"email": "jane@example.com", "email_verified": true}`. Send `email_verified: false` to record that ownership is not proved. `email_verified` must be sent alongside `email` in the same request; a request that includes `email_verified` without `email` fails with a `400`. Omit the field to leave verification as it is; a newly created contact starts unverified, and changing a verified contact's email leaves the new address unverified until you verify it. Only send `true` when you hold that proof: 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. example: true phone: type: string @@ -43126,7 +43126,7 @@ components: type: boolean nullable: true 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. To record that proof, send `email_verified: true` together with `email` in the same request, for example `{"email": "jane@example.com", "email_verified": true}`. Send `email_verified: false` to record that ownership is not proved. `email_verified` must be sent alongside `email` in the same request; a request that includes `email_verified` without `email` fails with a `400`. Omit the field to leave the contact's verification state unchanged; a newly created contact starts unverified. Only send `true` when you hold that proof: 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. + 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. To record that proof, send `email_verified: true` together with `email` in the same request, for example `{"email": "jane@example.com", "email_verified": true}`. Send `email_verified: false` to record that ownership is not proved. `email_verified` must be sent alongside `email` in the same request; a request that includes `email_verified` without `email` fails with a `400`. Omit the field to leave verification as it is; a newly created contact starts unverified, and changing a verified contact's email leaves the new address unverified until you verify it. Only send `true` when you hold that proof: 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. example: true phone: type: string diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index 05be0253..c376cfaf 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -28101,7 +28101,7 @@ components: type: boolean nullable: true 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. To record that proof, send `email_verified: true` together with `email` in the same request, for example `{"email": "jane@example.com", "email_verified": true}`. Send `email_verified: false` to record that ownership is not proved. `email_verified` must be sent alongside `email` in the same request; a request that includes `email_verified` without `email` fails with a `400`. Omit the field to leave the contact's verification state unchanged; a newly created contact starts unverified. Only send `true` when you hold that proof: 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. + 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. To record that proof, send `email_verified: true` together with `email` in the same request, for example `{"email": "jane@example.com", "email_verified": true}`. Send `email_verified: false` to record that ownership is not proved. `email_verified` must be sent alongside `email` in the same request; a request that includes `email_verified` without `email` fails with a `400`. Omit the field to leave verification as it is; a newly created contact starts unverified, and changing a verified contact's email leaves the new address unverified until you verify it. Only send `true` when you hold that proof: 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. example: true email: type: string @@ -34841,7 +34841,7 @@ components: type: boolean nullable: true 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. To record that proof, send `email_verified: true` together with `email` in the same request, for example `{"email": "jane@example.com", "email_verified": true}`. Send `email_verified: false` to record that ownership is not proved. `email_verified` must be sent alongside `email` in the same request; a request that includes `email_verified` without `email` fails with a `400`. Omit the field to leave the contact's verification state unchanged; a newly created contact starts unverified. Only send `true` when you hold that proof: 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. + 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. To record that proof, send `email_verified: true` together with `email` in the same request, for example `{"email": "jane@example.com", "email_verified": true}`. Send `email_verified: false` to record that ownership is not proved. `email_verified` must be sent alongside `email` in the same request; a request that includes `email_verified` without `email` fails with a `400`. Omit the field to leave verification as it is; a newly created contact starts unverified, and changing a verified contact's email leaves the new address unverified until you verify it. Only send `true` when you hold that proof: 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. example: true phone: type: string From fe431db0823b2c3769a7b7685766ad03634d4eb0 Mon Sep 17 00:00:00 2001 From: dq Date: Mon, 28 Sep 2026 13:39:02 +0100 Subject: [PATCH 12/13] Show email_verified in the visitor convert response example Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01X52yaGBxmKCTMiXQG8rBKe --- descriptions/0/api.intercom.io.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index d88cfb02..f8a02a66 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -25961,6 +25961,7 @@ paths: external_id: role: user email: foo@bar.com + email_verified: false phone: formatted_phone: name: From c8bb0c0c2391dcecfd992dcdb41f4af6d08a2da8 Mon Sep 17 00:00:00 2001 From: dq Date: Wed, 30 Sep 2026 15:08:20 +0100 Subject: [PATCH 13/13] Simplify the email_verified request field description Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01X52yaGBxmKCTMiXQG8rBKe --- descriptions/0/api.intercom.io.yaml | 20 ++++++++++++++++---- descriptions/2.16/api.intercom.io.yaml | 20 ++++++++++++++++---- 2 files changed, 32 insertions(+), 8 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index f8a02a66..a307db35 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -34849,8 +34849,14 @@ components: email_verified: type: boolean nullable: true - 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. To record that proof, send `email_verified: true` together with `email` in the same request, for example `{"email": "jane@example.com", "email_verified": true}`. Send `email_verified: false` to record that ownership is not proved. `email_verified` must be sent alongside `email` in the same request; a request that includes `email_verified` without `email` fails with a `400`. Omit the field to leave verification as it is; a newly created contact starts unverified, and changing a verified contact's email leaves the new address unverified until you verify it. Only send `true` when you hold that proof: 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. + 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 @@ -43126,8 +43132,14 @@ components: email_verified: type: boolean nullable: true - 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. To record that proof, send `email_verified: true` together with `email` in the same request, for example `{"email": "jane@example.com", "email_verified": true}`. Send `email_verified: false` to record that ownership is not proved. `email_verified` must be sent alongside `email` in the same request; a request that includes `email_verified` without `email` fails with a `400`. Omit the field to leave verification as it is; a newly created contact starts unverified, and changing a verified contact's email leaves the new address unverified until you verify it. Only send `true` when you hold that proof: 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. + 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 diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index c376cfaf..36d3013c 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -28100,8 +28100,14 @@ components: email_verified: type: boolean nullable: true - 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. To record that proof, send `email_verified: true` together with `email` in the same request, for example `{"email": "jane@example.com", "email_verified": true}`. Send `email_verified: false` to record that ownership is not proved. `email_verified` must be sent alongside `email` in the same request; a request that includes `email_verified` without `email` fails with a `400`. Omit the field to leave verification as it is; a newly created contact starts unverified, and changing a verified contact's email leaves the new address unverified until you verify it. Only send `true` when you hold that proof: 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. + 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 @@ -34840,8 +34846,14 @@ components: email_verified: type: boolean nullable: true - 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. To record that proof, send `email_verified: true` together with `email` in the same request, for example `{"email": "jane@example.com", "email_verified": true}`. Send `email_verified: false` to record that ownership is not proved. `email_verified` must be sent alongside `email` in the same request; a request that includes `email_verified` without `email` fails with a `400`. Omit the field to leave verification as it is; a newly created contact starts unverified, and changing a verified contact's email leaves the new address unverified until you verify it. Only send `true` when you hold that proof: 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. + 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