GSAPI Contract Management

Version: 2026_1
Audience: Integrators and consultants working with contract data via GSAPI
Purpose: Explain how to retrieve, create, update, and manage contracts and contract lines using the Good Sign REST API, with examples mapped to UI actions.

1. Overview

Contracts are a core entity in Good Sign. They define the commercial relationship between the selling organization and its customers, including:

• contract header data
• contract lines
• pricing
• usage mapping
• custom parameters

While the user interface offers visual tools to browse and edit contracts, GSAPI provides programmatic access to the same functionality.

This guide explains how to:

• list and retrieve contracts
• update contract data
• work with custom parameters
• retrieve contract lines
• update contract lines
• understand how contract transactions relate to contract lines

For a functional overview of contract structures, see:
https://support.goodsign.com/contracts-contract-lines

2. Prerequisites

Authentication:
GSAPI uses either Basic Auth (via /welcome) or token‑based authorization depending on environment setup.

Required Rights:

• 6000 (GSAPI access)
• 6001 (GSAPI write access)
• Contract menu rights as configured in the UI

Testing environment:
Use a dedicated integration or staging environment when testing contract updates.

3. Contracts in the UI

The Contracts view lists contract headers for the selected organization level.

Figure 1: Contracts list in the UI

This view displays:

• ContractID
• organization
• contract name
• validity
• contract line indicator
• custom identifiers (if configured)

Contract UI fields correspond to the fields returned by GSAPI.

4. Listing Contracts (GET)

Endpoint:

GET /interface/gsapi/contracts/list

This retrieves contracts filtered by organization or identifiers.
Same data as shown in the UI contract list.

Example parameters:

• org_id — retrieve contracts under a single organization
• organization — organization path, e.g. Root/Finland/Customer A
• ContractID — retrieve a single specific contract

Example URL:

GET .../contracts/list?org_id=1202

Example response excerpt:

[
  {
    "ContractID": "FINARA-00012",
    "company_name": "Finara",
    "parent_org_id": 0,
    "customParams": {
      "myfirstcustomparam": "is here"
    },
    "ContractLines": [
      {
        "objectkey": "F000000013",
        "ContractLineID": "F000000013"
      }
    ]
  }
] 

UI mapping:
The JSON fields correspond directly to the columns in the contract list.

5. Retrieving a Single Contract (GET)

Endpoint:

GET /interface/gsapi/contract/actions

Use this to retrieve the full contract header structure.

Example parameters:

• ContractID
• objectkey

This is the recommended way to fetch a contract for editing.

6. Editing a Contract (PUT)

Editing is usually done by:

1. Fetching the existing contract via GET
2. Using the response as the baseline for the update
3. Posting the modified fields back via PUT

Endpoint:

PUT /interface/gsapi/contract/actions

In the UI, editing is done by opening the contract header:

Figure 2: Contract Header editing view in the UI

Recommended workflow:

1. GET the contract
2. Remove JSON array brackets
3. Modify the necessary fields (e.g., description, validity, customParams)
4. Submit via PUT

Example:

 {
  "ContractID": "FINARA-00012",
  "description": "Updated contract description",
  "customParams": {
    "contractType": "Premium"
  }
}

Response:
The updated contract is returned, confirming the new state.

7. Contract Custom Parameters

If customer‑specific fields are added to the contract type, they appear under:

customParams: {
  "<key>": "<value>"
}

Examples:

• externalContractId
• contractCategory
• internalCostCenter

Custom parameters:

• can be added or updated via PUT
• follow JSON key/value format
• reflect what is configured in the metadata model

8. Creating a New Contract (POST)

Endpoint:

POST /interface/gsapi/contract/actions

Minimum recommended fields:

• company_name (or equivalent org reference)
• validity fields
• contract identifiers (e.g., externalContractId)

Custom parameters may also be included.

Example:

{
  "company_name": "Finara",
  "externalContractId": "FNR-2026-001",
  "customParams": {
    "businessSector": "Software"
  }
} 

The response contains the new contract's ContractID.

9. Copying Contracts

Good Sign supports:

• Copy this contract
• Create Contract from Template (internally uses contract copy logic)

These are available via UI and via API endpoints depending on customer configuration.

If enabled in the environment, copying is performed using specialized API actions.
(If needed, we can create a separate GSAPI Contract Copy article based on the dedicated template logic.)

10. Deleting / Terminating Contracts

Contract termination in the UI triggers:

• validation rules
• closing of contract validity
• updates to dependent contract lines

Termination can be automated via:

PUT /interface/gsapi/contract/actions

by setting validity end date and status fields.

Hard deletion is normally restricted and typically not exposed through GSAPI for audit reasons.

11. Contract Lines Overview

Contract lines define:

• the objectkey linked to the contract
• the pricing model
• mapping keys for usage
• validity periods
• custom parameters for the line

You can retrieve contract lines using:

GET /interface/gsapi/contractline/list

Fields commonly include:

• ContractLineID
• objectkey
• pricing model identifiers
• mapping keys
• validity

12. Editing Contract Lines (PUT)

Endpoint:

PUT /interface/gsapi/contractline/actions

UI editing is performed by selecting a contract line inside a contract.

Contract line updates often require:

• updating mapping keys
• extending validity
• adjusting custom parameters

Example:

{
  "ContractLineID": "F000000013",
  "mapping1": "DEVICE-123",
  "validfrom": "2026-01-01"
} 

13. Creating a Contract Line (POST)

POST /interface/gsapi/contractline/actions

Minimum fields depend on pricing model.
Common fields include:

• ContractID
• objectkey
• pricing fields
• mapping configurations

14. Terminating Contract Lines

Terminating a line typically sets:

• validity end date
• status
• flags preventing further billing

This matches UI termination behavior.

15. Transactions (Related but distinct from Contract Lines)

Transactions (usage events):

• are imported via GSAPI Contract Transactions, not via contract endpoints
• are linked to contract lines via mapping keys
• must pass mapping validation during invoice processing

Key considerations:

• duplicates are controlled by transactionId
• GSAPI does not validate mappingValue at import time
• transaction browsing is done via Datatables

For full details see:
https://support.goodsign.com/gsapi-data-import-contract-events

16. Viewing Contract‑Related Data in Datatables

Datatables provide a way to inspect imported usage, intermediate results, and contract‑related technical data.

Common tables:

• staging interfaces
• usage aggregate tables
• contract line resolution views

17. Summary

18. Consultant Notes (Advanced)

• When updating a contract or line, always retrieve the latest version first to avoid overwriting fields.
• Custom parameters must match defined metadata keys.
• Termination logic depends on pricing model and environment configuration.
• Contract copy features may vary by implementation and often follow customer-specific business rules.
• Transactions rely on correct mapping values; unmapped values accumulate silently and require reporting.