You can use the API to post a story that tags progress for only one contact at a time.

Overview

There are two APIs for posting a story. Choose the API that suits your scenario.

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 Zero-or-Multiple-Contacts Story API	Yes	Yes	No	Yes	Yes
Post a Single-Contact Story	No	Yes	Yes	No	No

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

API Documentation

See the Example of how to post a single-contact story for details of the related API calls and responses.

Definitions

Whenever you create a story on Makerble, what you are actually doing is completing a survey.

The Survey is called a Story Category
You can think of the fields that you submit within the story as answers to survey questions


Story group	Always input `"change_created"`
Story format	Always input `"old"`
Project ID	The numerical ID of the Project that the story will be created in

Story Category ID


Story Category ID	The numerical ID of the Story Category being used to create the story
Source of story
Wave_id	The numerical ID of the

Story Category

Waves being

used

selected to create the story

Source of story

Text	This is the main text field of your story so input whatever text would go into the story
Created At	This is the Date that the activity in the story actually happened. Submit in the format: “YYYY-MM-DD”
Story_changes_attributes	Use this section to include any progress that is tagged to Activity progress trackers (Changes) Engagement progress trackers (Changes) For each progress tracker of the Activity or Engagement type, you need to Include a random set of alphanumeric characters, e.g. “`05d83e67`” include the Change_ID which is the ID of the Change (the progress tracker) include the number (i.e. the amount of progress towards that tracker which comes from this story” Image Modified
Beneficiaries	This is the contact who is tagged in the story. (Contacts are called Beneficiaries in the back-end) There should only be one contact in the story State the ID number of the beneficiary
Case_ids	These are the IDs of the contact’s Cases that this story is showing progress towards Make sure you only include the IDs of Cases that are associated with the contact whom you included in the Beneficiaries field
Custom fields Image Modified	A story can contain custom fields that have been added to the Story Category. They can be of different types: Text Date Time Attachment State the ID of the Custom Field and the content to go into it
Story_indicator_beneficiaries Image Modified	This is how you include progress that is being made towards Multiple Choice trackers (survey questions - called Scale Indicators in the backend) Achievement trackers (tick box survey questions - called Binary indicators in the backend) Numerical trackers (numerical input survey questions - called Value Indicators in the back-end) Story indicator_beneficiary A story_indicator_beneficiary record is created for each response to a question from a single contact. For each record, you need to create and submit a unique alphanumeric code, e.g. “18c5bdb9” Outcomes Every indicator is associated with at least one outcome but when it is included in a story, there can only be one outcome associated with each indicator. The outcome to associate with the indicator can be found out from the Get a single Story Category API Answers to Multiple Choice Questions Every Answer choice in a Multiple Choice Question is called a sub ratio Every sub ratio has an ID Therefore you must include the Sub Ratio ID when submitting a response to a Multiple Choice Question The indicator_type is scale Answers to Tick box Questions If the tick box is ticked, the binray_indicator_value to submit is “on” If it was not ticked, do not include that story_indicator_beneficiary record in your API call The indicator_type is scale Answers to Numerical Questions Submit the contact’s response to the question. E.g. if the question is “how many miles did you run?” and the answer is “7”, submit 7 The indicator_type is value

API call

localhost:3000/api/v2/stories
header:

...

=====================================

One Participant

=====================================

...

Code Block

{
    "story": {
        "story_group": "change_created", 
        "story_format": "old", 
        "project_id": "572", 
        "story_category_id": "841", 
        "source_of_story": "android_mobile_app", 
        "text": "case test", 
        "created_at": "2022-05-24", 
        "story_changes_attributes": {
            "45048d65": {
                "change_id": "276", 
                "number": "5"
            }, 
            "05d83e67": {
                "change_id": "274", 
                "number": "4"
            },
            "0509f592": {
                "change_id": "260",
                "number": "6"
            }
        }
    }, 
    "beneficiaries": ["160498"], 
    "case_ids": ["96"],
    "wave_id": 299, 
    "custom_fields": {
        "352": "1991-02-21", 
        "353": "11:30", 
        "177": "Lunawada", 
        "354": "11:45", 
        "4": "2022-05-24", 
        "190": "ajay@gmail.com", 
        "324": "Hello Everyone"
    }, 
    "story_indicator_beneficiaries": {
        "78b138d1": {
            "indicator_id": "577",
            "indicator_type": "scale",
            "outcome_id": "528",
            "sub_ratio_id": ["927"]
        }, 
        "45ebc5de": {
            "indicator_id": "578", 
            "indicator_type": "scale", 
            "outcome_id": "528", 
            "sub_ratio_id": ["930"]
        }, 
        "18c5bdb9": {
            "indicator_id": "363", 
            "indicator_type": "value", 
            "outcome_id": "224", 
            "number": "3"
        }, 
        "b1a328d1": {
            "indicator_id": "364", 
            "indicator_type": "binary", 
            "outcome_id": "224", 
            "binray_indicator_value": "on"
        }, 
        "47e3dad5": {
            "indicator_id": "8", 
            "indicator_type": "binary", 
            "outcome_id": "2", 
            "binray_indicator_value": "on"
        }, 
        "8f0e789b": {
            "indicator_id": "455", 
            "indicator_type": "value", 
            "outcome_id": "271", 
            "number": "7"
        }
    }
}

API response

Code Block

{
    "id": 190282,
    "text": "test story create",
    "number": "0",
    "approved": true,
    "story_group": "change_created",
    "location": null,
    "project_id": 2882,
    "charity_id": null,
    "story_category_id": 3509,
    "edited_by": 2044,
    "user_id": 2044,
    "wave_id": 299,
    "updated_at": "2022-05-16T19:22:44.353+01:00",
    "created_at": "2022-05-16T19:22:41.000+01:00",
    "actual_created_at": "2022-05-16T19:22:41.573+01:00",
    "beneficiary_ids": [
        78820
    ]
}

...

=====================================

One Participant

=====================================

...

Code Block

{
    "id": 127311,
    "text": "case test",
    "number": "0",
    "approved": true,
    "story_group": "change_created",
    "location": null,
    "project_id": 572,
    "charity_id": null,
    "story_category_id": 841,
    "edited_by": 190,
    "user_id": 190,
    "wave_id": 299,
    "updated_at": "2022-05-24T13:32:07.923+01:00",
    "created_at": "2022-05-24T13:32:05.000+01:00",
    "actual_created_at": "2022-05-24T13:32:05.718+01:00",
    "beneficiary_ids": [
        160498
    ],
    "case_ids": [
        96
    ],
    "custom_fields": [
        {
            "id": 352,
            "name": "test date 2",
            "type": "date",
            "value": "1991-02-21"
        },
        {
            "id": 353,
            "name": "test time. 1",
            "type": "time",
            "value": "11:30"
        },
        {
            "id": 177,
            "name": "Location",
            "type": "text",
            "value": "Lunawada"
        },
        {
            "id": 354,
            "name": "test time 2",
            "type": "time",
            "value": "11:45"
        },
        {
            "id": 4,
            "name": "Date founded",
            "type": "date",
            "value": "2022-05-24"
        },
        {
            "id": 190,
            "name": "Email",
            "type": "text",
            "value": "ajay@gmail.com"
        },
        {
            "id": 324,
            "name": "Ideas suggested by the participant",
            "type": "text",
            "value": "Hello Everyone"
        }
    ],
    "story_indicator_beneficiaries": [
        {
            "id": 33101,
            "beneficiary_id": 160498,
            "indicator_id": 577,
            "indicator_type": "scale",
            "sub_ratio_id": 927,
            "outcome_id": 528
        },
        {
            "id": 33102,
            "beneficiary_id": 160498,
            "indicator_id": 578,
            "indicator_type": "scale",
            "sub_ratio_id": 930,
            "outcome_id": 528
        },
        {
            "id": 33103,
            "beneficiary_id": 160498,
            "indicator_id": 363,
            "indicator_type": "value",
            "number": 3.0,
            "outcome_id": 224
        },
        {
            "id": 33104,
            "beneficiary_id": 160498,
            "indicator_id": 364,
            "indicator_type": "binary"
        },
        {
            "id": 33105,
            "beneficiary_id": 160498,
            "indicator_id": 8,
            "indicator_type": "binary"
        },
        {
            "id": 33106,
            "beneficiary_id": 160498,
            "indicator_id": 455,
            "indicator_type": "value",
            "number": 7.0,
            "outcome_id": 271
        }
    ],
    "story_change_beneficiaries": [
        {
            "id": 36774,
            "beneficiary_id": 160498,
            "change_id": 276
        },
        {
            "id": 36775,
            "beneficiary_id": 160498,
            "change_id": 274
        },
        {
            "id": 36776,
            "beneficiary_id": 160498,
            "change_id": 260
        }
    ],
    "story_changes": [
        {
            "id": 37477,
            "change_id": 276,
            "number": 5
        },
        {
            "id": 37478,
            "change_id": 274,
            "number": 4
        },
        {
            "id": 37479,
            "change_id": 260,
            "number": 6
        }
    ]
}

Explanation

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 that tags a single contact

Logic

Component	Description
Beneficiary	Use this API to create a single story that contains progress relating to only one beneficiary
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 Changes attributes	The number for a Participation Change must always be '1'
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

Troubleshooting

Check that the story_changes_attributes key is send INSIDE the story distionary, not outside the story distionary

Versions Compared

Old Version 3

New Version Current

Key

Overview

API Documentation

Definitions

API call

API response

Explanation

Front-end Documentation

Logic

Troubleshooting

Page Comparison

Versions Compared

Old Version 3

New Version Current

Key

Overview

API Documentation

Definitions

API call

API response

Explanation

Front-end Documentation

Logic

Troubleshooting