SERMO Conversation API

The SERMO Conversation API is a tool to allow 3rd parties access to SERMO data, providing insight for brands and physician behavior. It is secured by a SERMO-generated token, which is used as an API key to allow access only to the API methods specified for a client.

Basic Notes

Allowed HTTPs requests

  • GET - Get a resource or list of resources

Description Of Usual Server Responses

  • 200 OK - the request was successful (some API calls may return 201 instead).
  • 400 Bad Request - The request could not be understood or was missing required parameters.
  • 401 Unauthorized - "Authentication failed" or "You do not have permissions for requested operation"
  • 402 Payment Required - Your subscription has lapsed.
  • 403 Forbidden - Access denied.
  • 405 Method Not Allowed - The requested method is not supported for resource.
  • 429 Too Many Requests - You have exceeded Conversation API limits.
  • 503 Service Unavailable - The service is temporary unavailable. Try again later.

Basic Models

Author

The author model is used to identify the author of either a comment or a post, and will be returned as part of either one.

Author
Name Description Details
id A unique identifier for the author string
specialty The medical specialty of the author string
country of practice The country of practice of the author string
zipcode The zip code of the area the author practices medicine string
post badge The author have the 'More than 100 posts' badge boolean
comment badge The author have the 'More than 100 comments' badge boolean

Example (JSON):

{
    "id": "92a547a3a53f",
    "specialty": "doctoring",
    "country_of_practice": "US",
    "zipcode": "12345",
    "post_badge":true,
    "comment_badge":false
}

Example (XML):

<author>
  <country-of-practice>US</country-of-practice>
  <id>92a547a3a53f></id>
  <specialty>doctoring</specialty>
  <zipcode>12345</zipcode>
  <post-badge>false</post-badge>
  <comment-badge>false</comment-badge>
</author>

Comment

The comment model is used to represent a comment that has been attached to a post.

Comment
Name Description Details
id The comment id integer
author The author of the comment author object
published_at The date/time the comment was published. Will be returned in ISO 8601 format, as UTC (i.e. YYYY-MM-DDTHH:MM:SSZ) datetime
content The body of the comment, as written by the author. The content is returned as plaintext, with all html formatting removed. string
helpful_count A count indicating the number of times other participants found this comment helpful. integer

Example (JSON):

{
    "id": 1,
    "author": {
        "id": "92a547a3a53f",
        "specialty": "doctoring",
        "country_of_practice": "US",
        "zipcode": "12345",
        "post_badge":false,
        "comment_badge":false
    },
    "published_at": "2014-06-30T12:00:00Z",
    "content": "Lorem ipsum dolor sit amet...",
    "helpful_count": 5
}

Example (XML):

<comment>
  <id>1</id>
  <published-at>2014-06-30T12:00:00Z</published-at>
  <helpful-count>5</helpful-count>
  <author>
    <id>92a547a3a53f></id>
    <specialty>doctoring</specialty>
    <country-of-practice>US</country-of-practice>
    <zipcode>12345</zipcode>
    <post-badge>false</post-badge>
    <comment-badge>false</comment-badge>
  </author>
  <content><!CDATA[
    Lorem ipsum dolor sit amet...
  ]]></content>
</comment>

Post

The post model is used to represent a post that has been entered on SERMO. A post instance will contain all of the comments currently associated with it.

Post
Name Description Details
id The post id integer
author The author of the post author object
published_at The date/time the post was published. Will be returned in ISO 8601 format, as UTC (i.e. YYYY-MM-DDTHH:MM:SSZ) datetime
rating A number representing the average number of "stars" applied to the current post. decimal
iconsult A boolean flag indicating whether or not this particular post was an iConsult request. boolean
solved_at If the post is an iConsult, a date/time indicating when the post was solved. Will be returned in ISO 8601 format, as UTC (i.e., YYYY-MM-DDTHH:MM:SSZ) If the post is not an iConsult, or has not been solved, this will be null. datetime
title The title of the post. string
content The body of the post, as written by the author. The content is returned as plaintext, with all html formatting removed. string
comments The list of comments attached to the post comment object array

Example (JSON):

{
  "id": 1,
  "author": {
    "id": "92a547a3a53f",
    "specialty": "doctoring",
    "country_of_practice": "US",
    "zipcode": "12345",
    "post_badge":false,
    "comment_badge":false
  },
  "published_at": "2014-06-30T12:00:00.000Z",
  "rating": 4.5,
  "iconsult": true,
  "solved_at": "2014-07-02T12:00:00.000Z",
  "title": "Lorem ipsum dolor sit amet...",
  "content": "Lorem ipsum dolor sit amet...",
  "comments": [
  {
    "id": 1,
    "author": {
      "id": "92a547a3a53f",
      "specialty": "doctoring",
      "country_of_practice": "US",
      "zipcode": "12345",
      "post_badge":false,
      "comment_badge":false
    },
    "published_at": "2014-06-30T12:00:00Z",
    "content": "Lorem ipsum dolor sit amet...",
    "helpful_count": 5
  },
  {
    "id": 2,
    "author": {
      "id": "92b547b3b53f",
      "specialty": "doctoring",
      "country_of_practice": "US",
      "zipcode": "54321",
      "post_badge":true,
      "comment_badge":true
    },
    "published_at": "2014-07-31T12:00:00Z",
    "content": "Lorem ipsum dolor sit amet...",
    "helpful_count": 3
  }
  ]
}

Example (XML):

<post>
  <id>1</id>
  <published-at>2014-06-30T12:00:00.000Z</published-at>
  <rating>4.5</rating>
  <iconsult>true</iconsult>
  <solved-at>2014-07-02T12:00:00.000Z</solved-at>
  <author>
    <id>92a547a3a53f></id>
    <specialty>doctoring</specialty>
    <country-of-practice>US</country-of-practice>
    <zipcode>12345</zipcode>
    <post-badge>false</post-badge>
    <comment-badge>false</comment-badge>
  </author>
  <title><!CDATA[
    Lorem ipsum dolor sit amet...
  ]]></title>
  <content><!CDATA[
    Lorem ipsum dolor sit amet...
  ]]></content>
  <comments>
    <comment>
      <id>1</id>
      <published-at>2014-06-30T12:00:00Z</published-at>
      <helpful-count>5</helpful-count>
      <author>
        <id>92a547a3a53f></id>
        <specialty>doctoring</specialty>
        <country-of-practice>US</country-of-practice>
        <zipcode>12345</zipcode>
        <post-badge>false</post-badge>
        <comment-badge>false</comment-badge>
      </author>
      <content><!CDATA[
        Lorem ipsum dolor sit amet...
      ]]></content>
    </comment>
    <comment>
      <id>2</id>
      <published-at>2014-07-31T12:00:00Z</published-at>
      <helpful-count>3</helpful-count>
      <author>
        <id>92b547b3b53f></id>
        <specialty>doctoring</specialty>
        <country-of-practice>US</country-of-practice>
        <zipcode>54321</zipcode>
        <post-badge>false</post-badge>
        <comment-badge>false</comment-badge>
      </author>
      <content><!CDATA[
        Lorem ipsum dolor sit amet...
      ]]></content>
    </comment>
  </comments>
</post>

Conversation

The conversation model is used as a container for the results of the call. It contains the list of search terms matched by the contained post, and the post the conversation references.

Conversation
Name Description Details
matched_terms The list of terms this conversation matched array
post The post that contains the conversation post object

Example (JSON):

{
    "matched_terms": ["foo","bar"],
    "post": {
        "id": 1,
        "author": {
            "id": "92a547a3a53f",
            "specialty": "doctoring",
            "country of practice": "US",
            "zipcode": "12345",
            "post_badge":false,
            "comment_badge":false
        },
        "published_at": "2014-06-30T12:00:00.000Z",
        "rating": 4.5,
        "iconsult": true,
        "solved_at": "2014-07-02T12:00:00.000Z",
        "title": "Lorem ipsum dolor sit amet...",
        "content": "Lorem ipsum dolor sit amet...",
        "comments": [
            {
                "id": 1,
                "author": {
                  "id": "92b547b3b53f",
                  "specialty": "doctoring",
                  "country of practice": "US",
                  "zipcode": "12345",
                  "post_badge":false,
                  "comment_badge":false
                },
                "published_at": "2014-06-30T12:00:00Z",
                "content": "Lorem ipsum dolor sit amet...",
                "helpful_count": 5
            }
        ]
    }
}

Example (XML):

<conversation>
  <matched-terms>
    <matched-term>foo</matched-term>
    <matched-term>bar</matched-term>
  </matched-terms>
  <post>
    <id>1</id>
    <published-at>2014-06-30T12:00:00.000Z</published-at>
    <rating>4.5</rating>
    <iconsult>true</iconsult>
    <solved-at>2014-07-02T12:00:00.000Z</solved-at>
    <author>
      <id>92a547a3a53f></id>
      <specialty>doctoring</specialty>
      <country-of-practice>US</country-of-practice>
      <zipcode>12345</zipcode>
      <post-badge>false</post-badge>
      <comment-badge>false</comment-badge>
    </author>
    <title><!CDATA[
      Lorem ipsum dolor sit amet...
    ]]></title>
    <content><!CDATA[
      Lorem ipsum dolor sit amet...
    ]]></content>
    <comments>
      <comment>
        <id>1</id>
        <published-at>2014-06-30T12:00:00Z</published-at>
        <helpful-count>5</helpful-count>
        <author>
          <id>92a547a3a53f></id>
          <specialty>doctoring</specialty>
          <country-of-practice>US</country-of-practice>
          <zipcode>12345</zipcode>
          <post-badge>false</post-badge>
          <comment-badge>false</comment-badge>
        </author>
        <content><!CDATA[
          Lorem ipsum dolor sit amet...
        ]]></content>
      </comment>
    </comments>
  </post>
</conversation>

Error

An error response is returned if something goes wrong. It will contain the HTTP status code, message, and further details about what went wrong.

Error
Name Description Details
code HTTP Response code int
message The message associated with the response code string
details A more detailed explanation of what has gone wrong string

Example (JSON):

{
    "code": 402,
    "message": "Payment Required",
    "details": "Your subscription has lapsed"
}

Example (XML):

<error>
  <code>402</code>
  <message>Payment Required</message>
  <details>Your susbscription has lapsed</details>
</error>

Group Summary

Summary [/conversations/summary?terms%5b%5d=foo&terms%5b%5d=bar&start={start}&end={end}]

The Summary resource is used to retrieve meta information about the posts in the SERMO community. With the passed in list of search terms, this API will return counts for the number of times the term appears in both posts, and in the comments. The required start and end times will be used to define a window of time for the posts returned. For example, passing in a start time of "2014-01-01T00:00:00Z" and an end time of "2014-01-02T00:00:00Z" will give back the counts for all of the posts and comments that match the search terms for that 24-hour window. Each successful call will also return a unique id, to be used to track the response.

  • Parameters
    • terms%5b%5d (required, array) ... The list of terms being used for the search. When there is more than one term, the terms[] parameter will be passed multiple times, once for each term.
    • start (required, datetime, 2014-01-01T22:00:00Z) ... The time the date window you want to search by begins with. Should be in ISO standard UTC format.
    • end (required, datetime, 2014-01-02T22:00:00Z) ... The time the date window you want to search by ends with. Should be in ISO standard UTC format.

Retrieve Conversation Summary [GET]

  • Request JSON

    • Headers
      Accept: application/vnd.sermo-v1+json
X-Sermo-Conversation-API-Key: {apiKey}

  • Response 200

        {
        "id": "63596a8b-8fd6-4d71-aede-69fc4c9a27d3",
        "data_calls_remaining": 3,
        "query": {
            "start": "2014-06-24T12:00:00Z",
            "end": "2014-06-25T12:00:00Z",
            "terms": ["foo", "bar"]
        },
        "summary": {
            "terms": [
                {
                    "term": "foo",
                    "matches": 12,
                    "posts": 3,
                    "comments": 56
                },
                {
                    "term": "bar",
                    "matches": 10,
                    "posts": 2,
                    "comments": 45
                }
            ],
            "uniques": {
                "posts": 3,
                "comments": 31
            }
        }
    }

  • Response 400

    {
    "code": 400,
    "message": "Bad Request",
    "details": "The request could not be understood or was missing required parameters."
}

  • Response 401

    {
    "code": 401,
    "message": "Unauthorized",
    "details":  "Authentication failed"
}

  • Response 402

    {
    "code": 402,
    "message": "Payment Required",
    "details": "Your subscription has lapsed."
}

  • Response 403

    {
    "code": 403,
    "message": "Forbidden",
    "details": "Access denied."
}

  • Response 405

    {
    "code": 405,
    "message": "Method Not Allowed",
    "details": "The requested method is not supported for resource."
}

  • Response 429

    {
    "code": 429,
    "message": "Too Many Requests",
    "details": "You have exceeded Conversation API limits."
}

  • Response 503

    {
    "code": 503,
    "message": "Service Unavailable,
    "details": "The service is temporary unavailable. Try again later."
}

  • Request XML

    • Headers
      Accept: application/vnd.sermo-v1+xml
X-Sermo-Conversation-API-Key: {apiKey}

  • Response 200

        <call>
      <id>63596a8b-8fd6-4d71-aede-69fc4c9a27d3</id>
      <data-calls-remaining>11</data-calls-remaining>
      <query>
        <start>2014-06-24T12:00:00Z</start>
        <end>2014-06-25T12:00:00Z</end>
        <query-terms>
          <query-term>foo</query-term>
          <query-term>bar</query-term>
        </query-terms>
      </query>
      <summary>
        <summary-terms>
          <summary-term>
            <term>foo<term>
            <matches>12</matches>
            <posts>3</posts>
            <comments>56</comments>
          </summary-term>
          <summary-term>
            <term>bar<term>
            <matches>10</matches>
            <posts>3</posts>
            <comments>45</comments>
          </summary-term>
        </summary-terms>
        <uniques>
          <posts>3</posts>
          <comments>31</comments>
        </uniques>
      </summary>
    </call>

Group Data

Data [/conversations/data?terms%5b%5d=foo&terms%5b%5d=bar&start={start}&end={end}]

The Data resource is used to retrieve all of the conversations that match the search criteria. The parameters for this call are the same as the call to the Summary API. In addition to the results given back by the Summary API, it will also return the conversation that the matches were found in. This is represented as an array of conversation objects, each of which contains a list of the search terms that the conversation matched, and the post object that represents the conversation. The number of posts and comments returned may not necessarily match the counts returned in the Summary API call. This is because the entire context of the conversation is returned, rather than just the matching item. For instance, if there is a match in a comment on a post, but not in the post itself, the Data API will still return the post, plus all of the comments attached to the post, not just the comment that matched the search term.

  • Parameters
    • terms%5b%5d (required, array) ... The list of terms being used for the search. When there is more than one term, the terms[] parameter will be passed multiple time, once for each term.
    • start (required, datetime, 2014-01-01T22:00:00Z) ... The time the date window you want to search by begins with. Should be in ISO standard UTC format.
    • end (required, datetime, 2014-01-02T22:00:00Z) ... The time the date window you want to search by ends with. Should be in ISO standard UTC format.

Retrieve Conversation Data [GET]

  • Request JSON

    • Headers
      Accept: application/vnd.sermo-v1+json
X-Sermo-Conversation-API-Key: {apiKey}

  • Response 200

    {
  "id": "63596a8b-8fd6-4d71-aede-69fc4c9a27d3",
  "data_calls_remaining": 5,
  "query": {
    "start": "2014-06-24T12:00:00Z",
    "end": "2014-06-25T12:00:00Z",
    "terms": ["foo", "bar"]
  },
  "summary": {
    "terms": [
      {
          "term": "foo",
          "matches": 12,
          "posts": 3,
          "comments": 56
      },
      {
          "term": "bar",
          "matches": 10,
          "posts": 2,
          "comments": 45
      }
    ],
    "uniques": {
        "posts": 26,
        "comments", 60
    }
  },
  "conversations": [
  {
    "matched_terms": ["foo","bar"],
    "post": {
      "id": 1,
      "author": {
        "id": "92a547a3a53f",
        "specialty": "doctoring",
        "country of practice": "US",
        "zipcode": "12345",
        "post_badge":false,
        "comment_badge":false
      },
      "published_at": "2014-06-30T12:00:00.000Z",
      "rating": 4.5,
      "iconsult": true,
      "solved_at": "2014-07-02T12:00:00.000Z",
      "title": "Lorem ipsum dolor sit amet...",
      "content": "Lorem ipsum dolor sit amet...",
      "comments": [
      {
        "id": 1,
        "author": {
          "id": "92b547b3b53f",
          "specialty": "doctoring",
          "country of practice": "US",
          "zipcode": "12345",
          "post_badge":false,
          "comment_badge":false
        },
        "published_at": "2014-06-30T12:00:00Z",
        "content": "Lorem ipsum dolor sit amet...",
        "helpful_count": 5
      }
      ]
    }
  },
  {
    "matched_terms": ["bar"],
    "post": {
      "id": 2,
      "author": {
        "id": "92c547c3c53f",
        "specialty": "doctoring",
        "country of practice": "US",
        "zipcode": "12345",
        "post_badge":false,
        "comment_badge":false
      },
      "published_at": "2014-06-30T12:00:00.000Z",
      "rating": 4.5,
      "iconsult": true,
      "solved_at": null,
      "title": "Lorem ipsum dolor sit amet...",
      "content": "Lorem ipsum dolor sit amet...",
      "comments": [
      {
        "id": 1,
        "author": {
          "id": "92b547b3b53f",
          "specialty": "doctoring",
          "country of practice": "US",
          "zipcode": "12345",
          "post_badge":false,
          "comment_badge":false
        },
        "published_at": "2014-06-30T12:00:00Z",
        "content": "Lorem ipsum dolor sit amet...",
        "helpful_count": 5
      }
      ]
    }
  }
  ]
}

  • Response 400

    {
    "code": 400,
    "message": "Bad Request",
    "details": "The request could not be understood or was missing required parameters."
}

  • Response 401

    {
    "code": 401,
    "message": "Unauthorized",
    "details":  "Authentication failed"
}

  • Response 402

    {
    "code": 402,
    "message": "Payment Required",
    "details": "Your subscription has lapsed."
}

  • Response 403

    {
    "code": 403,
    "message": "Forbidden",
    "details": "Access denied."
}

  • Response 405

    {
    "code": 405,
    "message": "Method Not Allowed",
    "details": "The requested method is not supported for resource."
}

  • Response 429

    {
    "code": 429,
    "message": "Too Many Requests",
    "details": "You have exceeded Conversation API limits."
}

  • Response 503

    {
    "code": 503,
    "message": "Service Unavailable,
    "details": "The service is temporary unavailable. Try again later."
}

  • Request XML

    • Headers
      Accept: application/vnd.sermo-v1+xml
X-Sermo-Conversation-API-Key: {apiKey}

  • Response 200

    <call>
  <id>63596a8b-8fd6-4d71-aede-69fc4c9a27d3</id>
  <data-calls-remaining>5</data-calls-remaining>
  <query>
    <start>2014-06-24T12:00:00Z</start>
    <end>2014-06-25T12:00:00Z</end>
    <query-terms>
      <query-term>foo</query-term>
      <query-term>bar</query-term>
    </query-terms>
  </query>
  <summary>
    <summary-terms>
      <summary-term>
        <term>foo<term>
        <matches>12</matches>
        <posts>3</posts>
        <comments>56</comments>
      </summary-term>
      <summary-term>
        <term>bar<term>
        <matches>10</matches>
        <posts>3</posts>
        <comments>45</comments>
      </summary-term>
    </summary-terms>
    <uniques>
      <posts>3</posts>
      <comments>31</comments>
    </uniques>
  </summary>
  <conversations>
    <conversation>
      <matched-terms>
        <matched-term>foo</matched-term>
      </matched-terms>
      <post>
        <id>1</id>
        <published-at>2014-06-30T12:00:00.000Z</published-at>
        <rating>4.5</rating>
        <iconsult>true</iconsult>
        <solved-at>2014-07-02T12:00:00.000Z</solved-at>
        <author>
          <id>92a547a3a53f></id>
          <specialty>doctoring</specialty>
          <country-of-practice>US</country-of-practice>
          <zipcode>12345</zipcode>
          <post-badge>false</post-badge>
          <comment-badge>false</comment-badge>
        </author>
        <title><!CDATA[
          Lorem ipsum dolor sit amet...
        ]]></title>
        <content><!CDATA[
          Lorem ipsum dolor sit amet...
        ]]></content>
        <comments>
          <comment>
            <id>1</id>
            <published-at>2014-06-30T12:00:00Z</published-at>
            <helpful-count>5</helpful-count>
            <author>
              <id>92a547a3a53f></id>
              <specialty>doctoring</specialty>
              <country-of-practice>US</country-of-practice>
              <zipcode>12345</zipcode>
              <post-badge>false</post-badge>
              <comment-badge>false</comment-badge>
            </author>
            <content><!CDATA[
              Lorem ipsum dolor sit amet...
            ]]></content>
          </comment>
        </comments>
      </post>
    </conversation>
    <conversation>
      <matched-terms>
        <matched-term>bar</matched-term>
      </matched-terms>
      <post>
        <id>2</id>
        <published-at>2014-06-30T12:00:00.000Z</published-at>
        <rating>4.5</rating>
        <iconsult>true</iconsult>
        <solved-at>2014-07-02T12:00:00.000Z</solved-at>
        <author>
          <id>92a547a3a53f></id>
          <specialty>doctoring</specialty>
          <country-of-practice>US</country-of-practice>
          <zipcode>12345</zipcode>
          <post-badge>false</post-badge>
          <comment-badge>false</comment-badge>
        </author>
        <title><!CDATA[
          Lorem ipsum dolor sit amet...
        ]]></title>
        <content><!CDATA[
          Lorem ipsum dolor sit amet...
        ]]></content>
        <comments>
          <comment>
            <id>1</id>
            <published-at>2014-06-30T12:00:00Z</published-at>
            <helpful-count>5</helpful-count>
            <author>
              <id>92a547a3a53f></id>
              <specialty>doctoring</specialty>
              <country-of-practice>US</country-of-practice>
              <zipcode>12345</zipcode>
              <post-badge>false</post-badge>
              <comment-badge>false</comment-badge>
            </author>
            <content><!CDATA[
              Lorem ipsum dolor sit amet...
            ]]></content>
          </comment>
        </comments>
      </post>
    </conversation>
  </conversations>
</call>