API reference

Integration type

GipoNext APIs are exclusively REST (HTTP + JSON). Each operation follows the synchronous request/response model: your client sends a request, the server processes it and returns a response.

No other integration models are supported. In particular:

• No webhooks — GipoNext does not send push notifications to your server when data changes.
• No WebSockets — no bidirectional real-time communication channel is available.
• No message queues — no integration via broker (RabbitMQ, Azure Service Bus, etc.) is available for external systems.

If you need to know when data changes, the only approach is polling: query the relevant endpoint periodically at reasonable intervals (see Rate limiting for applicable limits).

OpenAPI 2.0 specification

The APIs are described by an OpenAPI 2.0 specification (the format formerly known as Swagger). It is a machine-readable JSON document that describes all endpoints, parameters, request/response models, and authentication schemes.

Specification URL:

https://api.giponext.it/swagger/docs/v2

You can use this URL to:

• Import the collection into development tools such as Postman, Bruno, Insomnia, or Hoppscotch and have all endpoints ready to call.
• Generate client SDKs for your language with tools like OpenAPI Generator, NSwag, AutoRest, or Kiota.
• Browse interactive documentation on Swagger UI, where you can explore endpoints, read models, and try calls with OAuth authentication.
• Explore the APIs with the integrated Scalar client on this site.

Generating a client: why and how

Generating a client SDK from the OpenAPI spec is the recommended best practice for integrating GipoNext APIs. A generated client:

• Saves work — you do not write request, response, serialization, and endpoint handling classes by hand.
• Reduces errors — types, field names, and method signatures are derived from the spec, not manual copy-paste.
• Updates easily — when the spec changes, regenerate the client and the compiler will flag incompatibilities.
• Ensures consistency — the client reflects what the server exposes, including optional fields, enums, and formats.

💡 Tip

Include client generation in your build pipeline. Each spec update will produce an updated client, and the compiler will flag incompatibilities.

OAuth client configuration

To call the APIs, your client (generated or manual) must authenticate via OAuth 2.0. The parameters to configure are the same regardless of the tool you use.

Common parameters

Parameter	Value	Where to find it
Grant Type	authorization_code	Fixed
Auth URL	https://account.gipo.it/connect/authorize	Fixed
Token URL	https://account.gipo.it/connect/token	Fixed
Client ID	Your client_id	OAuth client detail page on account.gipo.it
Client Secret	Your client_secret	"Secrets" section of the OAuth client
Scopes	Space-separated scopes (e.g. openid offline_access giponext.patients)	Based on endpoints you need — see Authentication and authorization
Redirect URI	Depends on your client (see below)	Must match one of the redirect URIs registered on account.gipo.it
State	Random value	Generated by the client for CSRF protection — verify it in the callback

⚠️ Redirect URI

The redirect URI configured in your tool must be identical to the one registered in the OAuth client configuration on account.gipo.it. Even a small difference (trailing slash, http vs https) causes an authorization error.

Client configuration

Each development tool has its own interface for OAuth configuration. Below are the settings for the most common clients.

Scalar (integrated)

# Specs / Scalar tab on this site
# OAuth endpoints and scopes are preconfigured.
# You only need to enter Client ID and Client Secret.

Client ID:      <your client_id>
Client Secret:  <your client_secret>
Scope:          <scopes required for that session>

# to register on account.gipo.it:
Redirect URI:
  - https://api.giponext.it/specs/scalar.html
  - https://api.giponext.it/en/specs/scalar.html

Postman

# Authorization tab in the collection or request
Type:             OAuth 2.0
Grant Type:       Authorization Code
Callback URL:     https://oauth.pstmn.io/v1/callback
Auth URL:         https://account.gipo.it/connect/authorize
Access Token URL: https://account.gipo.it/connect/token
Client ID:        <your client_id>
Client Secret:    <your client_secret>
Scope:            <scopes required for that session>
State:            <generated automatically>

# to register on account.gipo.it:
Redirect URI:
  - https://oauth.pstmn.io/v1/callback

Bruno

# Auth tab in the collection
Auth Type:          OAuth 2.0
Grant Type:         Authorization Code
Callback URL:       https://oauth.usebruno.com/callback
Authorization URL:  https://account.gipo.it/connect/authorize
Access Token URL:   https://account.gipo.it/connect/token
Client ID:          <your client_id>
Client Secret:      <your client_secret>
Scope:              <scopes required for that session>
State:              <generated automatically>

# to register on account.gipo.it:
Redirect URI:
  - https://oauth.usebruno.com/callback
  # Bruno also supports local callback:
  - http://localhost:3000/oauth/callback

Insomnia

# Auth tab in the request or environment
Auth Type:          OAuth 2.0
Grant Type:         Authorization Code
Redirect URL:       http://localhost:7171/oauth/callback
Authorization URL:  https://account.gipo.it/connect/authorize
Access Token URL:   https://account.gipo.it/connect/token
Client ID:          <your client_id>
Client Secret:      <your client_secret>
Scope:              <scopes required for that session>

# to register on account.gipo.it:
Redirect URI:
  - http://localhost:7171/oauth/callback

Rules valid for all clients

1. Set Grant Type = Authorization Code.
2. If the client supports PKCE, enable it.
3. After authorization, use the token with the header Authorization: Bearer <access_token>.
4. When the token expires (response 401), renew it with the refresh token — see OAuth flows and tokens.

API calls after login

After obtaining a valid access token, all calls follow the same pattern.

Base URL:

https://api.giponext.it/v2

First call — obtain tenantId:

GET https://api.giponext.it/v2/userinfo
Authorization: Bearer <access_token>

The response contains the list of tenants the user can access. Use the tenantId in all subsequent calls.

Example — list patients:

GET https://api.giponext.it/v2/tenants/{tenantId}/patients
Authorization: Bearer <access_token>

For the full resource and endpoint map, see Entities and operations.

Advanced settings

You can use Postman scripts to automate repetitive operations. This example saves tenantId from the UserInfo response and injects it automatically into all routes that require it.

UserInfo / Scripts / Post-Response

const tenantId = pm.response.json().tenants.at(0);
pm.collectionVariables.set('tenantId', tenantId);

Collection / Scripts / Pre-Request

const url = pm.request.url.toJSON();
const index = url.variable.findIndex(item => item.key === 'tenantId');

if (index < 0) return;

url.variable[index].value = pm.collectionVariables.get('tenantId');
pm.request.url = url

Next steps

• Swagger UI — interactive documentation with all endpoints
• Scalar — integrated API client on this site
• Entities and operations — resource map, operations, and scopes
• OAuth flows and tokens — technical details on the authentication flow
• API features — cross-cutting operational rules (errors, pagination, rate limiting, TLS)