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

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.

API call

localhost:3000/api/v2/stories
header:

{“X-User-Token”: b7c+D5o0joNRXMVNycN696yJZkuWshy4Zw66qWSJ--tT63Ev/FYFl00rCr--WomZk6tiLoXtapKgB/EtZA==,
“X-User-Token”: “soft.dave99@gmail.com“}

body_parameters:
{ "beneficiary_ids": [78820], "case_ids": [], "custom_fields": {}, "story": { "story_format": "old", "story_group": "change_created", "project_id": 2882, "source_of_story": "android_mobile_app", "story_category_id": 3509, "text": "test story create" }, "story_change_beneficiaries": [], "story_changes": [], "story_indicator_beneficiary": [] }

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

One Participant

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

body parameters

{
    "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"], 
    "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

{
    "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,
    "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

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

postman response

{
    "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,
    "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
        }
    ]
}

Definitions

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

Post a single-contact story API

Overview

API Documentation

API call

API response

Definitions

Explanation

Front-end Documentation

Logic