There are two APIs for posting a story.

API	Story about zero contacts	Story about only one contact	Story about one or more cases of one contact	Story about multiple contacts	Story with anonymous progress (i.e. progress is not tagged to a contact)

API	Story about zero contacts	Story about only one contact	Story about one or more cases of one contact	Story about multiple contacts	Story with anonymous progress (i.e. progress is not tagged to a contact)
Post a Multiple-Contacts or Zero Contacts Story API	Yes	Yes	No	Yes	Yes
Post a single-contact Story API	No	Yes	Yes	No	No

If your story is about one or more cases, you should use the Single-Contact Story API

Introduction

Stories are the main content format on Makerble
Every story has a single story category. (The story category contains the current fields (i.e. Survey Questions) that appear on the Create Story page)
Stories can contain
- text
- media (e.g. image, video, audio, document attachments)
- progress towards Changes and Indicators; and that progress can optionally be tagged to individual beneficiaries (called contacts in the front-end)
Every story must belong to a single project
Every story must have a single author who is a user

Front-end Documentation

How to create a story

Logic

Component	Description

Component	Description
Beneficiaries	Use this API to create a single story that contains progress relating to no beneficiaries, one beneficiary (as long as there are no cases to tag to the story) or many beneficiaries It can also contain anonymous progress that is not linked to individual beneficiaries.
Story Category	Every story is created using a single Story Category. The story category contains the fields that are used to create the story. A story Category can contain one or more of the following: quantitative fields: Activity Change (These are numerical fields but are not linked to an outcome) Participation Change (These are also numerical fields but are not linked to an outcome) Binary Indicator (used for tickbox fields that are linked to an outcome). Scale Indicator (used for multiple choice fields) Value Indicator (used for numerical fields linked to an outcome) qualitative fields and other fields Text fields Date fields Time fields File Attachment User who wrote the story Time & Date story was created Privacy setting of the story Location (The longitude and latitude coordinates of the story) Event ID: this should only be used when the story is related to a specific event record. (How events work in the front end) The ‘date happened’ field that allows you to backdate a story
Story Change Beneficiary	A story can contain anonymous progress and/or progress which is tagged to individual beneficiaries For example if there are three beneficiaries: Adam, Betty and Carlos, they can be tagged to the “Session Attendances” participation-type Change metric. Each beneficiary would have a Story Change Beneficiary record with the value of “1' for the session attendances metric. This shows they have each attended this session once in this story. You als need to submit the total Story Change value for this metric, which would be '3'. However if there were two people who also attended the session but they are not registered as beneficiaries, you would record the total Story Change for the “Session Attendances” metric as being '5'. This is because the server will detect that there are three tagged beneficiaries who have Story Change Beneficiary data and therefore recognise that there were 2 anonymous participants.
Story Change	When you use the API to post a story that contains progress in the change format tagged to individual beneficiaries you must submit two types of information Story Change Beneficiary data: these records contain the progress towards a single Change for a single beneficiary in this single story Story Change data: this is the total number of individual beneficiaries and anonymous participants that have progress towards this Change The number of Anonymous Participants is calculated by the server and is simply the Story Change value minus the number of Story Change Beneficiary records Note: if the metric is a Change of the Activity type, you cannot tag a beneficiary. I.e. for this type of metric you can only post Story Change data, not Story Change Beneficiary data.
Story Indicator Beneficiary	When you use the API to post a story that contains progress in the indicator format tagged to individual beneficiaries you must submit two types of information Story Indicator Beneficiary data: these records contain the progress towards a single indicator for a single beneficiary in this single story Story Indicator data: this is the total number of individual beneficiaries and anonymous participants that have progress towards this indicator The number of Anonymous Participants is calculated by the server and is simply the Story Indicator value minus the number of Story Indicator Beneficiary records
Story Indicator	When you use the API to post a story that contains progress in the indicator format tagged to individual beneficiaries you must submit two types of information Story Indicator Beneficiary data: these records contain the progress towards a single indicator for a single beneficiary in this single story Story Indicator data: this is the total number of individual beneficiaries and anonymous participants that have progress towards this indicator The number of Anonymous Participants is calculated by the server and is simply the Story Indicator value minus the number of Story Indicator Beneficiary records

API Documentation

Desc: Post a Zero-or-Multiple-Contacts Story

API call: definitions

Part of the API call	What it means	Front-end documentation

Part of the API call	What it means	Front-end documentation
“Story”: {	Everything after this point relates to the single story that is being created	Stories App
“story_group”
“story_format”
“display as”
“project_id”	Every story must belong to a single project	Projects App
“charity_id”		Organisations
“story category ID”	every story must belong to a single Story Category	Survey
“event ID”	this only needs to be filled in if the story is tagged to an event	Events App
latitude
longitude
draft	The options are:
source of story	The options are:
is_public	The options are:
approved	The options are:
text	This is the default text field within the story. In the front-end it is called the What’s been happening? Share a relaxed anecdote field on the Create/Edit Story page
story_privacy	The options are:	Story Privacy
individual_list	Only if you have set the story privacy to Specific Individuals only, must you complete this field with the IDs of the user whom you want to be able to view the story. You must include the user who created the story if you want them to be able to see it too
beneficiary IDs		Tag a contact in a story
story_changes
Each pair of change_id and number fields
change_id	If there are
number
Story change beneficiaries
Each pair of story_change_beneficiary and beneficiary fields
change_id
beneficiary_id
Story indicators
Story indicator beneficiaries
Each quintet (group of five) of fields
indicator ID
indicator type	The options are: value scale binary
outcome ID	This is the outcome that the indicator should be linked to. (See outcome indicator pairings)
beneficiary indicator value
beneficiary ID
custom fields
[ID of each custom field]	value entered for that custom field

API call: code

url: /stories

method: POST

required: story_category_id, project_id

NOTE: The api supports markdown language for formatting and need to send in text parameter.

body:

{
  "story": {
    "story_group": "change_created",
    "story_format": "old",
    "display_as": "survey_questions_view",
    "project_id": 19,
    "charity_id": "", 
    "story_category_id": 327,
    "event_id":"" ,
    "latitude":"" ,
    "longitude": "" ,
    "draft": false,
    "source_of_story": "one_participant_story_form",
    "is_public": false,
    "approved": "",
    "text": "API TEST"
  },
  "story_privacy": "only_charity_colleagues",
  "individual_list": [],
  "beneficiary_ids": [413],
  "story_changes": [
    {
      "change_id": 199,
      "number": 2
    },
    {
      "change_id": 230,
      "number":2
    }
  ],
  "story_change_beneficiaries":[
    {
      "change_id": 230,
      "beneficiary_id": 413
    }
  ],
  "story_indicator_beneficiaries":[
    {
      "indicator_id": 243,
      "indicator_type": "scale",
      "outcome_id": 145,
      "sub_ratio_id": 54,
      "beneficiary_id": 413
    },
    {
      "indicator_id": 244,
      "indicator_type": "binary",
      "outcome_id": 145,
      "binray_indicator_value": "on",
      "beneficiary_id": 413
    },
    {
      "indicator_id": 242,
      "indicator_type": "value",
      "outcome_id": 145,
      "number": 2,
      "beneficiary_id": 413
    }
  ],
  "custom_fields": {
    "26": "adfasfasf",
    "103": "02:05",
    "19": "2021-04-25",
    "177": "Place"
  } 
}