Makerble API

Obtain a token by calling POST /users/sign_in. Tokens are long-lived and do not expire — each user has one fixed token.

Pass both headers on every authenticated request:

All list endpoints support cursor-free offset pagination. The maximum per_page is 200.

Makerble uses different terms in the front-end UI and the API. The API uses the back-end terms listed below.

A Prism-powered mock server is running alongside these docs. It reads the OpenAPI spec and returns realistic example responses — safe to call without touching any real Makerble data.

Organisations (called Charities in the API) are the top-level entity. Each Organisation owns one or more Projects, and all data ultimately belongs to an Organisation.

Every Story and Case on Makerble belongs to a Project. A Project belongs to a single Organisation. Users hold one of three roles per Project: Editor (Manager), Reporter (Changemaker), or Observer (Analyst).

Platform users with login credentials. Creating users requires a separate API Key — request one at api-key-request@makerble.com.

Contacts (Beneficiaries in the API) are the people your organisation works with. Each Contact belongs to an Organisation and can be enrolled in multiple Projects. Custom fields are defined per Contact Bio Form.

Contact Bio Forms (Beneficiary Categories in the API) define the custom fields available when creating or editing a Contact. Use these endpoints to discover field IDs before calling POST /beneficiaries.

Cases are structured records for a specific Contact within a Project. Each Case has a Case Owner (creator) and optional Case Workers. Case fields are defined by a Case Form (Custom Field Category).

Surveys (Story Categories in the API) are the form templates used to create Stories. A Survey must be deployed as a Survey Campaign (Project Story Category) before Stories can be created with it in a Project.

Stories are the primary content format on Makerble — they capture text, media, and progress towards Changes and Indicators, and can be tagged to Contacts. Every Story belongs to a Project and is created using a Survey.

Story timestamps: actual_created_at = Date Posted (database time) · created_at = Date Happened (user-selected, can be backdated) · updated_at = Date Edited.

Every photo, video, audio file and document attached to Stories and to Contacts' bios in one organisation, in one list. Only files from Stories and Contacts the user is already allowed to view are returned, so two users can see different results for the same organisation.

Sub-resources that record per-story metric progress. Filter by story_id on any of these endpoints to get all metric data for a specific Story.

Versions are the audit trail behind the Manage Versions page: every time a Contact is created or edited, a Version records who did it, when, and a full snapshot of every field at that moment. Only Contacts are versioned so far.

Visible to Charity Editors (any Contact in their Organisation) and Project Editors (Contacts in at least one of their Projects). Anything else returns 404. user_name is System when no signed-in user made the change, e.g. a CSV import.

Changes are custom KPIs (Activity and Participation trackers). They appear in Progress Panel columns 1 and 2. Activity Changes are numerical metrics; Participation Changes track attendance and can tag individual Contacts.

Indicators are linked to Outcomes and appear in Progress Panel columns 3–5. Three types: Scale (multiple-choice using a Ratio Set), Binary (tickbox), Value (numerical).

Outcomes are the top-level impact categories. Progress is tracked via Indicators, not Outcomes directly. Each Outcome has a stage (short/medium/long-term) that determines which Progress Panel column its Indicators appear in.

A Framework Set groups Impact Frameworks (template in the API) into one thing an organisation reports its contribution towards. For example, the 17 SDG Impact Frameworks form the set "UN Sustainable Development Goals"; others are TOMs, a funder's outcomes framework or an organisation's own strategy. Each set names its two levels, e.g. Goal › Target: level 1 is an Impact Framework and level 2 an Outcome inside it.

availability decides who can use a set: platform (every organisation; created by System Access users), network (every organisation in a Network; created by that Network's admins) or charity (one organisation; created by its organisation admins).

A Cohort Tracker is a metric that counts the Contacts in a Project or Album who meet a set of Contact Filter criteria, e.g. "Children attending 75%+". It is placed in an Impact Scorecard column like other metrics and targeted with a number of Contacts to reach. Every tracker counts only members of the Project or Album it is placed on: membership is ever_enrolled (anyone whose status History shows them Enrolled at any time) or currently_enrolled.

A filtered version counts a standard metric again for only some responses and Contacts, e.g. "Session attendances — Female, under 21". The metric is a Change (Activity or Engagement tracker) or an Indicator (Choice, Achievement or Numerical tracker) already on the Project. It counts attendances or answers, not Contacts: to count Contacts, use a Cohort Tracker. It has its own row, name, column and targets on the Results Canvas, and Albums show every filtered version on their Projects.

response_criteria filters the responses, as a Progress Board's "Filter responses/stories by" does: story_category_ids (Surveys), wave_ids (Intervals), date_range (Date Happened, "dd/mm/yyyy - dd/mm/yyyy"), label_ids and author_ids. contact_criteria filters the Contacts tagged in them, in the Contact Filters format. Age is worked out at the date of each response; other Bio fields use the Contact's current value; the other sections are judged at the end of each reporting period.

Event Formats (Event Categories in the API) are the templates an organisation's events are created from, such as Workshops, Classes or Meetings. Only an Organisation Admin of the organisation that owns an Event Format can delete it, and only once it has no events and is not added to any project. Default formats can be deleted under the same rules.

Ratio Sets are reusable dropdown/list field definitions. Sub Ratios are the individual answer choices within a Ratio Set. Sub Ratio IDs are required when submitting Scale Indicator responses in a Story.

Case Forms (Custom Field Categories in the API) define the structured fields available on a Case. Each form contains Custom Field Definitions — the reusable fields — and Custom Field Category Definitions — the record created when a field is added to a form.