Social Connect API FAQs

General

How do I enable my developer account?

To access API and related features, you must first enable the developer account. See Personal Settings Preferences for more information.

How do I get started with the Social Connect API?

See the Qualtrics Social Connect API step-by-step guide.

What type of account do I need to use the Social Connect API?

Access to the API isn’t included in all pricing plans. Contact Support if you have questions about what’s included in your license.

Do you have a client library in programming language x?

Qualtrics doesn’t offer client libraries, but libraries for the OAuth protocol exist in almost every language, see http://oauth.net/code/.

Can I quickly test the API?

You can test the API via the API console. Here, you’ll pick an endpoint and fill in the required parameters. An immediate result will appear for you to see if the API resulted in your desired outcome.

Can you increase the API rate limits?

See Rate Limiting for an overview of API rate limits. Our current rate limits are more than enough for standard use cases. If however, you would need extra rate limits, please contact Support and describe the use case of your application and the requested rate limits.

How does filtering work in the API?

Several endpoints of the Social Connect API allows you to pass a filter string parameter.

For example, let’s say you’re fetching a list of mentions. You can filter the mentions so that only mentions with a certain tag are returned.

The filter parameter is always a string. Its syntax supports searching for several properties of the data (mentioned words, tags, status, resolve time, …) and combining them using a boolean and nested syntax.

When you build a filter in the Social Connect platform, the filter has an associated textual representation. This representation will appear in the filter window after you’ve selected your filter fields. You can copy this parameter to then use in your API calls.

What method is used for signing webhooks?

See Webhooks for more information.

Why am I rate limited to 20 API calls per hour?

If using the API Console, the rate limit is 20 authenticated calls per hour, instead of the standard 350 calls per hour for other API clients. If you’re experiencing this 20 call limit, make sure that you’re using the access token for your API application, not the API Console.

API Authentication

How are API calls authenticated?

Qualtrics uses the standard OAuth 2.0 protocol. See Authentication for more information.

Do I really need to implement OAuth for my application?

If you don’t need the users of your application to authenticate their Qualtrics Social Connect account, you can instead generate an OAuth token for your own user account. Go to the application overview, click Edit next to your registered application, go to the Access Tokens tab. If you click Authorise Myself, an access token for your current logged-in user (with its permissions) will be generated. You can use this access token to sign API requests.

How long are access tokens valid?

See the Authentication page for more information.

What accounts and data can I access with a token?

An OAuth access token is generated for a specific Social Connect user. This user has access to one or more accounts (you can see which ones via the `/me/accounts` endpoint). What data you can access depends on what accounts the user itself has access to, and what their user role in that account is.

Working with mentions

How do I get mentions from my Social Connect Inbox into my own application?

Use the `/{account_id}/inbox/mentions` endpoint to retrieve all the mentions in any of your topics. This API support page covers what information is retrieved for your mentions.

You could also design a workflow to call up web hooks in your application using the Social Connect automation recipe feature.

Why are Tweets returned by the API missing details?

For Tweets, Qualtrics can only return the Social Connect specific data and the Twitter Tweet ID. This is a restriction from the Twitter API Terms.

Since you have the Tweet ID, you can access the Twitter API and use the “/statuses/lookup” endpoint  for fetching all details.

Why are some Facebook posts anonymous?

Public Facebook posts (picked up by Social Connect through your keyword search, not messages on your Facebook pages) are anonymised. This is a limitation from the Facebook API.

Can I add my own messages to Social Connect?

If you have a contact form, or internal forum that you’d like to see monitored by Social Connect, you can call the “/{account_id}/inbox/add” endpoint to add your custom messages to Social Connect. These messages will then be accessible in your inbox and insights.

Messages added to Social Connect via the API cannot be replied from within Social Connect If you want to have this tighter integration with your custom system, please get in touch with Support.

Can I export cases via the API?

You can use the regular mention endpoint (export list / update single mention) to export cases. If you only want to return cases in your request, you can use the filter ‘sub_category:case’.

What’s the difference between cases and mentions for the API?

In Social Connect a “mention” is the central object of a message (a single tweet, a single private message, a single comment). There is also the concept of a “Case” which basically is a collection of mentions.

The main use for cases is to group several messages from a certain user and replies from agents into conversations.

From a technical perspective a “case conversation” consists of:

• The case itself (which is also a mention object).
• A case can have labels, a status, a title, etc.
• A list of mentions that are part of the conversation.
• The mentions that have been grouped in the case.

See this API support page for more information about cases and mentions.

Can I import messages to Social Connect outbox?

You can create drafts of new posts for social managers to verify, edit, and publish through the endpoint “/{account_id}/publisher/add”.

Can I edit a mention via the API?

You can edit existing mentions by using the “/{account_id}/inbox/mention/{topic_id}/{id}” endpoint. The documentation for this endpoint has examples for updating a mention’s tags, adding a note, and more.

How do I delete all data from a certain user in Engage via the API?

If you want to delete all data from a certain customer that is in your Social Connect account, you need to delete two types of data:

1. All mentions from that user in the system
2. Any information about that user that is stored in the Social Connect CRM.

To find all mentions from a certain user, use the “/{account_id}/inbox/mentions” endpoint and filter for a certain authorID, e.g. “author.id:123”.Once you have that list of mentions, the mentions can be deleted via the “/{account_id}/inbox/mention/{topic_id}/{id}” endpoint .

To know whether or not your agents saved more contact data in the Social Connect CRM for a contact, do a GET request to “/{account_id}/inbox/contact/{service}/{service_id}”. If the response object contains a contact.id, this means that there is a contact for this user. If the response doesn’t contain a contact.id property, it means that no data was stored in the Social Connect CRM.

Once you have a contact.id, you can then do a DELETE request to the /{account_id}/inbox/contact/{contact_id} endpoint to remove all information.

Working With Contacts  ​

How can I find contact details from a mention or case?

If a mention or a case is returned by the API, it will contain a list of “action_link” objects. Action links contain information for the current object on what other API Endpoints or URLs in the web application are relevant for this object. For mentions and cases, one of the included action-links is where you can fetch the contact details of the author of the mention or case.

When using the /{account_id}/inbox/cases endpoint, the contact object of the author of the mention is included by default. Qualtrics doesn’t include the full contact object for mentions, but via the action links this object can then be fetched by doing a separate API call.

Publishing​

Can I use the Clarabridge Engage API to publish to a social channel?

No, the API doesn’t allow directly publishing to 3rd party platforms. This means you cannot use the Social Connect API to publish a tweet or a Facebook comment.

However, you can use the Social Connect API to create drafts or queue messages for approval. These will then be published when approved or published through the Social Connect interface. The endpoint to draft messages is /{account_id}/publisher/add.

User Management

Can I change the status of Users via the API?

No, you cannot change the status of users via API. While you cannot change the status, you can change the Name, Company, Email, Avatar and Business Hour Schedule via the /{account_id}/settings/user/{id} endpoint.

Can I change the User Role of Users via the API?

It’s possible to change the user role of a user via our API. However, for security reasons it’s not possible to change a user role to Administrator. All the other user roles are available to change to via the /{account_id}/settings/user/{id} endpoint.

Can I create new Users via the API?

Due to security reasons this is not possible via API.

Working with Social Profiles

Can I retrieve information about the social profiles in my topics?

You can fetch information about a certain social profile via the “/{account_id}/inbox/contact/{service}/{service_id}” endpoint. This will include any details you’ve filled in for that person within the Social Connect CRM, like gender, email, or custom attributes you’ve added for this user.

Working with Insights

Can I get statistics from Clarabridge Engage?

You can pull data from Insights using 2 different API endpoints;

1. The “/{account_id}/dashboards/export/{dashboard_id}” endpoint returns the data from all widgets on a certain dashboard. Once you or your users have set-up custom dashboards, you can use this endpoint to get the data behind them.
2. The “/{account_id}/insights/facets” endpoint, acts as the the API equivalent of the Chart Builder feature in Social Connect.

Problems

Where can I find my account id?

Once you’ve authenticated, you can get a list of all accounts (and their ids) a user has access to via the “/me/accounts” endpoint.

Where can I find my topic id?

Once you’ve authenticated, you can get a list of all the topics (and their ids) a user has access to via the “/me/accounts” endpoint.

Where can I find my user id?

Once you’ve authenticated, you can get details about the authenticating user (including his/her id) via the “/me” endpoint.