API version 1 documentation

API key

Use of our API requires a key, which you can get by contacting us. This means we can know who you are, so that as the API changes we can let you know.

Once you have a key you just add it to the query string like this:

  • apikey={xxx}

To get an API key, get in touch.

Posting API

We have a simple, read-only posting API available. You can use it to retrieve a single posting or a collection of postings.

Some things you'll need to know:

  • It's a RESTful API
  • It only accepts HTTP GET
  • The data comes back as plain old XML
  • You'll need an API key, which you add to the query string

Retrieving a single posting

  • This returns a single posting, together with the tags, health services and responses linked to that posting
  • You put the Id of the posting you want in place of {postingid}
  • You put your API key in place of {apikey} (duh!)
  • If the ID refers to a non-existent or unpublished posting, or to a response, you'll get a 404

Retrieving a collection of postings

  • This returns a collection of postings, together with the tags, health services and responses linked to each posting
  • You put your search parameters in place of {param1}, etc. You can add as many parameters as you like
  • You put your API key in place of {apikey}
  • If the search returns no postings, you'll get a 404

Search parameters

The API supports the following search parameters:

  • authorrole:the role of the posting author, e.g. patient, carer, relative: consult the dropdown list on the "share your story" page for the options available
  • postingsource: "po" if you just want stories posted via Care Opinion
  • phrase: a phrase you want to be in the posting text
  • nacs:The ID (NACS code) of a health service the posting is about. You can find the ID you want by looking at the URL of the page about that service. You can add as many as you want. Because we model health care as a tree, when you set a nacs code we return all the postings linked to that health service or any of its descendant services (i.e. the subtree).
  • tag: a tag linked to the posting. You can add as many as you want.
  • frompopulation: the ONS/ODS code of an area the posting has come from. This can be the code for a local government district council, county, unitary authority, metropolitan area or London borough. You can add as many as you want.
  • treatmentfunction: the NHS code for a specialty provided by a service the posting is about
  • SubmittedOnBefore, SubmittedOnAfter: date limits for the search
  • ProgressId: the progress of a story through told (1), heard (2), has response (3), led to change (4)
  • skip: see below
  • take: see below
  • startfrom: The default ordering is in reverse order of posting submission date, from most recent to least recent. Using startfrom changes the sort order to "oldest first", and sets the minimum posting id in the set. This will allow you to page forwards in time, picking up from where you left off in a previous session.


Responses to postings are accessible in two distinct ways:

  • Within the response collection on postings retrieved through the posting API as described above
  • As a separate Response API, which returns a collection of responses

The response API is here:


This endpoint will return a collection of responses, in order of submission date (oldest first), which makes it useful for paging through latest responses.

This endpoint accepts a few parameters as follows:

  • postingsource: "po" if you just want stories posted via Care Opinion
  • skip: see below
  • take: see below
  • startfrom: sets the lower limit for the response id (so you can pick up where you left off)
  • provideronly: Only includes responses which were posted by one of the providers the posting is about. This allows you to exclude responses from, for example, commissioners, patient groups, regulators, etc.

Paging parameters

There are two optional paging parameters:

  • skip: skips the first S postings in the set (default is zero)
  • take: returns the first T postings in the set (default is 10, maximum is 100)

Used together, skip and take will allow you to page through a collection of postings.