Welcome

Welcome to the MutualMind Developers portal. This site is a repository of information and documentation to help you get started using our developer API.

What is MutualMind?

MutualMind is a web app that can be used to monitor and promote brands on social networks. We provide actionable insights and integrated response management to help you increase your social media ROI.

Find out more at mutualmind.com

Follow us on Twitter @mutualmind

The Basics

Base API URL

The base API URL for the MutualMind API is:

https://api.mutualmind.net/v1/

We are currently on v1 of the API.

Application Key, Secret and Auth Token

In order to use the MutualMind API, you'll need to get your application instance's application key and auth token. Log in to your site as an admin and then go to the “Admin” area and click “API Access”. You'll find the following keys there:

  • an application key
  • an application secret and
  • an auth token

Application keys are fixed and cannot be changed. However, if your credentials get compromised, you can always reset your application secret and auth token from the “Admin” area of your site.

All API methods require authentication using your fixed application key and generated auth token. Here are the request query params:

Key/Token Query Parameter
Application Key application_key
Auth Token auth_token

Data Formats

The MutualMind API supports the following formats:

Type API Format Code
JSON json
XML xml

You can use one of the format codes above when sending requests to any of our API endpoints. For example:

https://api.mutualmind.net/v1/campaigns/campaign/?format=json&application_key=GCngH8qtDrVShD7T9aGHqvWb6wDt5BcV&auth_token=a7f015cfd79e7393c8e3a497957f4acb9e0f7356

Try It

Will return results in JSON format. If you wish to get data as XML, then use this instead:

https://api.mutualmind.net/v1/campaigns/campaign/?format=xml&application_key=GCngH8qtDrVShD7T9aGHqvWb6wDt5BcV&auth_token=a7f015cfd79e7393c8e3a497957f4acb9e0f7356

Try It

IMPORTANT NOTE: You must specify the format with every API call and it must be the first parameter passed in.

Timestamps and Date Formats

All dates and times accepted and returned by the MutualMind API must conform to the ISO-8601 data interchange specification. E.g.,

  • 2008-08-13
  • 2008-08T15:30:00

All API endpoints accept only UTC timestamps and only return timestamp data as UTC. It is up to the calling application to convert timestamps to UTC as part of each request and also convert timestamps from UTC to the desired target time zone from each response.

Resource URIs

Most resources (including those that are embedded) returned via our API include a resource_uri node. If populated, it provides a relative URL to that specific resource. You can use this URL to access that resource. For example:

<?xml version='1.0' encoding='utf-8'?>
<object>
    <labels type="list">
        <object>
            <created_datetime>2011-01-16T17:43:35.464304</created_datetime>
            <id>5</id>
            <label_text>Technical Support</label_text>
            <resource_uri>/v1/campaigns/label/5/</resource_uri>
        </object>
        ...
    </labels>
</object>

Pagination

By default, lists of objects are returned as paged results, 20 items at a time. If you wish to get more items per page, simply increase the value of the limit parameter. The maximum value for limit is 500. There is no limit on the number of pages.

Paged results include a meta node which contains paging information including the total number of objects, offset, limit and helper URLs for paging to the next or previous pages. For example:

<meta type="hash">
    <next>...</next>
    <total_count type="integer">22</total_count>
    <previous type="null" />
    <limit type="integer">20</limit>
    <offset type="integer">0</offset>
</meta>

Rate Limiting

Most resources are not rate limited. However, some resources may have a rate limit and it will be noted in the documentation. Contact us to request a higher limit if needed.

HTTP Response Codes

CodeDescription
200OKThe request was successful.
201CreatedAn object was created.
400Bad RequestThe request is invalid. Look at the returned error message for details.
401UnauthorizedIncorrect authentication credentials were supplied.
403ForbiddenThe request is valid but it has been refused. This may occur if you don’t have permission to access the requested resource. Look at the returned error message for details.
404Not FoundThe requested resource was not found.
410GoneYou may be trying to access something that no longer exists or you don’t have access to.
500Internal Server ErrorUh-oh. Looks like something is broken. These errors are logged and we try to get them resolved as soon as we can.
503Service UnavailableThe API servers are up but are not accepting requests. They may be undergoing scheduled maintenance.
You are here: Welcome
© 2008 – 2014 MutualMind, Inc.