Skip to main content

Hi!  I have a question about which to rely on in the API v2.9 Models documentation: the example JSON object, or the documented fields / field datatypes.  In some cases the inconsistencies can be significant.  For example, in looking at https://developers.intercom.com/intercom-api-reference/reference/the-contact-model I can see the following differences:

  • Documentation does not include the external_id field from the example JSON.
  • Documentation lists avatar as having type object but in the example object it has type string.
  • Documentation does not include the opted_out_subscription_types field from the example JSON.
  • Documentation does not include the opted_in_subscription_types field from the example JSON.
  • Documentation does not include the utm_campaign field from the example JSON.
  • Documentation does not include the utm_content field from the example JSON.
  • Documentation does not include the utm_medium field from the example JSON.
  • Documentation does not include the utm_source field from the example JSON.
  • Documentation does not include the utm_term field from the example JSON.
  • Documentation does not include the referrer field from the example JSON.
  • Example JSON does not include the formatted_phone field from the documentation.

At the very least it would be good for the site / documentation team to fix these inconsistencies; but in the meantime, I’d love to know which is accurate - JSON or documentation table - and whether that’s true not just for the Contact model but other models as well.  (The Contact model doc is the most egregious case of this, but there are a few difference on other pages too.)

Thank you very much in advance for the help!

I’ll quickly mention another page where there are differences between the documentation and the example JSON: the content_stat webhook model documentation at https://developers.intercom.com/intercom-api-reference/reference/webhook-models#content-stat-notification-object.  Every “id” field’s value in the JSON object is an integer, but every such field is documented as having a string type in the table immediately below.  In this case, having tested the webhook, it seems that the JSON object matches what is actually sent and the written documentation is wrong.  Here’s an example I saw in testing:

"content_stat": {
        "id": 3,
        "content_type": "email",
        "content_id": 38663206,
        "stat_type": "receipt",
        "ruleset_id": 34895243,
        "content_title": "test webhook tag",
        "ruleset_version_id": 6451876,
        "receipt_id": 3,
        "tags": {
          "type": "list",
          "has_more": false,
          "data":  
            {
              "id": 8313930,
              "type": "tag",
              "url": "/tags/8313930"
            }
          ],
          "total_count": 1
        }
      },

 

Hey @Gideon Jeffrey Racheal from the support engineer team here👋 

 

I can see you were working with my teammate Oseas on some of this and he has flagged your feedback on the content_stat webhook to the team. As for the API discrepancies I totally understand that this is not very ideal and can cause some confusion. We do, of course, aim to keep our docs up to date as much as possible as our API develops and improves but as you noticed, there are a few fields missing/inaccuracies. I would always suggest making an example GET request to see the data you are getting back before building any projects off of the response. So in the case of The Conversation Model when you make a GET request to the Get a contact endpoint you will see the full response which includes:

  • external_id
  • all subscription_types fields
  • utm fields
  • referrer
  • formatted_phone

Here is an example response with those fields included:

{

  "type": "contact",

  "id": "abc1345",

  "workspace_id": "abc1234",

  "external_id": null,

  "role": "user",

  "email": "testing@example.com",

  "phone": "5551234567",

  "formatted_phone": null,

  "name": null,

  "avatar": null,

  "owner_id": null,

  "social_profiles": {

    "type": "list",

    "data": b]

  },

  "has_hard_bounced": false,

  "marked_email_as_spam": false,

  "unsubscribed_from_emails": false,

  "created_at": 1688690773,

  "updated_at": 1689966806,

  "signed_up_at": 1688690773,

  "last_seen_at": 1689625860,

  "last_replied_at": 1688690780,

  "last_contacted_at": 1689966806,

  "last_email_opened_at": null,

  "last_email_clicked_at": null,

  "language_override": null,

  "browser": "chrome",

  "browser_version": "114.0.0.0",

  "browser_language": "en",

  "os": "OS X 10.15.7",

  "location": {

    "type": "location",

    "country": "United States",

    "region": "Illinois",

    "city": "Chicago",

    "country_code": "USA",

    "continent_code": "NA"

  },

  "android_app_name": null,

  "android_app_version": null,

  "android_device": null,

  "android_os_version": null,

  "android_sdk_version": null,

  "android_last_seen_at": null,

  "ios_app_name": null,

  "ios_app_version": null,

  "ios_device": null,

  "ios_os_version": null,

  "ios_sdk_version": null,

  "ios_last_seen_at": null,

  "custom_attributes": {},

  "tags": {

    "type": "list",

    "data": ],

    "url": "/contacts/abc123/tags",

    "total_count": 0,

    "has_more": false

  },

  "notes": {

    "type": "list",

    "data": }

      {

        "id": "2344",

        "type": "note",

        "url": "/notes/81544231708"

      }

    ],

    "url": "/contacts/abc123/notes",

    "total_count": 1,

    "has_more": false

  },

  "companies": {

    "type": "list",

    "data": _],

    "url": "/contacts/abc123/companies",

    "total_count": 0,

    "has_more": false

  },

  "opted_out_subscription_types": {

    "type": "list",

    "data": r],

    "url": "/contacts/abc123/subscriptions",

    "total_count": 0,

    "has_more": false

  },

  "opted_in_subscription_types": {

    "type": "list",

    "data": ],

    "url": "/contacts/abc123/subscriptions",

    "total_count": 0,

    "has_more": false

  },

  "utm_campaign": null,

  "utm_content": null,

  "utm_medium": null,

  "utm_source": null,

  "utm_term": null,

  "referrer": "https://example.intercom.io/",

  "sms_consent": false,

  "unsubscribed_from_sms": false
 

The avatar field being listed as an object instead of a string definitely seems unintentional to me as I’m not sure when that field was an object- I’m going to go ahead and flag that with the team now as well! I really appreciate you bring this to our attention!

Reply


Terms & ConditionsCookie settings