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) |
|---|---|---|---|---|---|
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 |
Story format | Always input |
Project ID | The numerical ID of the Project that the story will be created in |
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 Waves being selected to create the 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 For each progress tracker of the Activity or Engagement type, you need to
 |
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  | A story can contain custom fields that have been added to the Story Category. They can be of different types:
State the ID of the Custom Field and the content to go into it |
Story_indicator_beneficiaries  | This is how you include progress that is being made towards
Story indicator_beneficiary
Outcomes
Answers to Multiple Choice Questions
Answers to Tick box Questions
Answers to Numerical Questions
|
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
Logic
Component | Description |
|---|---|
Beneficiary |
|
Story Category |
|
Story Changes attributes |
|
Story Indicator Beneficiary |
|
Story Indicator |
|
Troubleshooting
Check that the
story_changes_attributeskey is send INSIDE the story distionary, not outside thestorydistionary