Below are templates of the responses the Clarabridge Engage API returns for several types of API calls. This gives you an idea on what to expect as a result for your requests.

Eg.: the /me endpoint returns a single User object, wrapped in the standard envelope.

The default and preferred (!) response format for the Clarabridge Engage API is JSON. However we can also return xml if you pass "format=xml" as a GET parameter to our endpoints. Format and members of the XML responses are the same as for JSON responses, with the exception that items of numeric arrays are wrapped in an <item/> element.


Envelope for successful requests Structure of valid responses

  • {
    • "meta":
      • {
        • "code": integer The HTTP Response status code.
        • "messages": [] (optional) Holds an array of non fatal errors or warnings regarding to the request.
        • "etag": string (optional) If you send the HTTP Request Header "ETag/If-None-Match", we will send back a HTTP "Etag" Response Header. When the request & response hashes match, we return an empty "304 Not Modified". The ETag for a certain request will be included in the envelope if a HTTP Request Header "ETag/If-None-Match" is present.
        }
    • "response": The actual response data.
    }

Error responses Structure of fatal error responses

  • {
    • "code": integer The HTTP Response status code.
    • "error": string Unique identifier for the type of error.
      • Possible values: "invalid_parameter", "no_permission", "not_found", "invalid_http_method", "unsupported_language", "internal_server_error", "invalid_protocol"
    • "error_description": string Human readable description of the type of error.
    • "error_details": array (optional) Extra details about the error that occured (relevant id's, etc.).
    }

Objects Available fields for different type of json objects returned by API endpoints

  • {
    • "id": integer Unique identifier of the Clarabridge Engage account.
    • "name": string
    • "expires": integer
    • "expired": boolean (optional)
    • "plan": string
      • Possible values: "starter", "basic", "standard", "professional", "enterprise", "trial", "engagorv1", "free", "special", "reseller", "basicv3", "professionalv3", "enterprisev3", "starterv4", "professionalv4", "teamv4", "enterprisev4", "standard_v5", "enterprise_v5", "casemanagement"
    • "projects": []
    • "users": []
    }
  • {
    • "key": string Identifier of the type of action
      • Possible values: "reply", "comment", "like", "hide_on_service", "delete_on_service", "block_user_on_service", "promote", "approve", "edit", "delete", "publish", "recent_conversations", "privatemessage", "retweet", "quote_tweet", "favorite", "submit", "reblog", "status", "assign", "tags", "sentiment", "note", "case", "mark_as_done", "mark_as_todo", "enable", "disable", "webview", "upvote", "verify", "suggest"
    • "type": string (optional) Is this a link to the api or web application?
      • Possible values: "web", "api"
    • "name": string (optional) Verb describing the action
    • "title": string (optional) Description of the action
    • "link": string Url to where you can do this action
    • "http_method": string HTTP method used for the action
      • Possible values: "GET", "POST", "DELETE"
    • "post_params": string (optional) POST body used for this action
    }
  • {
    • "id": string Clarabridge Engage specific Identifier for this assign note.
    • "content": string The content of the assign note
    • "added_by": string
    • "date":
      • {
        • "added": integer (optional) UNIX Timestamp (in UTC) of when the assign note was added.
        }
    }
  • {
    • "id": integer Unique identifier of the change.
    • "description": string Text describing the change.
    • "type": string The event description.
      • Possible values: "Security_Audit", "getEventStrings"
    • "user":
      • {
        • "id": integer (optional) ID of the user who did this change. Not available if anonymous change/change by Clarabridge Engage system.
        • "name": string (optional) Name of the user who did this change.
        • "email": string (optional) Email of the user who did this change.
        }
    • "password_strength": string (optional) Describes how strong the new password is.
    • "location":
      • {
        • "country": string (optional) The full country name of the new location.
        • "city": string (optional) The city name of the new location.
        • "latitude": float (optional) The latitude of the new location.
        • "longitude": float (optional) The longitude of the new location
        • "continent": string (optional) The continent code of the new location
        }
    • "device":
      • {
        • "platform": string (optional) The platform of the detected device
        • "browser": string (optional) The browser used on the device
        • "browser_version": string (optional) The version of the browser used on the device
        }
    • "dateadd": integer UNIX Timestamp (in UTC) of when the change was made Clarabridge Engage.
    }
  • {
    • "id": string The unique identifier of the Business Hours Schedule.
    • "name": string The name of the Business Hours Schedule.
    • "timezone": string PHP Timezone identifier of the chosen timezone for this Business Hours Schedule.
    • "summary": string The summary of the Business Hours Schedule.
    • "periods": [
      • {
        • "dayofweek": integer Day of the week, Monday is 1, Sunday is 7.
        • "start": string `0000` for midnight, `2300` for 11 pm.
        • "end": string `0000` for midnight, `2300` for 11 pm.
        }
      • {
        • "dayofweek": integer Day of the week, Monday is 1, Sunday is 7.
        • "start": string `0000` for midnight, `2300` for 11 pm.
        • "end": string `0000` for midnight, `2300` for 11 pm.
        }
      ]
      List of periods during which the Business Hours Schedule is active.
    • "date":
      • {
        • "added": integer UNIX Timestamp (in UTC) of when the Business Hours Schedule was first created.
        • "updated": integer UNIX Timestamp (in UTC) of when the Business Hours Schedule was last updated.
        }
    }
  • {
    • "dayofweek": integer Day of the week, Monday is 1, Sunday is 7.
    • "start": string `0000` for midnight, `2300` for 11 pm.
    • "end": string `0000` for midnight, `2300` for 11 pm.
    }
  • {
    • "id": string The unique identifier of the canned response item
    • "name": string The name of the canned response item
    • "message": string The message of the canned response item
    • "formatted_message": string (optional) The message of the canned response item filled in with the details of the contact.
    • "type": string The type of the canned response item
      • Possible values: "text", "csat", "nps", "buttons", "flow", "richtext", "messagetemplate"
    • "labels": array (optional) The list of labels of the canned response item
    • "images": array (optional) The list of images of the canned response item
    • "folder":
      • {
        • "id": string (optional) The id of the folder a canned response is part of
        • "name": string (optional) The id of the folder a canned response is part of
        }
    }
  • {
    • "id": integer The id of the folder
    • "name": string The name of the folder
    • "updated_by": integer User that last updated the folder
    • "created_at": integer UNIX Timestamp (in UTC) when the folder was created
    • "updated_at": integer UNIX Timestamp (in UTC) when the folder was updated
    }

Identifying properties associated with a cxa document.

  • {
    • "document_id": integer Document id
    • "project_id": integer Project id
    • "content_provider_id": integer Content provider Id
    • "master_account_id": integer Master account id
    • "account_id": integer Account id
    }
  • {
    • "id": integer Clarabridge Engage Specific Id for this connected profile.
    • "type": string Type of connected profile. (Also source.service for mentions from this type.)
      • Possible values: "twitter", "facebook", "foursquare_venue", "googleplus", "instagram", "instagram_hashtag", "instagram_ads", "linkedin_group", "pinterest", "rss", "youtube", "mixcloud", "telegram_bot", "tripadvisor", "tumblr_blog", "soundcloud", "vimeo", "linkedin_company", "lithium", "yelp_business", "keywordsearch", "mailservice", "telligent_forum", "instagram_business_profile", "instagram_business_profile_hashtag", "wechat", "twilio", "web", "whatsapp", "viber", "linkedin_company_v2", "email_mailbox", "ditto_brand", "social_case", "social_document"
    • "service_id": string Id of the connected profile on the site.
    • "authorized_connection": boolean Is this an authorized connection, or not?
    • "displayname": string (optional) Display Name of the profile.
    • "username": string (optional) Username of the profile (For Twitter profiles this is the handle.).
    • "avatar": string (optional) Url of avatar image of this connected profile.
    • "provider": string Identification of the source.type field for mentions from this profile.
      • Possible values: "SearchProviderFacebook", "SearchProviderTwitter", "SearchProviderGoogle", "SearchProviderGooglePlus", "SearchProviderFoursquare", "SearchProviderInstagram", "SearchProviderInstagramBusinessProfile", "SearchProviderInstagramAds", "SearchProviderInstagramHashtags", "SearchProviderLinkedInGroups", "SearchProviderLinkedInCompanies", "SearchProviderLinkedInCompaniesV2", "SearchProviderRss", "SearchProviderOmgili", "SearchProviderMoreOver", "SearchProviderTrendiction", "SearchProviderYahoo", "SearchProviderWordpress", "SearchProviderBing", "SearchProviderYoutube", "SearchProviderCustom", "SearchProviderApi", "SearchProviderPinterest", "SearchProviderMixCloud", "SearchProviderTripadvisor", "SearchProviderTumblr", "SearchProviderVimeo", "SearchProviderSoundCloud", "SearchProviderEmail", "SearchProviderLithium", "SearchProviderYelp", "SearchProviderCase", "SearchProviderDocument", "SearchProviderTelegramBot", "SearchProviderTelligent", "SearchProviderWeChat", "SearchProviderTwilio", "SearchProviderWeb", "SearchProviderWhatsApp", "SearchProviderViber"
    • "filters":
      • {
        • "postedby": string (optional) Use this in a filter string to filter on messages posted by this profile. (Only available if it's possible for this profile to post messages itself, which eg. is not the case of a LinkedIn Group.)
        • "postedin": string (optional) Use this in a filter string to filter on messages posted on this profile. (Only available if it's possible for users to post messages on the profile.)
        • "profile": string (optional) Use this in a filter string to filter on all profile related messages (posted by, posted in, mentioning the profile, ...).
        }
    }
  • {
    • "id": string (optional) Unique Clarabridge Engage specific identifier for this contact (unique per account).
    • "name": string (optional) Full name filled in for this contact.
    • "company": string (optional) Company name filled in for this contact.
    • "gender": string (optional) Gender filled in for this contact.
      • Possible values: "", "male", "female"
    • "email": string (optional) Email filled in for this contact (unvalidated, free-text).
    • "phone": string (optional) Phone number filled in for this contact (unvalidated, free-text).
    • "permalink": string Permanent URL to the contact in Clarabridge Engage
    • "address":
      • {
        • "city":
          • {
            • "name": string (optional) City filled in for this contact (unvalidated, free-text).
            }
        • "region":
          • {
            • "name": string (optional) Region filled in for this contact (unvalidated, free-text).
            }
        • "country":
          • {
            • "name": string (optional) Country description chosen for this contact (validated).
            • "code": string (optional) Country code for the country chosen for this contact (ISO 3166-1 country code.).
            }
        }
    • "language": string (optional) ISO 639-1 language code chosen for this contact.
    • "timezone": string (optional) PHP Timezone identifier of the chosen timezone for this contact.
    • "comments": string (optional) Free text area for notes about contact.
    • "socialprofiles": [
      • {
        • "type": string Type of service the social profile is from.
          • Possible values: "twitter", "facebook", "foursquare_venue", "googleplus", "instagram", "instagram_hashtag", "instagram_ads", "linkedin_group", "pinterest", "rss", "youtube", "mixcloud", "telegram_bot", "tripadvisor", "tumblr_blog", "soundcloud", "vimeo", "linkedin_company", "lithium", "yelp_business", "keywordsearch", "mailservice", "telligent_forum", "instagram_business_profile", "instagram_business_profile_hashtag", "wechat", "twilio", "web", "whatsapp", "viber", "linkedin_company_v2", "email_mailbox", "ditto_brand", "social_case", "social_document"
        • "service_id": string Service specific id of the social profile.
        • "username": string (optional) Handle, username or nickname of the social profile.
        • "displayname": string (optional) Full name or name as shown on social service.
        • "avatar": string (optional) Url of avatar image for this social profile.
        • "url": string (optional) Url of the social profile.
        • "location": string (optional) Textual version of social profile's location.
        • "bio": string (optional) Profile's biography or profile description.
        • "counts": [
          • {
            • "description": string Description of the counter
            • "value": integer The value of the counter
            }
          • {
            • "description": string Description of the counter
            • "value": integer The value of the counter
            }
          ] (optional)
        • "action_links": [] (optional) Action links define what actions are possible on this social profile and what links for it are.
        }
      • {
        • "type": string Type of service the social profile is from.
          • Possible values: "twitter", "facebook", "foursquare_venue", "googleplus", "instagram", "instagram_hashtag", "instagram_ads", "linkedin_group", "pinterest", "rss", "youtube", "mixcloud", "telegram_bot", "tripadvisor", "tumblr_blog", "soundcloud", "vimeo", "linkedin_company", "lithium", "yelp_business", "keywordsearch", "mailservice", "telligent_forum", "instagram_business_profile", "instagram_business_profile_hashtag", "wechat", "twilio", "web", "whatsapp", "viber", "linkedin_company_v2", "email_mailbox", "ditto_brand", "social_case", "social_document"
        • "service_id": string Service specific id of the social profile.
        • "username": string (optional) Handle, username or nickname of the social profile.
        • "displayname": string (optional) Full name or name as shown on social service.
        • "avatar": string (optional) Url of avatar image for this social profile.
        • "url": string (optional) Url of the social profile.
        • "location": string (optional) Textual version of social profile's location.
        • "bio": string (optional) Profile's biography or profile description.
        • "counts": [
          • {
            • "description": string Description of the counter
            • "value": integer The value of the counter
            }
          • {
            • "description": string Description of the counter
            • "value": integer The value of the counter
            }
          ] (optional)
        • "action_links": [] (optional) Action links define what actions are possible on this social profile and what links for it are.
        }
      ]
      A list of social profiles coupled to this contact.
    • "tags": array (optional) Array of strings; (smart) tags added to this contact.
    • "customattributes": [
      • {
        • "id": integer Unique Id of the custom attribute
        • "name": string Name of the custom attribute
        • "type": string Type of custom attribute
          • Possible values: "numeric", "string", "enum", "boolean"
        • "allowed_values": array (optional) List of allowed values (for type `enum`). (Only returned when fetching custom attributes definitions, not when returning custom attributes of a contact.
        • "value": The value of the the custom field for a certain contact. (Only set when returning contacts, not when returning custom attribute definitions.)
        }
      • {
        • "id": integer Unique Id of the custom attribute
        • "name": string Name of the custom attribute
        • "type": string Type of custom attribute
          • Possible values: "numeric", "string", "enum", "boolean"
        • "allowed_values": array (optional) List of allowed values (for type `enum`). (Only returned when fetching custom attributes definitions, not when returning custom attributes of a contact.
        • "value": The value of the the custom field for a certain contact. (Only set when returning contacts, not when returning custom attribute definitions.)
        }
      ] (optional)
      A list of extra custom fields for this contact
    • "date":
      • {
        • "added": integer UNIX Timestamp (in UTC) of when the contact was first created.
        • "updated": integer UNIX Timestamp (in UTC) of when the contact was last updated.
        }
    • "action_links": [] (optional) Action links define what actions are possible on this contact.
    }
  • {
    • "id": integer Unique Id of the custom attribute
    • "name": string Name of the custom attribute
    • "type": string Type of custom attribute
      • Possible values: "numeric", "string", "enum", "boolean"
    • "allowed_values": array (optional) List of allowed values (for type `enum`). (Only returned when fetching custom attributes definitions, not when returning custom attributes of a contact.
    • "value": The value of the the custom field for a certain contact. (Only set when returning contacts, not when returning custom attribute definitions.)
    }
  • {
    • "id": string The id of the context item object
    • "type": string The type of the context item object
      • Possible values: "mention", "note", "assign_note"
    • "parent_id": user The id of the context_item that is the parent of this item
    • "object": The object with the detailed information (schema defined by type)
    }
  • {
    • "id": string The unique identifier of the crisis event
    • "name": string The name of the crisis event
    • "created_at": integer UNIX Timestamp (in UTC) when the plan was activated
    • "completed_todo_items": [] (optional) The list of to-do items that are marked as done
    }
  • {
    • "id": string The unique identifier of the to-do item
    • "completed_by": Object: user (optional) The user who marked the to-do item as done
    • "completed_at": integer UNIX Timestamp (in UTC) when the to-do item was marked as done
    }
  • {
    • "id": string The unique identifier of the plan
    • "name": string The name of the plan
    • "account_id": integer The account ID of the plan
    • "summary": array The summary of the plan
    • "description": string The description of the plan
    • "type": string The type of the plan (severity)
      • Possible values: "error", "warning", "info", "success"
    • "instructions": string The instructions of the plan
    • "instructions_html": string The instructions of the plan with formatted HTML links
    • "coordinators": [] (optional) The list of coordinators of the plan
    • "todo_items": [] (optional) The to-do items of the plan
    • "is_active": boolean Whether the plan is currently active
    • "active_event": Object: crisis_event (optional) The active crisis event of the plan (if currently active)
    • "created_at": integer UNIX Timestamp (in UTC) when the plan was created
    • "updated_at": integer UNIX Timestamp (in UTC) when the plan was last updated
    • "action_links": actionlink These action links include one or more links back to the API with a list of allowed actions for the logged-in user.
    }
  • {
    • "id": string The unique identifier of the to-do
    • "description": string The to-do description
    • "description_html": string The to-do description with formatted HTML links
    • "assignee": Object: user (optional) The to-do assignee (if the task is assigned)
    • "action_links": [] These action links include a link back to the API endpoint to update the status of a task.
    }

This is a generic object that's used where cursored resultsets are returned.

  • {
    • "data": [
      • {Object: }
      • {Object: }
      ]
    • "next":
      • {
        • "url": string (optional) API url to previous page in results (if any).
        • "count": integer (optional) How much results can you expect when using the next url
        }
    }
  • {
    • "id": integer Clarabridge Engage Specific Id for this dashboard.
    • "name": string Name of this dashboard.
    • "description": string (optional) Description of this dashboard.
    • "components": [] (optional) List of widgets.
    }
  • {
    • "id": integer Clarabridge Engage Specific Id for this widget.
    • "name": string The name of the dashboard widget.
    • "position":
      • {
        • "column": integer The column this dashboard widget is positioned on (on a grid of 6 columns).
        • "row": integer The row this dashboard widget is positioned on.
        }
    • "size":
      • {
        • "width": integer The width of this dashboard widget. Values 1 to 6 (grid of 6 columns).
        • "height": integer The height of this dashboard widget. 1 = about 150px in Clarabridge Engage.
        }
    • "data": Data of the specific widget. (Note: Structure depends on type of widget!)
    }
  • {
    • "string": string Matching hashtag
    • "indices": array Start and end index of matching string in the message of mention
    • "text": string Matching hashtag without the symbol
    • "filter": string Filter string to use when filtering mentions for this hashtag
    • "url": string Clickthrough url for the entity
    }
  • {
    • "string": string Matching url
    • "indices": array Start and end index of matching string in the message of mention
    • "url": string Clickthrough url for the entity
    • "short_url": string Shortened url
    • "long_url": string Lengthened version of the short_url
    • "display_url": string Shortened version of the long_url field
    }
  • {
    • "string": string Matching user
    • "indices": array Start and end index of matching string in the message of mention
    • "service": string Service type of mentioned user
    • "screen_name": string Display name of the user
    • "filter": string Filter string to use when filtering mentions for this user
    • "url": string Clickthrough url for the entity
    }
  • {
    • "id": string The id of the data field
    • "name": string The attribute name of the data field
    • "value": string The value of the data field
    }
  • {
    • "keys": [
      • {
        • "id": Unique identifier of the key.
        • "text": Textual representation of the key header.
        • "html": HTML representation of the key header.
        }
      • {
        • "id": Unique identifier of the key.
        • "text": Textual representation of the key header.
        • "html": HTML representation of the key header.
        }
      ]
    • "segments": [
      • {
        • "id": Unique identifier of the segment.
        • "text": Textual representation of the segment identifier.
        • "html": HTML representation of the segment identifier.
        }
      • {
        • "id": Unique identifier of the segment.
        • "text": Textual representation of the segment identifier.
        • "html": HTML representation of the segment identifier.
        }
      ]
    • "data": [
      • array Numeric array of values per segment.
      • array Numeric array of values per segment.
      ]
    }

This object describes a data facet. It's used for defining a statistical data API-call. Useful for showing charts or summary tables about your data.

  • {
    • "key":
    • "value":
      • {
        • "field": string (optional) The type of calculation to use as Y-axis/cell value for the chart.
          • Possible values: "mentions", "followers", "followers_average", "timestamps_action_reply_first_average", "timestamps_action_reply_first_in_bh_average", "timestamps_action_reply_first_sum", "timestamps_action_reply_first_in_bh_sum", "timestamps_action_status_first_average", "timestamps_action_status_first_in_bh_average", "timestamps_action_status_first_sum", "timestamps_action_status_first_in_bh_sum", "timestamps_action_assign_first_average", "timestamps_action_assign_first_in_bh_average", "timestamps_action_assign_first_sum", "timestamps_action_assign_first_in_bh_sum", "timestamps_action_first_average", "timestamps_action_first_in_bh_average", "timestamps_action_first_sum", "timestamps_action_first_in_bh_sum", "rating"
        }
    • "segmentation":
      • {
        • "field": string (optional) The mention property/field to compare/segment. (Different rows in a table, series in a chart.)
          • Possible values: "message.language", "message.sentiment", "message.type", "message.entities.video", "message.entities.photo", "message.entities.url", "message.entities.domain", "hashtag", "priority", "feedback_facebook_rating", "author.name", "source.category", "category_parentsonly", "source.domain", "source.profile", "source.profile.postedby", "source.profile.postedin", "source.application", "location.continent", "location.country", "region_state", "location.city", "location.region", "topic.id", "topic.keywords", "custom"
        • "field_values": array (optional) Custom segmentation. If you choose "custom" as "segmentation.field", supply an array of filter query strings to use for the segmentation.
        • "size": integer (optional) The amount of different segments you want.
        }
    • "type": string (optional) The source data type to use for this facet.
      • Possible values: "mentions", "insights"
    }
  • {
    • "name": string The essence of the filter formulated in a name.
    • "filter": string The value that should be passed to the filter-parameter in the inbox.
    }
  • {
    • "id": integer Unique identifier of the change.
    • "type": string Type of change.
      • Possible values: "project_add", "project_edit", "project_delete", "query_add", "query_edit", "query_delete", "user_add", "user_edit", "user_delete", "query_connectedservice_add", "query_connectedservice_delete", "account_plan_edit", "user_enable", "user_disable", "account_volume_warning", "account_volume_blocked", "account_volume_reset", "mention_delete", "custom_error", "user_custom_role_add", "user_custom_role_edit", "user_custom_role_delete", "automation_rule_add", "automation_rule_edit", "automation_rule_delete", "saved_search_add", "saved_search_edit", "saved_search_delete", "chart_template_add", "chart_template_edit", "chart_template_delete", "project_demodata_add", "project_demodata_edit", "project_demodata_delete", "dashboard_add", "dashboard_edit", "dashboard_delete", "dashboard_component_add", "dashboard_component_edit", "dashboard_component_delete", "cannedresponses_add", "cannedresponses_edit", "cannedresponses_delete", "cannedrespones_copy", "cannedresponses_folder_add", "cannedresponses_folder_edit", "cannedresponses_folder_delete", "cannedresponses_folder_change", "cannedresponses_status_change", "account_tag_add", "account_tag_edit", "account_tag_delete", "account_integration_add", "account_integration_edit", "account_integration_delete", "mention_restore", "account_integration_restore", "account_customfield_add", "account_customfield_edit", "account_customfield_delete", "account_connectedservice_add", "account_connectedservice_delete", "service_mention_delete", "mailbox_add", "mailbox_edit", "mailbox_delete", "mailbox_folder_add", "mailbox_folder_edit", "mailbox_folder_delete", "service_resolve_all", "mailbox_folder_watchdog_add", "mailbox_folder_watchdog_edit", "mailbox_folder_watchdog_delete", "account_businesshoursschedules_add", "account_businesshoursschedules_edit", "account_businesshoursschedules_delete", "account_businesshoursschedules_holiday_add", "account_businesshoursschedules_holiday_delete", "account_teams_add", "account_teams_edit", "account_teams_delete", "account_teams_user_add", "account_teams_user_delete", "automation_rule_status", "project_restore", "query_restore", "user_role_change", "user_businesshours_change", "query_connectedservice_edit", "security_user_locked", "security_user_unlocked", "automation_rule_restore", "account_connectedservice_edit", "dashboard_restore", "dashboard_component_restore", "query_mention_add", "security_settings_changed", "publishingguideline_add", "publishingguideline_edit", "publishingguideline_delete", "publishingguideline_status_change", "query_cxa_stream_add", "query_cxa_stream_delete", "query_cxa_stream_edit", "query_stream_edit", "account_tag_archive", "account_tag_unarchive", "account_crisis_plans_add", "account_crisis_plans_edit", "account_crisis_plans_delete", "account_crisis_plans_restore", "account_profilemanager_theme_add", "account_profilemanager_theme_edit", "account_profilemanager_theme_delete", "account_profilemanager_scheduled_settings_add", "account_profilemanager_scheduled_settings_delete", "account_profilemanager_scheduled_settings_edit", "account_profilemanager_twitter_profile_edit", "account_twitter_custom_profile_add", "account_twitter_custom_profile_delete", "account_twitter_custom_profile_terms_confirmed", "cannedresponses_add_label", "cannedresponses_remove_labels", "account_social_profiles_group_add", "account_social_profiles_group_edit", "account_social_profiles_group_delete", "connectedservice_expired", "query_connectedservice_auth_refresh", "account_custom_badges_add", "account_custom_badges_edit", "account_custom_badges_delete", "saved_search_restore", "account_email_template_edit", "account_delete_contact_details", "account_cxa_integration_add", "account_cxa_integration_edit", "account_cxa_integration_delete", "account_cxa_integration_start_dates_add", "account_cxa_integration_start_dates_edit", "account_cxa_integration_sync_tags", "account_cxa_integration_sync_attributes", "account_hardlocking_edit", "account_whitelabel_edit", "auto_case_creation_rule_add", "auto_case_creation_rule_edit", "auto_case_creation_rule_delete", "auto_case_creation_rule_restore"
    • "description": string Text describing the change.
    • "topic":
      • {
        • "id": integer (optional) ID of the topic this change is related to.
        • "name": string (optional) Name of the topic this change is related to.
        }
    • "project":
      • {
        • "id": integer (optional) ID of the project this change is related to.
        • "name": string (optional) Name of the project this change is related to.
        }
    • "user":
      • {
        • "id": integer (optional) ID of the user who did this change. Not available if anonymous change/change by Clarabridge Engage system.
        • "name": string (optional) Name of the user who did this change.
        • "email": string (optional) Email of the user who did this change.
        }
    • "ip": string (optional) IP of where the change was made from. (Only available since January 2015.)
    • "date":
      • {
        • "added": integer UNIX Timestamp (in UTC) of when the change was made Clarabridge Engage.
        }
    }
  • {
    • "code": string ISO 639-1 language code.
    • "name": string Textual representation of the language, in English.
    }
  • {
    • "coordinates":
      • {
        • "longitude": float (optional)
        • "latitude": float (optional)
        }
    • "city":
      • {
        • "name": string (optional)
        • "timezone": string (optional)
        • "population": integer (optional)
        }
    • "region":
      • {
        • "name": string (optional)
        • "timezone": string (optional)
        • "population": integer (optional)
        }
    • "country":
      • {
        • "code": string ISO 3166-1 country code.
        • "name": string
        • "timezone": string
        • "population": integer (optional)
        }
    }
  • {
    • "key": string Identifier of the mailbox
    • "name": string Name of the mailbox
    • "folders": [
      • {
        • "key": string Identifier of the folder in the mailbox
        • "name": string Name of the folder
        • "data_type": string Describes the type of data that is in this folder
          • Possible values: "mentions", "publisher"
        • "topics": array List of topic id's
        • "filter": string Filter string
        • "action_links": [] These action links include a link back to the API endpoint to fetch the mentions in this folder (with the right arguments).
        • "subfolders": array (optional) Possible subfolders (these have the same structure as folders)
        }
      • {
        • "key": string Identifier of the folder in the mailbox
        • "name": string Name of the folder
        • "data_type": string Describes the type of data that is in this folder
          • Possible values: "mentions", "publisher"
        • "topics": array List of topic id's
        • "filter": string Filter string
        • "action_links": [] These action links include a link back to the API endpoint to fetch the mentions in this folder (with the right arguments).
        • "subfolders": array (optional) Possible subfolders (these have the same structure as folders)
        }
      ]
      A list of folders for this mailbox.
    }

This object represents a single mention as tracked by Clarabridge Engage.
(For Tweets we're only allowed to return the Clarabridge Engage specific data and the Twitter Tweet ID, see Twitter Api Terms, use this endpoint to look up multiple tweets at once. Read more)

  • {
    • "id": string Clarabridge Engage specific Identifier for this mention (unique per topic).
    • "unique_id": string Clarabridge Engage specific Identifier for this mention.
    • "author":
      • {
        • "name": string (optional) Username or handle of the author of the mention.
        • "fullname": string (optional) Full name of the author of the mention.
        • "id": string (optional) Service specific identifier of the author (eg. Twitter UID).
        • "url": string (optional) Url to the profile page of the author.
        • "img": string (optional) Url to the avatar of the author.
        • "tags": array (optional) Array of strings; tags added to the author of this mention.
        }
    • "original_author":
      • {
        • "name": string (optional) Username or handle of the original author of the mention. (In case this is a retweet, repin, ...)
        • "fullname": string (optional) Full name of the original author of the mention.
        • "id": string (optional) Service specific identifier of the original author (eg. Twitter UID).
        • "url": string (optional) Url to the profile page of the original author.
        • "img": string (optional) Url to the avatar of the original author.
        }
    • "message":
      • {
        • "title": string (optional)
        • "content": string
        • "entities": Entities found in the message's content field
        • "attachments": [] (optional)
        • "language": string ISO 639-1 language code of the language this message is in.
        • "sentiment": string Any of positive, negative, neutral or unset.
        • "type": string (optional) Type of message.
          • Possible values: "post", "privatemessage", "video", "checkin", "photo", "text", "quote", "link", "chat", "audio", "email", "review", "applause", "like", "retweet", "shared", "repin", "user_favorite", "reblog", "engagement", "comment", "reply", "tips", "answer", "postcard", "listed", "case", "live_chat", "document", "user_tweet", "user_mention", "normal", "other"
        }
    • "source":
      • {
        • "category": string Category this mention can be classified under.
          • Possible values: "social", "social_videos", "social_photos", "microblogs", "forums", "blogs", "podcasts", "comments", "news", "news_academic", "news_consumer", "news_corporate", "news_government", "news_journal", "news_local", "news_national", "news_organisation", "news_presswire", "news_trade", "wikis", "reviews", "classifieds", "qa", "email", "case"
        • "service": string What "connected service" source the mention is coming from.
          • Possible values: "twitter", "facebook", "foursquare_venue", "googleplus", "instagram", "instagram_hashtag", "instagram_ads", "linkedin_group", "pinterest", "rss", "youtube", "mixcloud", "telegram_bot", "tripadvisor", "tumblr_blog", "soundcloud", "vimeo", "linkedin_company", "lithium", "yelp_business", "keywordsearch", "mailservice", "telligent_forum", "instagram_business_profile", "instagram_business_profile_hashtag", "wechat", "twilio", "web", "whatsapp", "viber", "linkedin_company_v2", "email_mailbox", "ditto_brand", "social_case", "social_document"
        • "type": string What source the mention is coming from. (Internal name for filtering.)
          • Possible values: "SearchProviderFacebook", "SearchProviderTwitter", "SearchProviderGoogle", "SearchProviderGooglePlus", "SearchProviderFoursquare", "SearchProviderInstagram", "SearchProviderInstagramBusinessProfile", "SearchProviderInstagramAds", "SearchProviderInstagramHashtags", "SearchProviderLinkedInGroups", "SearchProviderLinkedInCompanies", "SearchProviderLinkedInCompaniesV2", "SearchProviderRss", "SearchProviderOmgili", "SearchProviderMoreOver", "SearchProviderTrendiction", "SearchProviderYahoo", "SearchProviderWordpress", "SearchProviderBing", "SearchProviderYoutube", "SearchProviderCustom", "SearchProviderApi", "SearchProviderPinterest", "SearchProviderMixCloud", "SearchProviderTripadvisor", "SearchProviderTumblr", "SearchProviderVimeo", "SearchProviderSoundCloud", "SearchProviderEmail", "SearchProviderLithium", "SearchProviderYelp", "SearchProviderCase", "SearchProviderDocument", "SearchProviderTelegramBot", "SearchProviderTelligent", "SearchProviderWeChat", "SearchProviderTwilio", "SearchProviderWeb", "SearchProviderWhatsApp", "SearchProviderViber"
        • "id": string (optional) Identification of this message on the service it's from. (Eg. the tweet ID for a Twitter message.)
        • "in_reply_to_message_id": string (optional) Unique identifier of the message this message is a reply/comment on.
        • "domain": string
        • "url": string (optional) The URL of the message on the service it's from. (E.g. the link to the comment on Facebook itself.)
        • "application": string (optional) Application or client this message was posted with.
        • "profile": string (optional) Identifier of the profile this mention was found on. (eg. Facebook page, Forum, ...)
        • "profile_name": string (optional) Name/title of the profile/category/forum this message was posted on. Eg. the id of the Facebook Page, the id of the Pinterest Board, ...
        • "identifiers":
        }
    • "location":
      • {
        • "continent": string (optional) Continent code
        • "country": string (optional) ISO 3166-1 country code.
        • "city": string (optional) Full name of the city.
        • "region": string (optional)
        • "longitude": float (optional)
        • "latitude": float (optional)
        }
    • "tags": array (optional) Array of strings; (smart) tags added to this mention.
    • "topic":
      • {
        • "id": integer
        • "name": string
        }
    • "project":
      • {
        • "id": integer
        • "name": string
        }
    • "status": string In the API, mention status "done" corresponds to a mention that was resolved by a Clarabridge Engage end-user. On the other hand, "new" is a message that is still unresolved in Clarabridge Engage.
      • Possible values: "done", "new"
    • "permalink": string Clarabridge Engage specific-url unique to this mention.
    • "assignment":
      • {
        • "user_ids": array Array of (integer) UIDs this mention is assigned to.
        • "team_ids": array Array of (integer) team IDs this mention is assigned to.
        • "comments": string The comment on the most recent assignment.
        }
    • "actions": []
    • "action_links": [] Action links define what actions are possible on this mention and what links for it are.
    • "timestamps":
      • {
        • "response_time": integer (optional) The time between date.published and the first reply (if any), in seconds.
        • "response_time_during_bh": integer (optional) The time (during business hours) between date.published and the first reply (if any), in seconds.
        • "resolve_time": integer (optional) The time between date.published and the first resolve date (if any), in seconds.
        • "resolve_time_during_bh": integer (optional) The time (during business hours) between date.published and the first resolve date (if any), in seconds.
        • "handle_time": integer (optional) The total time spent handling this message, in seconds.
        }
    • "date":
      • {
        • "added": integer UNIX Timestamp (in UTC) of when the post was indexed by Clarabridge Engage.
        • "published": integer (optional) UNIX Timestamp (in UTC) of when the post was published.
        }
    • "priority": priority (optional)
    • "extra_attributes": [] (optional) Extra fields with details about the mention.
    }
  • {
    • "user":
      • {
        • "id": string UID of the user who did the action.
        • "name": string Full name of the user who did the action.
        }
    • "type": string Textual representation of the type of action.
      • Possible values: "tag", "assign", "status", "note", "reply", "sentiment", "like", "retweet", "favorite", "automationtriggered", "property", "email", "delete_on_service", "hide_on_service", "create_case_on_service", "block_on_service", "triggered_by_alert", "case_linked", "case_unlinked", "post_created", "upvote", "verify", "suggest", "post_awaitingapproval_created", "post_draft_created", "case_created", "csat_reply", "nps_reply", "handover_on_service", "multiple_choice", "rebut"
    • "description": string Textual description of the action taken.
    • "details": string (optional) Extra information (eg. the note when "Note Added" action)
    • "date":
      • {
        • "added": integer UNIX Timestamp (in UTC).
        }
    }
  • {
    • "type": string Type of the attachment (photo, url, other)
    • "url": string (optional) Url of the attachment (the link, the photo, ...)
    • "title": string (optional)
    • "image": string (optional) Url of the image of the attachment
    • "description": string (optional)
    • "caption": string (optional)
    • "question": string (optional) Question sent along with the CSAT or NPS response.
    • "id": integer (optional) The id of the image of the attachment
    • "content": (optional) The content of the attachment (E.g. for `dm_deeplink` this will be `true`)
    }
  • {
    • "level": string (optional) Is this an error (non-fatal) or a warning?
      • Possible values: "error", "info", "success", "warning"
    • "code": string (optional) This is for non fatal error & warning messages. (Eg. when using deprecated methods.)
    • "description": string (optional)
    • "details": array (optional) Extra details about the error that occured.
    • "show_user": boolean (optional) Should you show this message to the user?
    }
  • {
    • "id": string Clarabridge Engage specific Identifier for this note.
    • "content": string The content of the note
    • "added_by": user
    • "date":
      • {
        • "added": integer (optional) UNIX Timestamp (in UTC) of when the note was added.
        }
    }

This is a generic object that's used where paginated resultsets are returned.

  • {
    • "count": integer Total count of results.
    • "data": [
      • {Object: }
      • {Object: }
      ]
    • "paging":
      • {
        • "next_url": string (optional) Absolute API url to next page in results (if any). (Some paged lists are limited in how many pages you can request for performance reasons; `next_url` will be empty if you've reached the last available page.)
        • "previous_url": string (optional) Absolute API url to previous page in results (if any).
        }
    }
  • {
    • "id": integer The priority of a case (0 to 10).
    • "name": string The priority level of a case.
    • "color": string The color of the priority level of a case.
    }
  • {
    • "id": string Unique identifier for the Profile Group.
    • "name": string Name of the Profile Group.
    • "profiles_count": integer The total number of profiles in this group.
    • "date":
      • {
        • "updated": integer UNIX Timestamp (in UTC) of when the group was last updated.
        • "added": integer UNIX Timestamp (in UTC) of when the group was first created.
        }
    • "profiles": [] The list of profiles in this group.
    }
  • {
    • "id": integer Unique identifier of the project.
    • "name": string
    • "visible": boolean Is this project visible to the user?
    • "topics": []
    }

This object represents a collection of posts from the publisher.

  • {
    • "id": string Clarabridge Engage specific Identifier for this publisher mention.
    • "author":
    • "message":
      • {
        • "title": string (optional)
        • "content": string
        • "type": string (optional) Type of message (source specific, eg. "retweet", or "like").
        • "attachments": [] (optional)
        • "permalink": string Clarabridge Engage specific-url unique to this mention.
        • "status": string Status of message (eg. "draft", "posted")
        }
    • "assignment":
      • {
        • "user_ids": array Array of UIDs this publisher mention is assigned to.
        • "comments": string The comment on the most recent assignment.
        }
    • "tags": array (optional) Array of strings; (smart) tags added to this mention.
    • "date":
      • {
        • "added": integer UNIX Timestamp (in UTC) of when the post was first created in Clarabridge Engage.
        • "published": integer (optional) UNIX Timestamp (in UTC) of the (upcoming) publication date.
        }
    • "action_links": [] Action links define what actions are possible on this publisher mention and what links for it are.
    • "services": [] A list of profiles this post will/is published to.
    • "actions": []
    • "in_reply_to": Object: mention (optional) The mention to which the post is a reply.
    }
  • {
    • "id": integer Unique identifier for the Publishing Guideline.
    • "type": string The type of the Publishing Guideline.
      • Possible values: "PRESET", "TEXT"
    • "content": The restricted content of the Publishing Guideline.
    • "arguments": array (optional)
    • "message": string The message of the Publishing Guideline.
    • "level": string The level of warning for a Publishing Guideline.
      • Possible values: "INFO", "WARNING", "BLOCK"
    • "regex": string (optional) Regex to determine if message is according to the Publishing Guideline.
    • "date":
      • {
        • "updated": integer UNIX Timestamp (in UTC) of when the Publishing Guideline was last updated.
        }
    }
  • {
    • "type": string The type of service
    • "service_id": string Service specific id of this profile
    • "displayname": string Display name of the profile
    • "url": string (optional) Url to the profile
    • "avatar": string (optional) Url of the avatar of this profile
    • "status": string (optional) Indicates if the publisher mention was successfully published on the service. (Only available as part of a publisher_mention object.)
      • Possible values: "success", "failed"
    }
  • {
    • "id": integer Unique identifier of the tag
    • "tag": string Name of the tag
    • "filter": string Filter string to use when filtering mentions for this tag
    • "color_code": string (optional) rgb() color code for the tag
    • "parent_id": string (optional) Id of the tag's parent
    • "visible": boolean Tag configured as visible or not
    • "category_model_tag": boolean Is the tag belonging to a category model
    • "status": string The status of a tag
      • Possible values: "active", "archived"
    }
  • {
    • "id": integer Identifier of the team.
    • "name": integer Name of the team.
    • "show_in_team_performance": boolean Whether or not this team is shown in the Team Performance section.
    • "users": [
      • {
        • "id": integer Unique identifier of this Clarabridge Engage user.
        • "name": string
        • "company": string
        • "email": string (optional) (Only if your application has permission for scope 'email')
        • "avatar": string (optional) Url of avatar image for this user
        • "account_role": string (optional) Shows rights of user in the context of an account.
        • "business_hours_schedule_id": string (optional) Unique identifier for the Business Hours Schedule of the Clarabridge Engage user.
        }
      • {
        • "id": integer Unique identifier of this Clarabridge Engage user.
        • "name": string
        • "company": string
        • "email": string (optional) (Only if your application has permission for scope 'email')
        • "avatar": string (optional) Url of avatar image for this user
        • "account_role": string (optional) Shows rights of user in the context of an account.
        • "business_hours_schedule_id": string (optional) Unique identifier for the Business Hours Schedule of the Clarabridge Engage user.
        }
      ]
      List of users that are part of the team.
    • "date":
      • {
        • "added": integer UNIX Timestamp (in UTC) of when the Team was first created.
        • "updated": integer UNIX Timestamp (in UTC) of when the Team was last updated.
        }
    }
  • {
    • "id": integer Unique identifier of the topic.
    • "name": string
    • "searchkeywords": (optional) Search keywords
    • "monitoredprofiles": [] (optional)
    }
  • {
    • "id": integer Unique identifier of this Clarabridge Engage user.
    • "name": string
    • "company": string
    • "email": string (optional) (Only if your application has permission for scope 'email')
    • "avatar": string (optional) Url of avatar image for this user
    • "account_role": string (optional) Shows rights of user in the context of an account.
    • "business_hours_schedule_id": string (optional) Unique identifier for the Business Hours Schedule of the Clarabridge Engage user.
    }
  • {
    • "id": string Unique identifier for the User Role.
    • "title": string Title of the User Role.
    • "license": What type of license this User Role is.
      • Possible values: "free", "paying"
    • "date":
      • {
        • "added": integer UNIX Timestamp (in UTC) of when the User Role was created.
        • "updated": integer UNIX Timestamp (in UTC) of when the User ROle was last updated.
        }
    }
©2019 Clarabridge®. All rights reserved.
Stay Connected