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

GSAPI Data Import: Contract Events

Import usage or transaction events in bulk using GSAPI, including processing behavior and common pitfalls

Version: 2026_1
Audience: Customers and integrators importing usage or transaction events
Purpose: Explain how to import contract transaction records using GSAPI, how processing works, how to handle duplicates and validation errors, and how to generate transaction IDs when needed.

1. Overview

Contract-based usage models in Good Sign require transaction records to calculate consumption-based fees, such as:

  • quantity-based usage
  • event-based models
  • tiered consumption models
  • time-based consumption

This article describes how to import these transactions through the new unified GSAPI Contract Transactions endpoint, introduced for version 2026_1.

Key changes from older versions

Earlier Good Sign installations used two separate endpoints:

  • Single transaction: /contractevent/actions
  • Batch transactions: /contractevents/import

The new endpoint replaces both.
You now send transactions in an array, even when sending only a single item. [GSAPI_Cont...ansactions | Word]

Unique transaction IDs

Starting from 2026_1, new customer environments include a unique constraint on transactionId.
This improves transparency and prevents accidental duplicate billing.

If you do not have a transaction ID available, the API can auto-generate globally unique IDs.

2. Required User Rights

To import contract events, the following rights are required:

Right ID Description
3150 Contract Menu – right to send contract events
6000 GSAPI access
6001 GSAPI write access

Quick check:
If you see Contracts in the UI, you generally have the needed rights.

3. Endpoint

Standard environment URL:

POST https://api.goodsign.cloud/api/interface/gsapi/contract/transactions

To auto-create transaction IDs:

POST https://api.goodsign.cloud/api/interface/gsapi/contract/transactions?GenTransactionId=1

4. Transaction Fields

A contract transaction contains the following fields:

Field Description
transactionId Unique transaction ID for the event. Must be unique in 2026_1+ environments unless auto-generating.
timestamp Event time (yyyy-mm-dd hh:nn:ss).
productCode (Optional) Code of the product/service consumed.
quantity Decimal numeric value representing consumption. Can be aggregated later (SUM, AVG, etc.).
mappingValue Usage key linking the event to a contract line (example: ProductID + CustomerID).
dimension1–4 Optional attributes for grouping, reporting, or analysis. Each is a free-form business dimension.

5. Sending Transactions (Example)

Transactions must be sent inside a JSON array, even when sending only one.

Example POST body

Figure 1: Example batch transaction import

This example includes:

  • valid rows
  • a duplicate (SuperUniqueKey1 and SuperUniqueKey3)
  • an invalid timestamp (2026‑02‑32)

6. Understanding the Response

The response may be multi-status (HTTP 207) when the batch contains a mix of:

  • inserted items
  • discarded items
  • duplicate IDs
  • validation errors

Example response

Figure 2: Example 207 Multi-Status response

The response contains:

  • Lines – total rows received
  • Inserted – successfully added transactions
  • Discarded – duplicates + validation failures
  • Error node – per-item validation issues
  • Duplicate node – per-item duplicates

Example errors detected

  • invalid timestamp format
  • duplicate transactionId
  • negative quantity
  • invalid mappingValue

Duplicates and errors are shown separately for easier inspection.

7. Importing Transactions Without transactionId

If your source system does not have transaction IDs, you may ask GSAPI to generate them using a global GUID.

Use this endpoint:

POST https://api.goodsign.cloud/api/interface/gsapi/contract/transactions?GenTransactionId=1

Important rule

Do not include transactionId fields in your JSON when this parameter is used. 

8. Supported Methods

Only POST is supported.

To inspect imported rows, use Datatables under Interfaces.

9. Troubleshooting (Errors & ret-values)

Errors are returned with negative ret-values.
These errors are separate from per-row validation errors (timestamp, duplicates, etc.).

rettext Reason
Permission denied Missing right to send events
Array Expected JSON was not an array
Malformatted or empty JSON JSON parsing failed or message body was empty

The server may also return 4xx HTTP error codes depending on request validity.

10. Summary

Topic Description
Endpoint /api/interface/gsapi/contract/transactions
Format JSON array
Unique IDs Required from 2026_1+
Auto-generate IDs Use ?GenTransactionId=1
Processing Batch may insert some rows and discard others
Errors Mixed results returned in 207 multi-status
Validation No mappingValue validation at import time