API Reference v2.0.0
Makerble API
The Makerble API gives you programmatic access to your CRM and impact measurement data — contacts, projects, surveys, cases, outcomes, and more.
| Property | Value |
|---|---|
| Base URL | https://makerble.com/api/v2 |
| Staging URL | https://staging.makerble.com/api/v2 |
| Mock URL | {{HOST}}/mock |
| Protocol | HTTPS · JSON · REST |
| Auth | Token-based headers — X-User-Email + X-User-Token |
| Spec | openapi.yaml · OpenAPI 3.0.3 |
Security
Authentication
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:
| Header | Value |
|---|---|
| X-User-Email | Your Makerble account email address |
| X-User-Token | Your authentication token from POST /users/sign_in |
Multi-user integrations: If you need activity attributed to specific users, authenticate separately per user. A single Organisation Admin token is fine when attribution to a single admin is acceptable.
POST
/users/sign_in
Authenticate — obtain a token
Submit your email and password to receive your authentication token. Use this token in the X-User-Token header on all subsequent requests.
Request body (form-urlencoded)
| Field | Type | Description | |
|---|---|---|---|
| user[email] | string | required | Your Makerble email address |
| user[password] | string | required | Your Makerble password |
Responses
200Returns
user_id, email, and authentication_token401Invalid credentials
Reference
Pagination
All list endpoints support cursor-free offset pagination. The maximum per_page is 200.
| Parameter | Type | Default | Max | Description |
|---|---|---|---|---|
| page | integer | 1 | — | Page number |
| per_page | integer | 10 | 200 | Records per page |
| last_sync_datetime | string | — | — | ISO 8601 datetime — return only records updated after this value. Useful for incremental sync. |
All paginated responses wrap results in:
{ page, page_size, page_count, total_count, data: [] }
Reference
Terminology
Makerble uses different terms in the front-end UI and the API. The API uses the back-end terms listed below.
| Front-end (UI) | API (back-end) |
|---|---|
| Organisation | Charity |
| Contact | Beneficiary |
| Contact Bio Form | Beneficiary Category |
| Survey | Story Category |
| Survey Campaign | Project Story Category |
| Survey Response / Timeline Update | Story |
| Activity / Engagement tracker | Change (stage: activity / participation) |
| Achievement / Choice / Numerical tracker | Indicator (type: binary / scale / value) |
| Dropdown / List field | Ratio Set |
| Answer Choice | Sub Ratio |
| Case Form | Custom Field Category |
Developer tools
Mock server
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.
The mock server enforces authentication headers. Pass any non-empty values for
X-User-Email and X-User-Token to receive 200 responses rather than 401s.
Example curl request to the mock
curl {{HOST}}/mock/beneficiary_types -H "X-User-Email: test@example.com" -H "X-User-Token: mock-token"
Core resource
Organisations
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.
GET
/charities/{id}
Get a single Organisation
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| id path |
integer | required | Organisation ID |
Responses
200Charity record with id, name, timestamps
401Not authenticated
404Not found
Core resource
Projects
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).
GET
/projects
List all Projects
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| page query |
integer | Page number (default 1) | |
| per_page query |
integer | Records per page (default 10, max 200) | |
| last_sync_datetime query |
string | ISO 8601 — return only records updated after this |
Responses
200Paginated list of Projects
401Not authenticated
GET
/projects/{id}
Get a single Project
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| id path |
integer | required | Project ID |
Responses
200Project record
401Not authenticated
404Not found
POST
/projects/add_colleague.json
Add users to a Project
Requires authentication
Grant one or more users a role on a Project. A user can hold Editor, Reporter, and Observer simultaneously. Pass user IDs in
role_data[].editor_ids, reporter_ids, or observer_ids.Responses
200Users added successfully
401Not authenticated
422Validation failed
Core resource
Users
Platform users with login credentials. Creating users requires a separate API Key — request one at api-key-request@makerble.com.
GET
/users
List all Users
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| page query |
integer | Page number | |
| per_page query |
integer | Records per page | |
| last_sync_datetime query |
string | ISO 8601 incremental sync |
Responses
200Paginated list of Users
401Not authenticated
GET
/users/{id}
Get a single User
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| id path |
integer | required | User ID |
Responses
200User record
404Not found
POST
/users
Create a new User
Requires an
auth_code API Key. Password must be 8+ chars with at least one number, special character, and capital letter.Responses
200User created — returns id and email
422Validation failed (check password requirements)
Core resource
Contacts
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.
Workflow tip: Call
GET /beneficiary_types to get the beneficiary_type_id (1=Person, 2=Object, 3=Organisation, 4=Animal) and GET /custom_fields to discover custom field IDs before creating a Contact.
GET
/beneficiaries
List all Contacts
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| page query |
integer | Page number | |
| per_page query |
integer | Records per page | |
| charity_id query |
integer | Filter to Contacts in this Organisation | |
| project_id query |
integer | Filter to Contacts enrolled in this Project | |
| last_sync_datetime query |
string | ISO 8601 incremental sync |
Responses
200Paginated list of Contacts including custom fields
401Not authenticated
GET
/beneficiaries/{id}
Get a single Contact
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| id path |
integer | required | Contact ID |
Responses
200Full Contact profile with all custom fields
404Not found
POST
/beneficiaries
Create a Contact
Requires authentication
Required fields:
beneficiary.name, beneficiary.owner_id (User ID of the record owner). Submit custom field values as custom_fields: {"field_id": "value"}.Responses
200Contact created
422Validation failed (name and owner_id are required)
GET
/beneficiaries/impact_box_data
Get Impact Box data (Progress Trackers per Contact)
Requires authentication
Returns the data shown in the Progress Trackers box on a Contact Profile — total impact progress attributed to each Contact across all Changes and Indicators.
Parameters
| Name | Type | Description | |
|---|---|---|---|
| page query |
integer | Page number | |
| per_page query |
integer | Records per page |
Responses
200Aggregated metric progress per Contact
GET
/beneficiary_types
List Contact Types
Requires authentication
Responses
200Person (1), Object (2), Organisation (3), Animal (4)
GET
/project_beneficiaries
List Project–Contact associations
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| page query |
integer | Page number | |
| per_page query |
integer | Records per page |
Responses
200Join table records
Schema
Contact Bio Forms
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.
GET
/beneficiary_categories
List all Contact Bio Forms
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| page query |
integer | Page number | |
| per_page query |
integer | Records per page |
Responses
200Paginated list of forms
GET
/beneficiary_categories/{id}
Get a single Contact Bio Form
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| id path |
integer | required | Form ID |
Responses
200Form schema
404Not found
GET
/custom_fields
List custom field definitions
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| beneficiary_category_ids[] query |
integer | Filter by Contact Bio Form ID (repeat for multiple) | |
| page query |
integer | Page number | |
| per_page query |
integer | Records per page |
Responses
200Field definitions with IDs, names, and types
Core resource
Cases
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).
Workflow tip: Call
GET /custom_field_categories to discover field definition IDs before creating a Case.
GET
/cases
List all Cases
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| page query |
integer | Page number | |
| per_page query |
integer | Records per page | |
| last_sync_datetime query |
string | ISO 8601 incremental sync |
Responses
200Paginated list of Cases
POST
/cases
Create a Case
Requires authentication
Required:
project_id, beneficiary_id. Submit case form values in custom_field_categories_definition: {field_definition_id: value}.Responses
200Case created
422Validation failed
GET
/custom_field_categories
List Case Forms (field schemas)
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| page query |
integer | Page number | |
| per_page query |
integer | Records per page |
Responses
200Case Form schemas with field definition IDs
GET
/projects_beneficiaries_cases
List Project–Contact–Case associations
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| page query |
integer | Page number |
Responses
200Join table records
Surveys & Stories
Surveys
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.
Always call
GET /story_categories/:id before posting a Story. It returns the survey's fields, Indicator IDs, Outcome IDs, and valid Sub Ratio IDs — all of which are required in the Story payload.
GET
/story_categories
List all Surveys
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| page query |
integer | Page number | |
| per_page query |
integer | Records per page |
Responses
200Paginated list of Surveys
GET
/story_categories/{id}
Get a Survey with full field detail
Requires authentication
Returns all questions in order (
current_fields), the choice type (single/multiple) for each Scale Indicator (scale_indicator_choices), and scoring bands (verdict_data).Parameters
| Name | Type | Description | |
|---|---|---|---|
| id path |
integer | required | Survey ID |
Responses
200Survey with current_fields, scale_indicator_choices, and verdict_data
404Not found
GET
/story_categories/{id}/verdicts
Get verdict scores for a Survey Campaign
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| id path |
integer | required | Survey ID |
| project_id query |
integer | required | Project the Survey Campaign belongs to |
| page query |
integer | Page number |
Responses
200Total points per Contact per submission, grouped by beneficiary
GET
/project_story_categories
List Survey Campaigns
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| page query |
integer | Page number | |
| per_page query |
integer | Records per page |
Responses
200Surveys deployed to specific Projects
Surveys & Stories
Stories
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.
GET
/stories
List all Stories
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| page query |
integer | Page number | |
| per_page query |
integer | Records per page | |
| last_sync_datetime query |
string | ISO 8601 incremental sync |
Responses
200Paginated list of Stories with custom fields and beneficiary IDs
GET
/stories/{id}
Get a single Story
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| id path |
integer | required | Story ID |
Responses
200Full Story with custom_fields, case_ids, story_indicator_beneficiaries, story_changes, verdict_scores
404Not found
POST
/stories
Create a Story
Requires authentication
Creates a Story tagged to zero, one, or multiple Contacts. Required:
Use
For binary indicators: include
story.project_id, story.story_category_id, story.story_group: "change_created", story.story_format: "old".
Use
story_indicator_beneficiaries for indicator responses, story_changes for metric totals, and custom_fields for survey text/date/time fields.
For binary indicators: include
binray_indicator_value: "on" if ticked — omit the record entirely if not ticked. Activity Changes cannot be tagged to individual Contacts.Responses
200Story created
422Validation failed
GET
/stories/story_category_response
Get Stories with full survey response detail
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| story_category_id query |
integer | Filter by Survey | |
| project_ids[] query |
integer | Filter by Project ID (repeat for multiple) | |
| start_date query |
string | YYYY-MM-DD — stories on or after this date | |
| end_date query |
string | YYYY-MM-DD — stories on or before this date |
Responses
200Stories enriched with named Indicators, Changes, and Custom Field values — ideal for reporting
GET
/stories/{id}/attachments
Get attachments for a Story
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| id path |
integer | required | Story ID |
Responses
200Paginated media attachments
Surveys & Stories
Story Metrics
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.
GET
/story_changes
List Story Changes
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| story_id query |
integer | Filter to a specific Story | |
| page query |
integer | Page number |
Responses
200Per-story metric totals for Activity and Participation Changes
GET
/story_change_beneficiaries
List Story Change Beneficiaries
Requires authentication
Only applies to Participation type Changes (not Activity).
Parameters
| Name | Type | Description | |
|---|---|---|---|
| page query |
integer | Page number |
Responses
200Per-Contact Participation Change records
GET
/story_indicators
List Story Indicators
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| story_id query |
integer | Filter to a specific Story | |
| page query |
integer | Page number |
Responses
200Total indicator progress logged per Story
GET
/story_indicator_beneficiaries
List Story Indicator Beneficiaries
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| story_id query |
integer | Filter to a specific Story | |
| page query |
integer | Page number |
Responses
200Per-Contact indicator responses — one record per Contact per Indicator per Story
GET
/story_beneficiaries
List Story Beneficiaries
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| page query |
integer | Page number |
Responses
200Direct Contact-to-Story tagging records
Impact framework
Changes
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.
GET
/changes
List all Changes
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| page query |
integer | Page number | |
| per_page query |
integer | Records per page | |
| last_sync_datetime query |
string | ISO 8601 incremental sync |
Responses
200Paginated list of Changes with stage (activity/participation)
Impact framework
Indicators
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).
GET
/indicators
List all Indicators
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| page query |
integer | Page number | |
| per_page query |
integer | Records per page |
Responses
200Paginated list with indicator_type (scale/binary/value)
GET
/indicators/{id}
Get a single Indicator
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| id path |
integer | required | Indicator ID |
Responses
200Full Indicator detail including ratio_set_id, default_question
404Not found
GET
/scale_indicator_choices
Get Scale Indicator choices
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| story_category_id query |
integer | Filter by Survey | |
| indicator_id query |
integer | Filter by Indicator |
Responses
200Choice type (single_choice/multiple_choice) per Scale Indicator
GET
/outcome_indicators
List Outcome–Indicator pairings
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| page query |
integer | Page number |
Responses
200Join table — use to find outcome_id for story indicator responses
Impact framework
Outcomes
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.
GET
/outcomes
List all Outcomes
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| page query |
integer | Page number | |
| per_page query |
integer | Records per page |
Responses
200Paginated list with title, icon, stage (short_term/medium_term/long_term)
GET
/outcomes/{id}
Get a single Outcome
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| id path |
integer | required | Outcome ID |
Responses
200Outcome record
404Not found
Reference data
Ratio Sets & Sub Ratios
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.
GET
/ratio_sets
List all Ratio Sets
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| page query |
integer | Page number | |
| per_page query |
integer | Records per page |
Responses
200Paginated list — type: identity (Contact Bio Forms) or progress (Scale Indicators)
GET
/sub_ratios
List Sub Ratios (Answer Choices)
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| ratio_set_ids[] query |
integer | Filter by Ratio Set ID (repeat for multiple) | |
| page query |
integer | Page number |
Responses
200Answer choices with priority, default_criteria, and default_points for verdict scoring
GET
/sub_ratios/{id}
Get a single Sub Ratio
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| id path |
integer | required | Sub Ratio ID |
Responses
200Sub Ratio record
404Not found
GET
/ratio_set_choiceables
List Ratio Set selection rules
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| beneficiary_category_ids[] query |
integer | Filter by Contact Bio Form ID |
Responses
200Single/limited_multiple/unlimited_multiple choice rules per Ratio Set
Reference data
Case Forms
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.
GET
/custom_field_categories
List all Case Forms
Requires authentication
Parameters
| Name | Type | Description | |
|---|---|---|---|
| page query |
integer | Page number | |
| per_page query |
integer | Records per page |
Responses
200Case Form schemas with field definition IDs and types