GSAPI Object Charge Sharing

Version: 2026_1
Audience: Customers and integrators managing shared-cost allocations
Purpose: Explain how to configure Object Charge Sharing in Good Sign using the UI, GSAPI, or interface import, and how share multipliers work.

1. Overview

Object Charge Sharing allows you to split an object’s charges across multiple organizations.

This is useful in situations such as:

• shared assets
• inter-departmental cost allocation
• multi-entity service consumption
• internal rebilling needs

The feature is available starting from version 2025_2, and can be managed:

• in the UI,
• via GSAPI, or
• through file import using an interface action.

All sharing definitions consist of one or more organizations and multipliers that sum to 1.0.

2. Required User Rights

To edit Object Charge Sharing in the UI:

GSAPI and interface import require the general API access rights:

3. Editing Shares in the UI

Navigate to Objects, right‑click the object, and select Object Charge Sharing.

Figure 1: Opening Object Charge Sharing from the UI

This opens the Share Editor.

What the Share Editor shows

• current sharing definition (if any)
• organizations available for sharing
• multiplier values for each organization
• total multiplier sum

Adding a new share

1. Enter a description (optional, for documentation only).
2. Select an organization.
3. Add a multiplier.
4. Repeat for each share fragment.
5. Ensure that all multipliers sum to 1.0.
6. Save.

Figure 2: Object Charge Sharing editor

Descriptions are not delivered to invoices; they are purely for user clarity.

4. Managing Shares Through GSAPI

You can retrieve, update, or create charge sharing definitions via GSAPI.

4.1 GET an object’s share

Attach to the object using one of:

• share_id
• objectId (numeric representation of object)
• ObjectKey (unique object key)
• ObjectName (not unique)

Example GET call

 GET https://api.goodsign.cloud/api/interface/gsapi/objectshare?action=get&ObjectKey=12345

Figure 3: Example GET response showing ShareDetails

ShareDetails includes:

• org_id or organization path
• multiplier
• technical row identifiers

4.2 POST/PUT to create or update a share

You may send share definitions using either POST or PUT (both create/update).
Example structure:

 {
  "share_id": 1001,
  "ObjectKey": "12345",
  "ShareDetails": [
    { "org_id": 500, "multiplier": 0.7 },
    { "org_id": 501, "multiplier": 0.3 }
  ]
}

Rules

• Multipliers must sum to 1.0
• Organization must be referenced through either org_id or full path
• Description is optional
• Existing definitions are overwritten unless share_id changes

5. Editing Shares Using File Import

Shares can also be created or updated using a query2proc interface with the action Import Shares.

How to configure

1. Create a new interface.
2. Choose Import Shares as the action.
3. Upload your file through Data Inbound Settings.

File content

The example file uses a JSON‑in‑cell approach:

• The sharedetails column must contain a JSON array of share objects.
• This is required because the system must reliably validate multiplier totals.

Example snippet from the source document:

"sharedetails": [
  { "organization": "Root/Dept A", "multiplier": 0.50 },
  { "organization": "Root/Dept B", "multiplier": 0.50 }
] 

Figure 4: File import example with sharedetails JSON

After import

Good Sign reports:

• created shares
• updated shares
• any errors

Multiplayer sum validation ensures no leakage occurs.

6. Summary

7. Consultant Notes (Advanced)

API identifiers

objectId, ObjectKey, and share_id can all uniquely identify shares. Use the most stable one for integrations; ObjectKey is typically preferred.

Validation

• Multipliers must sum to exactly 1.0; any deviation causes errors.
• JSON in sharedetails must be valid and parsable.

Common failure cases

• organization not resolved
• undefined object references
• malformed JSON in sharedetails
• multiplier total != 1.0
• incorrect casing in organization paths

Batch processing

Bulk updates should be split into smaller files if share rows exceed several thousand entries.