Skip to content
  • There are no suggestions because the search field is empty.

ITONICS REST API: POST and PUT requests

What is it?

This article covers the endpoints and input formats for creating (POST) and updating (PUT) content in your ITONICS application via the REST API - elements, submissions, table data and roadmaps.

This article is part of the ITONICS REST API series. For the overview, refer to Overview and getting started. For the authentication required for writing requests (X-CSRF token or OAuth 2.0 access token), refer to Authentication and authorization.

This article details the endpoints and required input formats for creating (POST) and updating (PUT) data. Unlike GET requests, these operations require a specific JSON body and proper X-CSRF token authentication to successfully modify resources in your ITONICS application. These writing operations are essential for automated data injection and synchronization within your ITONICS application.

Note: POST and PUT requests are not available for the /api/user.json endpoint, you can only use GET.

Check out our public Postman API collection:

This dedicated resource provides detailed sample request bodies and complete output formats for all GET, POST, and PUT endpoints, ensuring you quickly understand the necessary technical specifications and expected JSON formats.

In this article

  • POST requests (Create)
  • PUT requests (Update)
  • POST & PUT field input formats

POST requests (Create)

The following sections describe the endpoints available for creating new data records (elements, users, etc.) in your ITONICS application via POST requests.

New element

  • Endpoint: /api/{entity_type}.json
  • Sample request: /api/itonics_trend.json

Creates a new element of the specified {entity_type}. All data for the different fields must be provided in the request body. Note that it is possible to define the creator value if a valid username in the system.

Retrieve field configuration details (incl. required machine names) by querying the /api/entity_field_properties.json?type={entity_type} GET endpoint for the relevant {entity_type}.

Child entity types: where the entity type has the Parent-Child module enabled, the parent_relation is mandatory and is validated in all statuses, including draft ("status": 0). Requests omitting it return a mandatory field validation error. The parent_relation metadata (incl. required, type, and entity_type) is returned by the /api/entity_field_properties.json?type={entity_type} GET endpoint.

Required permissions:

  • "Create {entity_type}" permission (entity-level)
  • "Access the resource {entity_type} via API" permission (entity-level)

New submission/Idea

  • Endpoint: /api/itonics_idea.json
  • Sample request: /api/itonics_idea.json

Creates a new submission/idea element of type itonics_idea. All data for the different fields must be provided in the request body.

Supported fields are submission default fields (Title, Abstract, Authors, Tags, Header Image, Description), and custom submission fields. Retrieve field configuration details (incl. required machine names) by querying the /api/entity_field_properties.json?type=itonics_idea GET endpoint.

Mandatory field values: Title, Abstract, Authors (multi-select), and a valid campaign_id (single-select), and Tags, Description, Header Image, and custom submission fields if set as required.

Custom submission field validation: Values are validated against the field configuration retrieved from the field properties endpoint. A rejected request returns 422 Unprocessable Entity identifying the field, and nothing is stored - where a multi-value field contains one invalid entry, the valid entries are not partially saved. Where is_multiple is false, an array is rejected: single line input fields expect a string, and radio button fields a single option ID. Where is_multiple is true, values are passed as an array and each entry is validated individually. List field and radio button values must be the option ID, not the option label; an option ID not configured on the field is rejected. A field with isNumber rejects non-numeric values, accepting only a point decimal separator and a leading negative sign, while isEmail and isUrl reject values not matching the respective format. A user search field receiving more users than its limit_number is rejected, whereas a request at exactly the maximum succeeds; a username or email matching no user in the system is rejected. Date picker fields expect YYYY-MM-DD - a syntactically valid but non-existent calendar date is rejected. Mandatory custom submission fields that are omitted are reported by the existing required-field response rather than a per-field validation error.

Status handling:

  • status: 0 (Draft): Created as Draft, phase information is ignored
  • status: 1 or >0 (Published)
  • Status not provided: Created as Published (time-bound campaign = active phase, and always-on campaign = first phase)

Phase handling: Including phase_id and status in the POST request automatically publishes the submission element. Provided phase_id is ignored, and the assignment is handled automatically: time-bound campaign = active phase, and always-on campaign = first phase.

Further information: You can publish submissions to a campaign that is inactive (e.g., not yet started or past its end date), but publishing to a campaign in Draft status is not allowed. Be aware that the system will verify that the provided user value for the creator property is a valid participant of the associated campaign.

Required permissions:

  • "Access the resource itonics_idea" permission (must be set by ITONICS)

PUT requests (Update)

The following sections describe the endpoints available for updating or manipulating existing data records in your ITONICS application via PUT requests.

Update element

  • Endpoint: /api/{entity_type}/{id}.json
  • Sample request: /api/itonics_trend/42.json

Updates the element of type {entity_type} matching the URI {id}. Note: An error is returned if the ID does not exist. All attributes of the element are updated / overwritten, while all data for the different fields must be provided in the request body. Note that it is possible to define the creator value if a valid username in the system.

Retrieve field configuration details (incl. required machine names) by querying the /api/entity_field_properties.json?type={entity_type} GET endpoint for the relevant {entity_type}.

Child entity types: the parent_relation is mandatory and is validated in all statuses, including draft ("status": 0). Updates omitting it return a mandatory field validation error. The parent_relation metadata (incl. required, type, and entity_type) is returned by the /api/entity_field_properties.json?type={entity_type} GET endpoint.

Required permissions:

  • "Edit {entity_type}" permission (entity-level)
  • "Access the resource {entity_type} via API" permission (entity-level)
  • + "Edit all {entity_type}" permission (entity-level) → access to edit all elements of the respective entity type
  • + "Edit own {entity_type}" permission (entity-level) → access to edit own elements created by the particular user

Update submission/idea

  • Endpoint: /api/itonics_idea/{id}.json
  • Sample request: /api/itonics_idea/10.json

Updates the submission element matching the URI {id}. Note: An error is returned if the ID does not exist. All attributes of the element are updated/overwritten, while all data for the different fields must be provided in the request body.

Supported fields are submission default fields (Title, Abstract, Authors, Tags, Header Image, Description), and custom submission fields (list fields, textarea fields, RTE fields, date fields, and user search fields). Retrieve field configuration details (incl. required machine names) by querying the /api/entity_field_properties.json?type=itonics_idea GET endpoint.

Custom submission field validation: The same validation applies as on the POST endpoint - refer to New submission/Idea above. A rejected update leaves the stored value unchanged. A mandatory field cannot be cleared: passing null or an empty value returns a validation error and the existing content is preserved. For list fields, a PUT replaces the stored selection rather than adding to it.

Status handling:

  • Status: 0 (Draft): Status remains Draft unless explicitly changed
    • No phase_id required (note: phase_id can be retrieved from campaign GET endpoint)
    • Only field data is updated, status remains unchanged unless explicitly set
  • Status: 1 or >0 (Published): Status remains Published unless explicitly changed
    • Published submission cannot be updated back to Draft status
    • Remains in the active phase (time-bound) or first phase (always-on)

Phase handling:

  • Valid phase_id:
    • Always-on campaigns: Submissions can be moved to a valid phase_id. Updating to/from the Declined phase is possible (except updating from Declined to a phase other than the first)
    • Time-bound campaigns: Phase assignment is ignored, the submission remains in the active phase
  • Invalid phase_id:
    • Draft submission gets published
    • Published submission remains published and stays in active- (time-bound) or first phase (always-on)
    • Field data are updated as expected

Further information: You can update submissions of an inactive campaign (not yet started, or end date exceeded). However, updating the campaign_id via PUT is not possible, while the campaign_id is not mandatory when updating a submission. Be aware that the system will verify that the provided user value for the creator property is a valid participant of the associated campaign.

Required permissions:

  • "Access the resource itonics_idea" permission (must be set by ITONICS)

Update table data

  • Endpoint: /api/table_data.json?entity_type={entity_type}&entity_id={entity_id}
  • Sample request: /api/table_data.json?entity_type=itonics_technology_tr3&entity_id=10

Updates the table data of an element matching the URI {id}. Note: An error is returned if the ID does not exist. All data information about different fields to be updated must be provided in the request body.

Supported field types in a table structure are currently text fields, dropdown fields, percentage fields, element fields, user search fields, and date picker fields.

The requested body must maintain the hierarchy of a table structure: table_machine_name -> rows -> option_key -> column_data.

Note: Multiple rows and multiple column fields can be updated within a single PUT request by adding additional keys to the rows or column_data objects.

Locked tables: Where a table structure has the Lock table for editing setting enabled, rows can still be created, updated, and deleted via this endpoint. The lock applies to the interface only and does not restrict API writes or Excel import. Validation and error responses are identical to those of an unlocked table. The lock state is returned as the locked property by the /api/entity_field_properties.json?type={entity_type}&config=table_data GET endpoint.

Required permissions:

  • "Access table structures via API" permission (global permission)
  • + "View all {entity_type}" permission (entity-level)
  • + "View own {entity_type}" permission (entity-level) → access to edit own elements created by the particular user

Update roadmap

  • Endpoint: /api/roadmap/{id}.json
  • Sample request: /api/roadmap/10.json

Updates an existing roadmap matching the URI {id}. Note: An error is returned if the ID does not exist. The request body supports separate arrays for elements, milestones, connections, deleted_milestones, and deleted_connections, of which at least one must be provided.

Be aware that the endpoint operates on roadmap records, not on the elements themselves: only existing elements of entity types with the Roadmap module enabled can be added to, updated on, or moved between the existing layers of the roadmap - creating new elements or layers via this endpoint is not possible. Each element can only appear once per request. Milestones and connections can be created, updated, and deleted.

Element handling: element_id, entity_type, and layer_id are required; start and end dates are required when adding an element to the roadmap and optional for updates (omitted dates retain the stored values). Optionally, a per-element background color can be provided as a hex value. For entity types with synced roadmap dates enabled, the optional date_mode property controls the date behavior: "sync" pulls the dates from the element's synced date fields (provided dates apply across all roadmaps containing the element), while "custom" detaches the element and applies the provided dates to this roadmap only. Note: switching an element back from custom to synced dates requires the "Update element sync date " permission.

Milestone handling: Milestones are created (no id provided), updated (existing id provided), or deleted (via deleted: true or the deleted_milestones array). Mandatory and custom milestone fields are validated against the milestone configuration of the respective entity type - retrieve it upfront via the GET /api/entity_field_properties.json?type={entity_type}&config=milestone endpoint.

Connection handling: Connections can be created between elements and milestones in any combination (element-to-element, element-to-milestone, milestone-to-element, milestone-to-milestone). The connection is always provided from the source (origin) perspective, specifying the target in the connection data - the connection must not be listed again on the target (in line with the Roadmap Excel import). Optionally, a connection_type_id can be provided; it must be enabled for the roadmap.

Required permissions:

  • "Use roadmap PUT API" permission (global permission; granted to the Application Owner role by default) - additionally, the user must have edit access to the particular roadmap.

POST & PUT field input formats

When creating (POST) or updating (PUT) data, use the following input formats for common ITONICS field types to ensure your requests are processed correctly.

Endpoint /api/{entity_type}.json for element creation and /api/{entity_type}/{id}.json for element update:

Field type Example field value Expected value in the request body Notes on structure
Single line input field of type text (Title) Creative AI "field_machine_name": "string" Expects a simple string value
Simple text field (Abstract) Creative AI (CAI) is the branch of artificial intelligence. "field_machine_name": "string" Expects a simple string value
Rich text editor (RTE) field (Description) Creative AI technologies have the potential to fundamentally alter … "field_machine_name": "string with <b>HTML</b> tags" Expects text content, including HTML tags for formatting
Image file (Header image) (Base64 encoded) Image file "field_machine_name": "encoded_image_data:image/png;base64,X…" Expects a base64 encoded string prefixed with the data URI scheme (e.g. data:image/png;base64,X…)
Single line input field of type URL, Email, Number https://www.itonics-innovation.com/
jane.innovation@itonics-innovation.com
100
Multi-select case: 100, 200, 300		 "field_machine_name": "URL string"
"field_machine_name": "email string"
"field_machine_name": "number string"
"field_machine_name": ["number/string", "number/string", "number/string"]		 Expects a simple string or numerical value represented as a string.
Note: Multi-select fields expect an array of strings, or numbers / emails represented as a string.
List fields: (Searchable) Dropdown (single-select) Single-select case: R&D "field_machine_name": 166 Expected value is the option_id of the selected field option, expected as an integer.
List fields: (Searchable) Dropdown (multi-select) Multi-select case: R&D, Marketing "field_machine_name": ["166", "167"] Expected value is an array of strings, where each string is the option_id of a selected item.
Radio button Active "field_machine_name": "field_option_id" Expected value is the option_id of the selected field option, expected as a string.
Single checkbox Yes "field_machine_name": 1 Expected value is an integer: 1 for 'Yes' (checked), 0 for 'No' (unchecked).
Pearl chain (with check) In progress "field_machine_name": "field_option_id" Expected value is the option_id of the selected field option, expected as a string.
Segment/ hierarchy field Technology Segment > Technology Sub-segment (each level can be multi-select):
ICT > AI & Engineering > Machines & Robotics		 "segment_field_machine_name": {"segment_field_machine_name_entity_segment": ["segment_field_option_id", "segment_field_option_id"], "sub_segment_field_machine_name_entity_sub_segment": ["segment_field_option_id", "segment_field_option_id"]} Expects a JSON object where keys are the machine names of the segment levels (e.g., segment_field_machine_name_entity_segment) and values are arrays of strings containing the segment field option_ids. Unused levels can be an empty string "".
Date picker field 2025-01-25 "field_machine_name": "YYYY-MM-DD" Expected value is a string in the specified date format (YYYY-MM-DD).
Term search field (Tags) - (single and multiple tags) artificial intelligence 
artificial intelligence, machine learning		 "Tags": "artificial intelligence"

"Tags": ["artificial intelligence", "machine learning"]		 Single tag: Expected value is a string. Multiple tags: Expected value is an array of strings, where each string is one tag. A single string is saved as one tag, including any commas it contains.
User search field (USF) (single-, and multi-select) Jane Innovation
Jane Innovation, John Doe		 "field_machine_name_username": "jane.innovation"
"field_machine_name_username": ["jane.innovation", "john.doe"]		 Single-select USF: Expected value is a string corresponding to the username used in the application.
Multi-select USF: The expected value is an array of strings, where each string is a username used in the application.
User group search field (UGSF) Experts & Collaborators (groups)
R&D & IT (contexts)		 "field_machine_name": {"group": ["1", "3"], "context": ["9", "10"]} Expects a JSON object containing two keys: "group" and "context", each with an array of strings representing the respective option_ids.
Element search fields (ESF) (single-, and multi-select) OpenAI (company), AR for machine maintenance (innovation project) "field_machine_name": {"entity_type_machine_name": [20, 21], "entity_type_machine_name": [3, 5]} Expects a JSON object where keys are the machine names of the target entity types (e.g., itonics_project_tr3) and values are an array of integers representing the entity_ids of the linked elements.
File fields (single-, and multi-select) File1.png
File1.png, file2.xlsx		 "field_machine_name": "file1_base64"
"field_machine_name": ["file1_base64", "file2_base64"]		 Expected value must be the base64 encoded string of the file content. For multi-select, the expected value is an array of strings, where each string is the base64 encoded string of a file content.
(Element-) Relations OpenAI (company), AR for machine maintenance (innovation project) "relations": {"entity_type_machine_name": [120, 35], "entity_type_machine_name": [45, 67]} Expects a JSON object where keys are the machine names of the target entity types (e.g., itonics_project_tr3) and values are an array of strings representing the entity_ids of the related elements.