MtoN relations in REST API
The Joint Resource pattern
The recommended and implemented pattern for Many-to-Many (MtoN) relations in the Planon REST API is the Joint Resource pattern.
With this pattern, the relation between two entities is represented as a separate resource. In Planon terms: an MtoN relation is exposed as an MtoN Business Object (MtoN BO).
Why this is the best fit
• It is scalable (relation cardinality can grow without inflating either entity).
• It aligns with common API design and with how Planon exposes BOs through endpoints.
REST endpoint patterns
Per Endpoint patterns
• The API supports CRUD, plus Lookup and State change, plus Execute (BOM) operations.
• The API is versioned: /sdk/system/rest/{version}/...
• To avoid exposing too much information, we only use POST requests (even for read operations).
So, for an MtoN BO like PersonSkills, you typically use:
• POST /sdk/system/rest/v2/read/PersonSkills (read relation records)
• POST /sdk/system/rest/v2/execute/PersonSkills/BomAdd (create relation record)
• POST /sdk/system/rest/v2/update/PersonSkills (update relation metadata)
• POST /sdk/system/rest/v2/delete/PersonSkills (delete relation record)
Which MtoN BOs are exposed
Rule of thumb: Planon exposes only many-to-many (MtoN) business objects through REST when they connect:
• a configurable business object, and
• an authorizable business object.
How to use MtoN in REST
In this example, PersonSkills is used as endpoint:
• PersonSkills (read): POST /sdk/system/rest/v2/read/PersonSkills
PersonSkills is the joint resource linking (conceptually):
• Person (M side)
• Skill (N side)
The exact field names depend on the BO schema, but typically there are two reference fields like:
• PersonRef (reference to Person)
• SkillRef (reference to Skill)
1. Read: all skills for a person
POST /sdk/system/rest/v2/read/PersonSkills
Content-Type: application/json
{
"filter": {
"PersonRef": { "eq": 12345 }
}
}
Content-Type: application/json
{
"filter": {
"PersonRef": { "eq": 12345 }
}
}
Result: returns the relation records. Use SkillRef values to fetch skill details from the Skill BO endpoint.
2. Read: all persons for a skill
POST /sdk/system/rest/v2/read/PersonSkills
Content-Type: application/json
{
"filter": {
"SkillRef": { "eq": 1001 }
}
}
Content-Type: application/json
{
"filter": {
"SkillRef": { "eq": 1001 }
}
}
3. Create: add a person-skill link (create relation record)
POST /sdk/system/rest/v2/execute/PersonSkills/BomAdd
Content-Type: application/json
{
"values": {
"PersonRef": 12345,
"SkillRef": 1001
}
}
Content-Type: application/json
{
"values": {
"PersonRef": 12345,
"SkillRef": 1001
}
}
 | If the MtoN BO is date-aware, If the MtoN BO is date-aware, include the date fields required by the BO (see next section). |
Date-aware MtoN relations
• It must be possible to add and delete date-aware MtoN relation records.
• Date-aware MtoN relations typically have:
◦ Start date-time (mandatory)
◦ End date-time (optional)
Example (field names are illustrative; use the BO’s OpenAPI schema to confirm exact names):
POST /sdk/system/rest/v2/execute/[BODefinition]/BomAddContent-Type: application/json
{
"values": {
"SomeRef": 12345,
"SomeOtherRef": 1001,
"StartDateTime": "2026-01-01T00:00:00",
"EndDateTime": null
}
}
{
"values": {
"SomeRef": 12345,
"SomeOtherRef": 1001,
"StartDateTime": "2026-01-01T00:00:00",
"EndDateTime": null
}
}
4. Adding business object field definition
In the REST API you can also add a reference to the referring BO. So, in this example, you can use an existing REST API definition like Person to use as a reference for the PersonSkill BO. In this way you can see which Person has which skill with more details than just a reference field.
You can do this by going to the field definitions and selecting the PersonRef and selecting 'RESTAPIDEFINITION'. After selecting it you will see another field popping up and here you can select a definition.
After publishing the definition and doing a request, you will see the complete information of the person as you have configured it on the Person REST API definition.