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

GSAPI Overview

A high‑level introduction to Good Sign’s REST API, its purpose, and how it powers automated data flow

Version: 2026_1
Audience: Customers, integrators, and consultants using Good Sign for automated data flows
Purpose: Provide a clear introduction to the Good Sign API (GSAPI), how it fits into the platform, and which capabilities it offers.

1. What Is GSAPI?

GSAPI (Good Sign API) is the REST-based interface that allows external systems to exchange data with Good Sign.
It is used for:

  • importing transactional or master data
  • updating pricing
  • sending or managing invoice batches
  • creating or modifying object charge shares
  • automating processes that would otherwise require UI interaction

GSAPI is designed for system‑to‑system integrations, but many customer users also utilize it for bulk updates, automation, and reporting.

2. When to Use GSAPI

You should consider using GSAPI when you need to:

  • send data automatically (usage, objects, pricing, events)
  • integrate Good Sign with other systems (ERP, CRM, billing engines)
  • manage invoicing activities programmatically
  • update pricing at scale
  • monitor or react to changes in Good Sign (via Webhooks or QueryMonitor)

GSAPI is the recommended path for high‑volume, automated, repeatable processes.

Examples:

Scenario Recommended Action
Import device usage Contract Events Import / Interface Import
Synchronize product or organization data Interface Import
Update thousands of prices Pricing Change API or Excel Import
Monitor invoice batches via integration Invoice Batches API
Trigger external system updates Webhook Adapter
Split charges across organizations Object Charge Sharing API

3. How GSAPI Fits Into the Good Sign Data Flow

GSAPI sits at the beginning of the Good Sign process pipeline.

External System → GSAPI → Staging Tables → Processing Engine → Objects / Charges → Invoicing → Reporting

Typical flow

  1. Data received via GSAPI
  2. Data is stored in a staging table (e.g., EventDataImport)
  3. Good Sign processes staged rows
  4. Objects/charges are created or updated
  5. Invoices are generated via schedules
  6. Results are visible in UI dashboards (Invoice Monitoring, Datatables, Customer Overview)

4. GSAPI Capabilities at a Glance

GSAPI is not one API — it is a collection of specialized actions.
These actions cover different operational areas.

4.1 Data Importing

Used to send data into Good Sign.

  • Interface Import (generic imports to any data model)
  • Contract Events Import (usage/transaction events)
  • File/Excel-based imports through interfaces (optional alternative)

4.2 Pricing Management

  • Update a single price
  • Bulk update via Excel
  • Change price by amount or percentage
  • Set validity ranges (pricevalidfrom / pricevalidto)

4.3 Invoicing

  • List invoice batches
  • Inspect batch status
  • Send or rollback invoice batches
  • Retrieve delivery details
  • Work queue behavior for large batches

4.4 Object & Charge Logic

  • Object Charge Sharing (UI + API + file import)
  • Adjusting charge allocations across organizations

4.5 Monitoring & Automation

  • QueryMonitor (SQL-based automated alerts)
  • Webhook Adapter (event notifications to external systems)
  • Real-time event flow to CRMs, ERPs, integration hubs

5. Authentication & User Rights

GSAPI uses the same authentication model as the Good Sign UI.

5.1 API Rights

Most GSAPI calls require:

  • 6000 – GSAPI access
  • 6001 – GSAPI write access (for POST/PUT/DELETE)

Depending on the function, additional rights are needed (e.g., 3150 for contract events, 3680/3681/3682 for invoice batches).

5.2 Environment & URL Structure

Standard cloud endpoint:

https://api.goodsign.cloud/api/interface/gsapi/<action>

Each GSAPI action uses its own sub-path.

6. Processing Behavior

6.1 Staging First, Processing Second

Almost all GSAPI actions follow a two-phase model:

  1. Stage the incoming data
  2. Process it (immediately or in scheduled batches)

6.2 The notify Parameter

Many endpoints accept:

?notify=1

Which triggers immediate processing.
Default (notify=0) queues the work for later.

Recommended practice

For high-volume imports:

  • use notify=0 for continuous batches
  • use notify=1 only for the final batch

7. Debugging Data Imported via GSAPI

7.1 Datatables — Your First Validation Tool

Datatables show the raw rows exactly as Good Sign received them.

You can check:

  • Did the JSON map correctly?
  • Did all rows arrive?
  • Are mandatory fields populated?
  • Are mapping values correct?

This is the fastest way for customers to confirm that their integration is delivering correct data.

7.2 Usage Aggregate Table (for Contract Events)

Unmapped rows appear here when:

  • mapping values don’t match contract lines
  • contract lines are inactive
  • required key fields are missing

This is important for detecting billing leakage.

8. Recommended Setup for New Integrations

  1. Start with Interface Import or Contract Events Import
  2. Validate data in Datatables
  3. Confirm business rules via Invoice Preparation
  4. Automate processing using notify appropriately
  5. Add monitoring using QueryMonitor or Invoice Monitoring
  6. Add Webhooks if external systems need updates
  7. Use the Pricing Change API for recurring updates

10. Related GSAPI Articles (Deep Dives)

These appear as separate articles:

Each article focuses on one topic for clarity.

11. Consultant Notes (Advanced)

A. Staging Table Initialization

Some interfaces require column initialization (init=1).
This applies especially to:

  • Interface Import
  • Late-added columns in custom interfaces

B. Performance Guidelines

  • Split extremely large JSON payloads (>50k rows)
  • Avoid notify=1 unless necessary
  • Monitor long-running processes via work queues

C. Error Handling (ret < 0)

Most GSAPI errors follow standard patterns:

  • permission issues
  • malformed JSON
  • staging table missing
  • interface misconfiguration
  • column mismatch

D. Version Differences

  • 2023_1 introduced unified endpoints
  • 2025_2 added staging auto-initialization
  • 2026_1 enhanced invoice batches + datatable visibility

12. Summary

GSAPI is the automation backbone of Good Sign.
It allows systems to deliver data, update pricing, manage invoices, and trigger external workflows — while customers maintain full visibility through Datatables and monitoring tools.

This overview is the entry point for all detailed GSAPI topics.