MENU navbar-image

Introduction

This documentation aims to provide all the information you need to work with our API.

<aside>As you scroll, you'll see code examples for working with the API in different programming languages in the dark area to the right (or as part of the content on mobile).
You can switch the language used with the tabs at the top right (or from the nav menu at the top left on mobile).</aside>

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {YOUR_AUTH_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

You can retrieve your token by visiting your dashboard and clicking Generate API token.

Accounting Groups

List Accounting Groups

requires authentication

Returns a paginated list of accounting groups. By default only active groups are returned; use active=false for inactive. Each group includes its account-number mappings (one per accounting type).

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/accounting-groups?per_page=15&page=1&ids=1%2C5%2C8&cts=27%2C28&active=1&search=Internet" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/accounting-groups"
);

const params = {
    "per_page": "15",
    "page": "1",
    "ids": "1,5,8",
    "cts": "27,28",
    "active": "1",
    "search": "Internet",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "ID": 2217,
            "AG_NAME": "aut adipisci",
            "AG_NOTE": "Qui commodi incidunt iure odit.",
            "AG_VAS": 0,
            "AG_CT": 35,
            "AG_CREATED": null,
            "AG_L_ID_CREATED": null,
            "AG_CHANGED": null,
            "AG_L_ID_CHANGED": null,
            "AG_ACTIVE": 1,
            "AG_ID_CT": null,
            "account_mappings": [
                {
                    "AGN_ID": 37164,
                    "AGN_AG_ID": 2217,
                    "AGN_TYPE": "LIABILITIES_OTHERS",
                    "AGN_ACCOUNT": "326",
                    "AGN_ACCOUNT_V": null,
                    "AGN_TITLE": "",
                    "AGN_CREATED": null,
                    "AGN_L_ID_CREATED": null,
                    "AGN_CHANGED": null,
                    "AGN_L_ID_CHANGED": null
                }
            ]
        },
        {
            "ID": 2218,
            "AG_NAME": "ipsum nostrum",
            "AG_NOTE": null,
            "AG_VAS": 0,
            "AG_CT": 7,
            "AG_CREATED": null,
            "AG_L_ID_CREATED": null,
            "AG_CHANGED": null,
            "AG_L_ID_CHANGED": null,
            "AG_ACTIVE": 1,
            "AG_ID_CT": null,
            "account_mappings": [
                {
                    "AGN_ID": 37165,
                    "AGN_AG_ID": 2218,
                    "AGN_TYPE": "OTHER",
                    "AGN_ACCOUNT": "525",
                    "AGN_ACCOUNT_V": null,
                    "AGN_TITLE": "",
                    "AGN_CREATED": null,
                    "AGN_L_ID_CREATED": null,
                    "AGN_CHANGED": null,
                    "AGN_L_ID_CHANGED": null
                }
            ]
        }
    ]
}

Request      

GET api/v3/accounting-groups

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of results per page. Example: 15

page   integer  optional    

Page number. Example: 1

ids   string  optional    

Filter by comma-separated accounting group IDs. Example: 1,5,8

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Example: 27,28

active   boolean  optional    

Filter by active status. When omitted, only active groups are returned (default). Set to false for inactive only. Example: true

search   string  optional    

Search in accounting group name (partial match). Example: Internet

Response

Response Fields

data   object     
ID   integer     

Unique accounting group identifier (primary key, zerofill int(4)).

AG_NAME   string     

Accounting group name (max 40 chars).

AG_NOTE   string     

Optional description / note.

AG_VAS   integer     

VAS (value-added / resale services) flag. 1 = external resale services, 0 = standard.

AG_ACTIVE   integer     

Active status. 1 = active, 0 = inactive (soft-deleted or deactivated).

AG_CT   integer     

Location (installation / CT) ID. 0 = global (visible to all locations).

AG_ID_CT   integer     

Reference to CT record (currently unused).

AG_CREATED   string     

Creation timestamp (datetime).

AG_L_ID_CREATED   integer     

Operator (login) ID who created this record.

AG_CHANGED   string     

Last modification timestamp (datetime).

AG_L_ID_CHANGED   integer     

Operator (login) ID who last modified this record.

account_mappings   object[]     

Account-number mappings — one entry per accounting type (SERVICE, REVENUES, DPH, ADVANCE, etc.).
AGN_ID   integer     

Unique mapping record ID (primary key).

AGN_AG_ID   integer     

Parent accounting group ID (FK → acc_groups.ID).

AGN_TYPE   string     

Accounting type code.

Must be one of:
  • SERVICE
  • REVENUES
  • DPH
  • ADVANCE
  • ADVANCE_ZZ
  • ADVANCE_NZZ
  • COMMISSION
  • CREDIT_NOTE
  • DEFERRED_INCOME
  • LIABILITIES_OTHERS
  • NON_ATTACH
  • OTHER
  • ROUND
  • NEXT_PERIOD
AGN_ACCOUNT   string     

Ledger account number (max 10 chars).

AGN_ACCOUNT_V   string     

Variable (counter) account number.

AGN_TITLE   string     

Optional label / description for this mapping.

AGN_CREATED   string     

Creation timestamp.

AGN_L_ID_CREATED   integer     

Creator operator ID.

AGN_CHANGED   string     

Last modification timestamp.

AGN_L_ID_CHANGED   integer     

Last modifier operator ID.

Get Accounting Group

requires authentication

Returns a single accounting group by ID, including its account-number mappings.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/accounting-groups/0" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/accounting-groups/0"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "ID": 2219,
        "AG_NAME": "aut adipisci",
        "AG_NOTE": "Qui commodi incidunt iure odit.",
        "AG_VAS": 0,
        "AG_CT": 35,
        "AG_CREATED": null,
        "AG_L_ID_CREATED": null,
        "AG_CHANGED": null,
        "AG_L_ID_CHANGED": null,
        "AG_ACTIVE": 1,
        "AG_ID_CT": null,
        "account_mappings": [
            {
                "AGN_ID": 37166,
                "AGN_AG_ID": 2219,
                "AGN_TYPE": "LIABILITIES_OTHERS",
                "AGN_ACCOUNT": "326",
                "AGN_ACCOUNT_V": null,
                "AGN_TITLE": "",
                "AGN_CREATED": null,
                "AGN_L_ID_CREATED": null,
                "AGN_CHANGED": null,
                "AGN_L_ID_CHANGED": null
            }
        ]
    }
}

Request      

GET api/v3/accounting-groups/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the accounting group. Example: 0

Response

Response Fields

data   object     
ID   integer     

Unique accounting group identifier (primary key, zerofill int(4)).

AG_NAME   string     

Accounting group name (max 40 chars).

AG_NOTE   string     

Optional description / note.

AG_VAS   integer     

VAS (value-added / resale services) flag. 1 = external resale services, 0 = standard.

AG_ACTIVE   integer     

Active status. 1 = active, 0 = inactive (soft-deleted or deactivated).

AG_CT   integer     

Location (installation / CT) ID. 0 = global (visible to all locations).

AG_ID_CT   integer     

Reference to CT record (currently unused).

AG_CREATED   string     

Creation timestamp (datetime).

AG_L_ID_CREATED   integer     

Operator (login) ID who created this record.

AG_CHANGED   string     

Last modification timestamp (datetime).

AG_L_ID_CHANGED   integer     

Operator (login) ID who last modified this record.

account_mappings   object[]     

Account-number mappings — one entry per accounting type (SERVICE, REVENUES, DPH, ADVANCE, etc.).
AGN_ID   integer     

Unique mapping record ID (primary key).

AGN_AG_ID   integer     

Parent accounting group ID (FK → acc_groups.ID).

AGN_TYPE   string     

Accounting type code.

Must be one of:
  • SERVICE
  • REVENUES
  • DPH
  • ADVANCE
  • ADVANCE_ZZ
  • ADVANCE_NZZ
  • COMMISSION
  • CREDIT_NOTE
  • DEFERRED_INCOME
  • LIABILITIES_OTHERS
  • NON_ATTACH
  • OTHER
  • ROUND
  • NEXT_PERIOD
AGN_ACCOUNT   string     

Ledger account number (max 10 chars).

AGN_ACCOUNT_V   string     

Variable (counter) account number.

AGN_TITLE   string     

Optional label / description for this mapping.

AGN_CREATED   string     

Creation timestamp.

AGN_L_ID_CREATED   integer     

Creator operator ID.

AGN_CHANGED   string     

Last modification timestamp.

AGN_L_ID_CHANGED   integer     

Last modifier operator ID.

Agreement Types

List Agreement Types

requires authentication 

Returns a paginated list of agreement type definitions.
Includes global types (AT_CT = NULL) available to all locations.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/agreement-types?per_page=10&page=1&ids=50%2C51&cts=1%2C2%2C3" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/agreement-types"
);

const params = {
    "per_page": "10",
    "page": "1",
    "ids": "50,51",
    "cts": "1,2,3",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "AT_ID": 460,
            "AT_CP": null,
            "AT_CT": 21,
            "AT_TYPE": "aut_2839",
            "AT_NUMBERING": "auto",
            "AT_NUMBER_FORMAT": "{A_NUMBER}",
            "AT_TEMPLATE": "quidem",
            "AT_NOTE": "Qui commodi incidunt iure odit.",
            "AT_FLAGS": "",
            "AT_PRINT": "ALL",
            "AT_VALID_FROM": null,
            "AT_VALID_TO": null,
            "AT_CONFIRM": null,
            "AT_REMIND_DAYS": null,
            "AT_BLOCK_DAYS": null
        },
        {
            "AT_ID": 461,
            "AT_CP": null,
            "AT_CT": 2,
            "AT_TYPE": "et_1839",
            "AT_NUMBERING": "auto",
            "AT_NUMBER_FORMAT": "{A_NUMBER}",
            "AT_TEMPLATE": "modi",
            "AT_NOTE": "Nostrum omnis autem et consequatur aut.",
            "AT_FLAGS": "",
            "AT_PRINT": "ALL",
            "AT_VALID_FROM": null,
            "AT_VALID_TO": null,
            "AT_CONFIRM": null,
            "AT_REMIND_DAYS": null,
            "AT_BLOCK_DAYS": null
        }
    ]
}

Request      

GET api/v3/agreement-types

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of agreement types to return per page. Example: 10

page   integer  optional    

Page number to return. Example: 1

ids   string  optional    

Filter by comma-separated agreement type IDs. Example: 50,51

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Example: 1,2,3

Response

Response Fields

data   object     
AT_ID   integer     

Unique agreement type ID (primary key).

AT_CT   integer     

Location (installation) ID. NULL = global type available to all locations.

AT_CP   integer     

Company/partner ID (cibs_partners).

AT_TYPE   string     

Agreement type name / identifier.

AT_TEMPLATE   string     

Document template name used for PDF generation.

AT_NOTE   string     

Description / note for this agreement type.

AT_NUMBERING   string     

Agreement number generation strategy.

Must be one of:
  • auto
  • auto.type
  • auto.user
  • auto.type=user
  • none
AT_NUMBER_FORMAT   string     

Format template for agreement numbers (e.g. {A_NUMBER}).

AT_FLAGS   string     

Comma-separated behavior flags.

Must be one of:
  • AUTO_ON_ACTIVATE
  • USER_DISTINCT
  • SERVICE_DISTINCT
  • AUTO_ON_CONNECT
  • AUTO_ON_CONNECT_SET
AT_PRINT   string     

Print mode for document expedition.

Must be one of:
  • SCAN
  • ALL
AT_VALID_FROM   string     

Date from which this agreement type is available (YYYY-MM-DD).

AT_VALID_TO   string     

Date until which this agreement type is available (YYYY-MM-DD).

AT_CONFIRM   integer     

Whether agreements of this type require customer confirmation. 1 = yes.

AT_REMIND_DAYS   integer     

Days after conclusion to send a confirmation reminder.

AT_BLOCK_DAYS   integer     

Days after conclusion to block services if not confirmed.

Agreements

List Agreements

requires authentication 

Returns a paginated list of agreements.
By default, only valid agreements (A_VALID = 1) are returned.
Use `valid=0` to see only invalid, or `valid=all` to see both.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/agreements?per_page=10&page=1&ids=41%2C42%2C45&cts=1%2C2%2C3&customer=30367%2C28934&type=50%2C51&valid=true&customer_service=266773&date_from=2020-01-01&date_to=2024-12-31" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/agreements"
);

const params = {
    "per_page": "10",
    "page": "1",
    "ids": "41,42,45",
    "cts": "1,2,3",
    "customer": "30367,28934",
    "type": "50,51",
    "valid": "true",
    "customer_service": "266773",
    "date_from": "2020-01-01",
    "date_to": "2024-12-31",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "A_ID": 348918,
            "A_AT_ID": 457,
            "A_USER_ID": 383,
            "A_CT": 57,
            "A_NUMBER": "857680",
            "A_NOTE": "Quidem nostrum qui commodi incidunt iure odit.",
            "A_CONCLUSION_DATE": "1977-08-15",
            "A_CREATED": "2026-01-04 19:19:02",
            "A_L_ID": 2685,
            "A_ML_ID": null,
            "A_NUM": null,
            "A_VALID": 1,
            "A_INVALID_NOTE": null,
            "A_CONFIRMED": null,
            "A_CONFIRM_L_ID": null,
            "A_REMINDER_DATE": null,
            "A_REMEMBER_L_ID": null,
            "A_BLOCK_DATE": null,
            "A_BLOCKED_L_ID": null,
            "A_UNBLOCK_DATE": null,
            "A_UNBLOCKED_L_ID": null,
            "customer_service_links": [
                {
                    "AS_ID": 577398,
                    "AS_A_ID": 348918,
                    "AS_SA_ID": 3981545
                }
            ],
            "type": {
                "AT_ID": 457,
                "AT_CP": null,
                "AT_CT": 214,
                "AT_TYPE": "modi_967",
                "AT_NUMBERING": "auto",
                "AT_NUMBER_FORMAT": "{A_NUMBER}",
                "AT_TEMPLATE": "nostrum",
                "AT_NOTE": "Autem et consequatur aut dolores enim non facere tempora.",
                "AT_FLAGS": "",
                "AT_PRINT": "ALL",
                "AT_VALID_FROM": null,
                "AT_VALID_TO": null,
                "AT_CONFIRM": null,
                "AT_REMIND_DAYS": null,
                "AT_BLOCK_DAYS": null
            }
        },
        {
            "A_ID": 348919,
            "A_AT_ID": 458,
            "A_USER_ID": 14086,
            "A_CT": 102,
            "A_NUMBER": "187043",
            "A_NOTE": "Laboriosam praesentium quis adipisci molestias fugit deleniti distinctio.",
            "A_CONCLUSION_DATE": "2013-02-14",
            "A_CREATED": "2026-02-05 10:17:14",
            "A_L_ID": 1818,
            "A_ML_ID": null,
            "A_NUM": null,
            "A_VALID": 1,
            "A_INVALID_NOTE": null,
            "A_CONFIRMED": null,
            "A_CONFIRM_L_ID": null,
            "A_REMINDER_DATE": null,
            "A_REMEMBER_L_ID": null,
            "A_BLOCK_DATE": null,
            "A_BLOCKED_L_ID": null,
            "A_UNBLOCK_DATE": null,
            "A_UNBLOCKED_L_ID": null,
            "customer_service_links": [
                {
                    "AS_ID": 577399,
                    "AS_A_ID": 348919,
                    "AS_SA_ID": 3950069
                }
            ],
            "type": {
                "AT_ID": 458,
                "AT_CP": null,
                "AT_CT": 154,
                "AT_TYPE": "id_4781",
                "AT_NUMBERING": "auto",
                "AT_NUMBER_FORMAT": "{A_NUMBER}",
                "AT_TEMPLATE": "libero",
                "AT_NOTE": "Veniam corporis dolorem mollitia.",
                "AT_FLAGS": "",
                "AT_PRINT": "ALL",
                "AT_VALID_FROM": null,
                "AT_VALID_TO": null,
                "AT_CONFIRM": null,
                "AT_REMIND_DAYS": null,
                "AT_BLOCK_DAYS": null
            }
        }
    ]
}

Request      

GET api/v3/agreements

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of agreements to return per page. Example: 10

page   integer  optional    

Page number to return. Example: 1

ids   string  optional    

Filter by comma-separated agreement IDs. Example: 41,42,45

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Example: 1,2,3

customer   string  optional    

Filter by comma-separated customer (user) IDs. Example: 30367,28934

type   string  optional    

Filter by comma-separated agreement type IDs. Example: 50,51

valid   string  optional    

Filter by validity. true = valid only (default), false = invalid only, all = both. Example: true

customer_service   integer  optional    

Filter agreements linked to a specific customer service (services_active) ID. Example: 266773

date_from   string  optional    

Filter agreements with conclusion date on or after this date (YYYY-MM-DD). Example: 2020-01-01

date_to   string  optional    

Filter agreements with conclusion date on or before this date (YYYY-MM-DD). Example: 2024-12-31

Response

Response Fields

data   object     
A_ID   integer     

Unique agreement identifier (primary key).

A_NUMBER   string     

Agreement number (may be auto-generated based on agreement type numbering rules).

A_CT   integer     

Location (installation) ID — multi-tenant discriminator.

A_AT_ID   integer     

Agreement type ID. See GET /v3/agreement-types.

A_USER_ID   integer     

Customer (user) ID. See GET /v3/customers.

A_L_ID   integer     

Operator login ID who created the agreement.

A_ML_ID   integer     

Related process (maintenance_list) ID, if the agreement was created from a process.

A_CONCLUSION_DATE   string     

Date the agreement was concluded (YYYY-MM-DD).

A_CREATED   string     

Datetime when the agreement was created (YYYY-MM-DD HH:MM:SS).

A_NOTE   string     

Agreement note / description.

A_NUM   integer     

Internal numbering counter (used by auto-numbering).

A_VALID   integer     

Validity flag. 1 = valid, 0 = invalidated.

A_INVALID_NOTE   string     

Reason for invalidation (set when A_VALID = 0).

A_CONFIRMED   string     

Datetime when the agreement was confirmed by the customer.

A_CONFIRM_L_ID   integer     

Operator login ID who recorded the confirmation.

A_REMINDER_DATE   string     

Datetime when a confirmation reminder was sent.

A_REMEMBER_L_ID   integer     

Operator login ID who triggered the reminder (or system if automatic).

A_BLOCK_DATE   string     

Datetime when services were blocked due to missing confirmation.

A_BLOCKED_L_ID   integer     

Operator login ID who triggered the blocking (or system if automatic).

A_UNBLOCK_DATE   string     

Datetime when services were unblocked after confirmation.

A_UNBLOCKED_L_ID   integer     

Operator login ID who triggered the unblocking.

customer_service_links   object[]     

Customer services covered by this agreement (junction records).
AS_ID   integer     

Unique junction record ID.

AS_A_ID   integer     

Agreement ID.

AS_SA_ID   integer     

Customer service (services_active) ID. See GET /v3/customer-services.

type   object     

Agreement type definition.
AT_ID   integer     

Unique agreement type ID.

AT_TYPE   string     

Agreement type name / identifier.

AT_TEMPLATE   string     

Document template name used for PDF generation.

Get Agreement

requires authentication 

Returns a single agreement by ID, including its customer service links and type.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/agreements/41" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/agreements/41"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "A_ID": 348920,
        "A_AT_ID": 459,
        "A_USER_ID": 467385,
        "A_CT": 33,
        "A_NUMBER": "333724",
        "A_NOTE": "Nostrum qui commodi incidunt iure.",
        "A_CONCLUSION_DATE": "1990-02-03",
        "A_CREATED": "2026-03-05 06:45:06",
        "A_L_ID": 2066,
        "A_ML_ID": null,
        "A_NUM": null,
        "A_VALID": 1,
        "A_INVALID_NOTE": null,
        "A_CONFIRMED": null,
        "A_CONFIRM_L_ID": null,
        "A_REMINDER_DATE": null,
        "A_REMEMBER_L_ID": null,
        "A_BLOCK_DATE": null,
        "A_BLOCKED_L_ID": null,
        "A_UNBLOCK_DATE": null,
        "A_UNBLOCKED_L_ID": null,
        "customer_service_links": [
            {
                "AS_ID": 577400,
                "AS_A_ID": 348920,
                "AS_SA_ID": 2961403
            }
        ],
        "type": {
            "AT_ID": 459,
            "AT_CP": null,
            "AT_CT": 5,
            "AT_TYPE": "et_1769",
            "AT_NUMBERING": "auto",
            "AT_NUMBER_FORMAT": "{A_NUMBER}",
            "AT_TEMPLATE": "ipsum",
            "AT_NOTE": "Omnis autem et consequatur.",
            "AT_FLAGS": "",
            "AT_PRINT": "ALL",
            "AT_VALID_FROM": null,
            "AT_VALID_TO": null,
            "AT_CONFIRM": null,
            "AT_REMIND_DAYS": null,
            "AT_BLOCK_DAYS": null
        }
    }
}

Request      

GET api/v3/agreements/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the agreement. Example: 41

Response

Response Fields

data   object     
A_ID   integer     

Unique agreement identifier (primary key).

A_NUMBER   string     

Agreement number (may be auto-generated based on agreement type numbering rules).

A_CT   integer     

Location (installation) ID — multi-tenant discriminator.

A_AT_ID   integer     

Agreement type ID. See GET /v3/agreement-types.

A_USER_ID   integer     

Customer (user) ID. See GET /v3/customers.

A_L_ID   integer     

Operator login ID who created the agreement.

A_ML_ID   integer     

Related process (maintenance_list) ID, if the agreement was created from a process.

A_CONCLUSION_DATE   string     

Date the agreement was concluded (YYYY-MM-DD).

A_CREATED   string     

Datetime when the agreement was created (YYYY-MM-DD HH:MM:SS).

A_NOTE   string     

Agreement note / description.

A_NUM   integer     

Internal numbering counter (used by auto-numbering).

A_VALID   integer     

Validity flag. 1 = valid, 0 = invalidated.

A_INVALID_NOTE   string     

Reason for invalidation (set when A_VALID = 0).

A_CONFIRMED   string     

Datetime when the agreement was confirmed by the customer.

A_CONFIRM_L_ID   integer     

Operator login ID who recorded the confirmation.

A_REMINDER_DATE   string     

Datetime when a confirmation reminder was sent.

A_REMEMBER_L_ID   integer     

Operator login ID who triggered the reminder (or system if automatic).

A_BLOCK_DATE   string     

Datetime when services were blocked due to missing confirmation.

A_BLOCKED_L_ID   integer     

Operator login ID who triggered the blocking (or system if automatic).

A_UNBLOCK_DATE   string     

Datetime when services were unblocked after confirmation.

A_UNBLOCKED_L_ID   integer     

Operator login ID who triggered the unblocking.

customer_service_links   object[]     

Customer services covered by this agreement (junction records).
AS_ID   integer     

Unique junction record ID.

AS_A_ID   integer     

Agreement ID.

AS_SA_ID   integer     

Customer service (services_active) ID. See GET /v3/customer-services.

type   object     

Agreement type definition.
AT_ID   integer     

Unique agreement type ID.

AT_TYPE   string     

Agreement type name / identifier.

AT_TEMPLATE   string     

Document template name used for PDF generation.

Download Agreement PDF

requires authentication 

Downloads the agreement document as a PDF file.
Note: PDF rendering is not yet implemented (returns 503).
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/agreements/41/download" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/agreements/41/download"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "message": "Unauthenticated."
}

Request      

GET api/v3/agreements/{agreement}/download

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

agreement   integer     

The agreement. Example: 41

Authentication

User Login

Authenticates a user with login credentials and returns a bearer token. The token should be included in the Authorization header for subsequent API requests.

Example request:
curl --request POST \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/login" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"login\": \"architecto\",
    \"password\": \"|]|{+-\"
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/login"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "login": "architecto",
    "password": "|]|{+-"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200, Successful authentication):


{
    "data": {
        "ID": 5550,
        "LOGIN": "idickens",
        "IS_SUPER_ADMIN": true
    }
}

Request      

POST api/v3/login

Headers

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Body Parameters

login   The login name     

string Example: architecto

password   The password     

string Example: |]|{+-

SSO Login

Authenticates a user from Mango session passed in MANGO_SESSION header. On success issues Sanctum token cookie and redirects to configured frontend URL.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/sso/login" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"mango_session\": \"architecto\",
    \"return_url\": \"http:\\/\\/www.bailey.biz\\/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html\"
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/sso/login"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "mango_session": "architecto",
    "return_url": "http:\/\/www.bailey.biz\/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "message": ""
}

Request      

GET api/v3/sso/login

Headers

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Body Parameters

mango_session   The Mango session     

string Example: architecto

return_url   The return URL  optional    

url Example: http://www.bailey.biz/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html

User Logout

requires authentication

Logs out the current user and clears the authentication cookie.

Example request:
curl --request POST \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/logout" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/logout"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());

Request      

POST api/v3/logout

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Current User

requires authentication

Returns the currently authenticated user.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/me" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/me"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200, Current authenticated user):


{
    "data": {
        "ID": 5551,
        "LOGIN": "dare.emelie",
        "IS_SUPER_ADMIN": true
    }
}

Request      

GET api/v3/me

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Billing Plans

List Billing Plans

requires authentication 

Returns a paginated list of billing plans (billing and payment configuration templates).
By default, disabled plans are excluded. Use `disabled=all` to include them.
CT scoping returns global plans (BP_CT IS NULL) plus plans specific to the user's locations.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/billing-plans?ids=1%2C2%2C3&cts=5%2C27&disabled=all" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/billing-plans"
);

const params = {
    "ids": "1,2,3",
    "cts": "5,27",
    "disabled": "all",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "BP_ID": 1075,
            "BP_NAME": "autem et consequatur",
            "BP_EU_NAME": null,
            "BP_NOTE": null,
            "BP_SC_ID": null,
            "BP_CT": null,
            "BP_CP_ID": null,
            "BP_DISABLED": 0,
            "BP_PAID": "NONE",
            "BP_PAID_SN_ID": null,
            "BP_PAID_TIME": "NONE",
            "BP_PAID_LEGEND": null,
            "BP_BLOCK": "NONE",
            "BP_DEFAULT": 1,
            "BP_TAXDOC_ROUNDING": "DEFAULT",
            "BP_SEPARATE": 0,
            "BP_VAR_PRICE_ACCORD": null,
            "BP_VAR_PRICE_SEPARATE": 0,
            "BP_TAX_DAY": 0,
            "BP_TAX_DATE_SHIFT": 0,
            "BP_TAXDOC_DELIVERY_TYPE": "NONE",
            "BP_COLLECTION_TYPE": "NONE",
            "BP_COLLECTION_DATE": null,
            "BP_COLLECTION_DAY": null,
            "BP_COLLECTION_DEBTS": "NONE",
            "BP_COLLECTION_DEBTS_AGE": 0,
            "BP_APPLICATION_TYPE": "NONE",
            "BP_APPLICATION_DELIVERY_TYPE": null,
            "BP_APPLICATION_DAY": null,
            "BP_PROFORMA_TYPE": "NONE",
            "BP_PROFORMA_DELIVERY_TYPE": null,
            "BP_PROFORMA_DATE": null,
            "BP_PROFORMA_DAY": null,
            "BP_ADVANCE": 0,
            "BP_ADVANCE_DELIVERY_TYPE": "NONE",
            "BP_CREDIT_NOTE_TYPE": "NONE",
            "BP_CREDIT_NOTE_DELIVERY_TYPE": null,
            "BP_CREDIT_NOTE_DAY": null,
            "BP_PAYMENT_TYPE": "ACCOUNT",
            "BP_PA_ID": null,
            "BP_PA_AUTO": null,
            "BP_MATURITY_TYPE": "ACTUAL",
            "BP_MATURITY_DAY": 0,
            "BP_RETURN_TYPE": "NONE",
            "BP_RETURN_PA_ID": null,
            "BP_VAR_TAX_DAY": 0,
            "BP_VAR_TAX_DATE_SHIFT": 0,
            "BP_VAR_TAXDOC_DELIVERY_TYPE": "NONE",
            "BP_VAR_COLLECTION_TYPE": "NONE",
            "BP_VAR_COLLECTION_DATE": null,
            "BP_VAR_COLLECTION_DAY": null,
            "BP_VAR_COLLECTION_DEBTS": "NONE",
            "BP_VAR_COLLECTION_DEBTS_AGE": 0,
            "BP_VAR_APPLICATION_TYPE": "NONE",
            "BP_VAR_APPLICATION_DELIVERY_TYPE": "NONE",
            "BP_VAR_APPLICATION_DAY": null,
            "BP_VAR_PROFORMA_TYPE": "NONE",
            "BP_VAR_PROFORMA_DELIVERY_TYPE": null,
            "BP_VAR_PROFORMA_DATE": null,
            "BP_VAR_PROFORMA_DAY": null,
            "BP_VAR_PAYMENT_TYPE": "ACCOUNT",
            "BP_VAR_PA_ID": null,
            "BP_VAR_MATURITY_TYPE": "ACTUAL",
            "BP_VAR_MATURITY_DAY": 0,
            "BP_VAR_RETURN_TYPE": "NONE",
            "BP_VAR_RETURN_PA_ID": null,
            "BP_VARIABILITY": "",
            "BP_AGR_NAME": null
        },
        {
            "BP_ID": 1076,
            "BP_NAME": "enim non facere",
            "BP_EU_NAME": "Voluptatem laboriosam praesentium.",
            "BP_NOTE": null,
            "BP_SC_ID": null,
            "BP_CT": null,
            "BP_CP_ID": null,
            "BP_DISABLED": 0,
            "BP_PAID": "POSTPAID",
            "BP_PAID_SN_ID": null,
            "BP_PAID_TIME": "NONE",
            "BP_PAID_LEGEND": null,
            "BP_BLOCK": "NONE",
            "BP_DEFAULT": 1,
            "BP_TAXDOC_ROUNDING": "DEFAULT",
            "BP_SEPARATE": 0,
            "BP_VAR_PRICE_ACCORD": null,
            "BP_VAR_PRICE_SEPARATE": 0,
            "BP_TAX_DAY": 0,
            "BP_TAX_DATE_SHIFT": 0,
            "BP_TAXDOC_DELIVERY_TYPE": "NONE",
            "BP_COLLECTION_TYPE": "NONE",
            "BP_COLLECTION_DATE": null,
            "BP_COLLECTION_DAY": null,
            "BP_COLLECTION_DEBTS": "NONE",
            "BP_COLLECTION_DEBTS_AGE": 0,
            "BP_APPLICATION_TYPE": "NONE",
            "BP_APPLICATION_DELIVERY_TYPE": null,
            "BP_APPLICATION_DAY": null,
            "BP_PROFORMA_TYPE": "NONE",
            "BP_PROFORMA_DELIVERY_TYPE": null,
            "BP_PROFORMA_DATE": null,
            "BP_PROFORMA_DAY": null,
            "BP_ADVANCE": 0,
            "BP_ADVANCE_DELIVERY_TYPE": "NONE",
            "BP_CREDIT_NOTE_TYPE": "NONE",
            "BP_CREDIT_NOTE_DELIVERY_TYPE": null,
            "BP_CREDIT_NOTE_DAY": null,
            "BP_PAYMENT_TYPE": "ACCOUNT",
            "BP_PA_ID": null,
            "BP_PA_AUTO": null,
            "BP_MATURITY_TYPE": "ACTUAL",
            "BP_MATURITY_DAY": 0,
            "BP_RETURN_TYPE": "NONE",
            "BP_RETURN_PA_ID": null,
            "BP_VAR_TAX_DAY": 0,
            "BP_VAR_TAX_DATE_SHIFT": 0,
            "BP_VAR_TAXDOC_DELIVERY_TYPE": "NONE",
            "BP_VAR_COLLECTION_TYPE": "NONE",
            "BP_VAR_COLLECTION_DATE": null,
            "BP_VAR_COLLECTION_DAY": null,
            "BP_VAR_COLLECTION_DEBTS": "NONE",
            "BP_VAR_COLLECTION_DEBTS_AGE": 0,
            "BP_VAR_APPLICATION_TYPE": "NONE",
            "BP_VAR_APPLICATION_DELIVERY_TYPE": "NONE",
            "BP_VAR_APPLICATION_DAY": null,
            "BP_VAR_PROFORMA_TYPE": "NONE",
            "BP_VAR_PROFORMA_DELIVERY_TYPE": null,
            "BP_VAR_PROFORMA_DATE": null,
            "BP_VAR_PROFORMA_DAY": null,
            "BP_VAR_PAYMENT_TYPE": "ACCOUNT",
            "BP_VAR_PA_ID": null,
            "BP_VAR_MATURITY_TYPE": "ACTUAL",
            "BP_VAR_MATURITY_DAY": 0,
            "BP_VAR_RETURN_TYPE": "NONE",
            "BP_VAR_RETURN_PA_ID": null,
            "BP_VARIABILITY": "",
            "BP_AGR_NAME": null
        }
    ]
}

Request      

GET api/v3/billing-plans

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

ids   string  optional    

Filter by comma-separated billing plan IDs. Example: 1,2,3

cts   string  optional    

Filter by comma-separated CT (installation) IDs. Returns global (BP_CT IS NULL) plans plus plans matching the specified CTs. Example: 5,27

disabled   string  optional    

Filter by disabled status. Default (omitted): exclude disabled plans. Pass "true" for disabled only, "all" to include both. Example: all

Response

Response Fields

data   object     
BP_ID   integer     

Billing plan ID.

BP_NAME   string     

Internal name of the billing plan.

BP_EU_NAME   string     

End-user (customer-facing) name.

BP_NOTE   string     

Internal notes or description.

BP_SC_ID   integer     

Service class ID.

BP_CT   integer     

Location (CT) ID. NULL means this is a global plan available to all locations.

BP_CP_ID   integer     

CIBS partner ID.

BP_DISABLED   integer     

Whether the plan is disabled. 0 = active, 1 = disabled.

BP_AGR_NAME   string     

Agreement name template.

BP_PAID   string     

Payment mode.

Must be one of:
  • NONE
  • PREPAID
  • ONTIMEPAID
  • POSTPAID
  • ACTUALPAID
  • BOX
BP_PAID_SN_ID   integer     

Service definition ID for payment service.

BP_PAID_TIME   string     

Payment time mode.

Must be one of:
  • WAITING
  • NONE
BP_PAID_LEGEND   string     

Payment legend text.

BP_BLOCK   string     

Blocking mode for non-payment.

Must be one of:
  • NONE
  • MATURITY
  • EXPIRATION_SHIFT
BP_DEFAULT   integer     

Default priority ranking (higher = more preferred).

BP_TAXDOC_ROUNDING   string     

Tax document rounding mode.

Must be one of:
  • DEFAULT
  • NOTROUNDED
BP_SEPARATE   integer     

Whether to generate separate tax documents. 0 = no, 1 = yes.

BP_TAX_DAY   integer     

Tax document day of month.

BP_TAX_DATE_SHIFT   integer     

Tax date shift in days.

BP_TAXDOC_DELIVERY_TYPE   string     

Tax document delivery method.

Must be one of:
  • NONE
  • EMAIL
  • MAIL
  • SMS
BP_COLLECTION_TYPE   string     

Collection type.

Must be one of:
  • NONE
  • SIPO
  • FETCH
BP_COLLECTION_DATE   string     

Collection date reference.

Must be one of:
  • PREV
  • ACTUAL
  • NEXT
  • 2NEXT
  • TAXDOC
BP_COLLECTION_DAY   integer     

Collection day of month.

BP_COLLECTION_DEBTS   string     

Whether to collect debts.

Must be one of:
  • NONE
  • ALL
BP_COLLECTION_DEBTS_AGE   integer     

Minimum debt age in days for collection.

BP_APPLICATION_TYPE   string     

Application (invoice) type.

Must be one of:
  • NONE
  • INVOICE
BP_APPLICATION_DELIVERY_TYPE   string     

Application delivery method.

Must be one of:
  • NONE
  • EMAIL
  • MAIL
  • SMS
BP_APPLICATION_DAY   integer     

Application day.

BP_PROFORMA_TYPE   string     

Proforma invoice type.

Must be one of:
  • NONE
  • PROFORMA
BP_PROFORMA_DELIVERY_TYPE   string     

Proforma delivery method.

Must be one of:
  • NONE
  • EMAIL
  • MAIL
  • SMS
BP_PROFORMA_DATE   string     

Proforma date reference.

Must be one of:
  • PREV
  • ACTUAL
  • NEXT
  • TAXDOC
  • MATURITY
  • USER
BP_PROFORMA_DAY   integer     

Proforma day.

BP_ADVANCE   integer     

Advance payment amount.

BP_ADVANCE_DELIVERY_TYPE   string     

Advance delivery method.

Must be one of:
  • NONE
  • EMAIL
  • MAIL
  • SMS
BP_CREDIT_NOTE_TYPE   string     

Credit note type.

Must be one of:
  • NONE
  • CREDIT_NOTE
BP_CREDIT_NOTE_DELIVERY_TYPE   string     

Credit note delivery method.

Must be one of:
  • NONE
  • EMAIL
  • MAIL
  • SMS
BP_CREDIT_NOTE_DAY   integer     

Credit note day.

BP_PAYMENT_TYPE   string     

Payment type.

Must be one of:
  • CASH
  • ACCOUNT
BP_PA_ID   integer     

Payment account ID.

BP_PA_AUTO   integer     

Automatic payment account assignment.

BP_MATURITY_TYPE   string     

Maturity date reference.

Must be one of:
  • PREV
  • ACTUAL
  • NEXT
  • TAXDOC
  • INVOICE
  • PREVFIX
BP_MATURITY_DAY   integer     

Maturity day.

BP_RETURN_TYPE   string     

Return payment type.

Must be one of:
  • NONE
  • SIPO
  • ORDER
BP_RETURN_PA_ID   integer     

Return payment account ID.

BP_VAR_PRICE_ACCORD   integer     

Variable pricing accord flag.

BP_VAR_PRICE_SEPARATE   integer     

Separate variable pricing flag.

BP_VAR_TAX_DAY   integer     

Variable section tax day.

BP_VAR_TAX_DATE_SHIFT   integer     

Variable section tax date shift.

BP_VAR_TAXDOC_DELIVERY_TYPE   string     

Variable section tax document delivery.

Must be one of:
  • NONE
  • EMAIL
  • MAIL
  • SMS
BP_VAR_COLLECTION_TYPE   string     

Variable section collection type.

Must be one of:
  • NONE
  • SIPO
  • FETCH
BP_VAR_COLLECTION_DATE   string     

Variable section collection date reference.

Must be one of:
  • PREV
  • ACTUAL
  • NEXT
  • 2NEXT
  • TAXDOC
BP_VAR_COLLECTION_DAY   integer     

Variable section collection day.

BP_VAR_COLLECTION_DEBTS   string     

Variable section debt collection.

Must be one of:
  • NONE
  • ALL
BP_VAR_COLLECTION_DEBTS_AGE   integer     

Variable section minimum debt age.

BP_VAR_APPLICATION_TYPE   string     

Variable section application type.

Must be one of:
  • NONE
  • INVOICE
BP_VAR_APPLICATION_DELIVERY_TYPE   string     

Variable section application delivery.

Must be one of:
  • NONE
  • EMAIL
  • MAIL
  • SMS
BP_VAR_APPLICATION_DAY   integer     

Variable section application day.

BP_VAR_PROFORMA_TYPE   string     

Variable section proforma type.

Must be one of:
  • NONE
  • PROFORMA
BP_VAR_PROFORMA_DELIVERY_TYPE   string     

Variable section proforma delivery.

Must be one of:
  • NONE
  • EMAIL
  • MAIL
  • SMS
BP_VAR_PROFORMA_DATE   string     

Variable section proforma date reference.

Must be one of:
  • PREV
  • ACTUAL
  • NEXT
  • TAXDOC
  • MATURITY
  • USER
BP_VAR_PROFORMA_DAY   integer     

Variable section proforma day.

BP_VAR_PAYMENT_TYPE   string     

Variable section payment type.

Must be one of:
  • CASH
  • ACCOUNT
BP_VAR_PA_ID   integer     

Variable section payment account ID.

BP_VAR_MATURITY_TYPE   string     

Variable section maturity reference.

Must be one of:
  • PREV
  • ACTUAL
  • NEXT
  • TAXDOC
  • INVOICE
  • PREVFIX
BP_VAR_MATURITY_DAY   integer     

Variable section maturity day.

BP_VAR_RETURN_TYPE   string     

Variable section return type.

Must be one of:
  • NONE
  • SIPO
  • ORDER
BP_VAR_RETURN_PA_ID   integer     

Variable section return payment account ID.

BP_VARIABILITY   string     

SET field indicating which sections can vary per service. Possible values: tax_date, maturity_date, rounding, separate.

Customer Contacts

List Customer Contacts

requires authentication 

Retrieve a paginated list of customer contacts (contact persons).
Contacts are scoped by CT through the parent customer.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-contacts?per_page=10&page=1&ids=1%2C2%2C3&cts=1%2C2%2C3&customer=100" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-contacts"
);

const params = {
    "per_page": "10",
    "page": "1",
    "ids": "1,2,3",
    "cts": "1,2,3",
    "customer": "100",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "UC_ID": 20906,
            "UC_USER_ID": 681,
            "UC_P_ID": null,
            "UC_LOGIN": null,
            "UC_LAST_NAME": "Price",
            "UC_FIRST_NAME": "Amber",
            "UC_EMAIL": "[email protected]",
            "UC_PHONE": 420760725744,
            "UC_PHONE2": null,
            "UC_GSM": 420659135052,
            "UC_FAX": null,
            "UC_FINANCE": 0,
            "UC_TECHNIC": 0,
            "UC_LEADER": 0,
            "UC_MANAGEMENT": 0,
            "UC_MARKETING": 0,
            "UC_SHOP": 0,
            "UC_POSITION": null
        },
        {
            "UC_ID": 20907,
            "UC_USER_ID": 59,
            "UC_P_ID": null,
            "UC_LOGIN": "schultz.audrey",
            "UC_LAST_NAME": "Koch",
            "UC_FIRST_NAME": "Christian",
            "UC_EMAIL": "[email protected]",
            "UC_PHONE": 420784087043,
            "UC_PHONE2": null,
            "UC_GSM": null,
            "UC_FAX": null,
            "UC_FINANCE": 0,
            "UC_TECHNIC": 0,
            "UC_LEADER": 0,
            "UC_MANAGEMENT": 0,
            "UC_MARKETING": 0,
            "UC_SHOP": 0,
            "UC_POSITION": null
        }
    ]
}

Request      

GET api/v3/customer-contacts

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of contacts to return per page (optional) Example: 10

page   integer  optional    

Page number to return (optional) Example: 1

ids   string  optional    

Filter by comma-separated contact IDs Example: 1,2,3

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Example: 1,2,3

customer   integer  optional    

Filter by customer ID (UC_USER_ID) Example: 100

Response

Response Fields

data   object     
UC_ID   integer     

Unique contact record ID (primary key).

UC_USER_ID   integer     

Customer ID this contact belongs to. See GET /v3/customers/{id}.

UC_P_ID   integer     

Premise ID (point of presence) associated with this contact.

UC_LAST_NAME   string     

Contact person's last name (surname).

UC_FIRST_NAME   string     

Contact person's first name.

UC_LOGIN   string     

Login name for the customer portal (SelfCare).

UC_POSITION   string     

Position code from the code list (installation-specific values, e.g. "DIR" = director, "UCT" = accountant, "SEC" = secretary).

UC_EMAIL   string     

Email address.

UC_PHONE   integer     

Primary phone number.

UC_PHONE2   integer     

Additional phone number.

UC_GSM   integer     

Mobile phone number.

UC_FAX   integer     

Fax number.

UC_FINANCE   integer     

Finance contact flag. 1 = contact for finance/billing matters.

UC_TECHNIC   integer     

Technical contact flag. 1 = contact for technical matters.

UC_LEADER   integer     

Statutory representative flag. 1 = contact is a company representative (jednatel).

UC_MANAGEMENT   integer     

Management contact flag. 1 = contact is in management.

UC_MARKETING   integer     

Marketing contact flag. 1 = contact for marketing matters.

UC_SHOP   integer     

Sales/shop contact flag. 1 = contact for sales and orders.

Get Customer Contact

requires authentication 

Retrieve a specific customer contact by ID.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-contacts/21" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-contacts/21"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "UC_ID": 20908,
        "UC_USER_ID": 681,
        "UC_P_ID": null,
        "UC_LOGIN": null,
        "UC_LAST_NAME": "Price",
        "UC_FIRST_NAME": "Amber",
        "UC_EMAIL": "[email protected]",
        "UC_PHONE": 420760725744,
        "UC_PHONE2": null,
        "UC_GSM": 420659135052,
        "UC_FAX": null,
        "UC_FINANCE": 0,
        "UC_TECHNIC": 0,
        "UC_LEADER": 0,
        "UC_MANAGEMENT": 0,
        "UC_MARKETING": 0,
        "UC_SHOP": 0,
        "UC_POSITION": null
    }
}

Request      

GET api/v3/customer-contacts/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the customer contact. Example: 21

Response

Response Fields

data   object     
UC_ID   integer     

Unique contact record ID (primary key).

UC_USER_ID   integer     

Customer ID this contact belongs to. See GET /v3/customers/{id}.

UC_P_ID   integer     

Premise ID (point of presence) associated with this contact.

UC_LAST_NAME   string     

Contact person's last name (surname).

UC_FIRST_NAME   string     

Contact person's first name.

UC_LOGIN   string     

Login name for the customer portal (SelfCare).

UC_POSITION   string     

Position code from the code list (installation-specific values, e.g. "DIR" = director, "UCT" = accountant, "SEC" = secretary).

UC_EMAIL   string     

Email address.

UC_PHONE   integer     

Primary phone number.

UC_PHONE2   integer     

Additional phone number.

UC_GSM   integer     

Mobile phone number.

UC_FAX   integer     

Fax number.

UC_FINANCE   integer     

Finance contact flag. 1 = contact for finance/billing matters.

UC_TECHNIC   integer     

Technical contact flag. 1 = contact for technical matters.

UC_LEADER   integer     

Statutory representative flag. 1 = contact is a company representative (jednatel).

UC_MANAGEMENT   integer     

Management contact flag. 1 = contact is in management.

UC_MARKETING   integer     

Marketing contact flag. 1 = contact for marketing matters.

UC_SHOP   integer     

Sales/shop contact flag. 1 = contact for sales and orders.

Customer Groups

List Customer Groups

requires authentication 

Retrieve a paginated list of customer groups.
By default, only active groups (G_ACTIVE=1) are returned.
Pass `active=all` to include inactive groups.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-groups?per_page=10&page=1&ids=1%2C2%2C3&cts=1%2C2%2C3&active=true&type=OTHER&search=VIP" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-groups"
);

const params = {
    "per_page": "10",
    "page": "1",
    "ids": "1,2,3",
    "cts": "1,2,3",
    "active": "true",
    "type": "OTHER",
    "search": "VIP",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "ID": 2660,
            "G_TARGET": "user",
            "GROUP_NAME": "adipisci quidem nostrum",
            "NOTE": null,
            "G_NOTE_BS": null,
            "CT": 6,
            "G_TYPE": "SELFCARE",
            "G_UDF_COLOR": null,
            "G_VIRTUAL": 0,
            "G_USER_DETAIL": 0,
            "G_WIZARD": 0,
            "G_ACTIVE": 1,
            "G_SELFCARE": 0,
            "G_DETAIL": null
        },
        {
            "ID": 2661,
            "G_TARGET": "user",
            "GROUP_NAME": "odit et et",
            "NOTE": "Nostrum omnis autem et consequatur aut.",
            "G_NOTE_BS": null,
            "CT": 7,
            "G_TYPE": "SELFCARE",
            "G_UDF_COLOR": null,
            "G_VIRTUAL": 0,
            "G_USER_DETAIL": 0,
            "G_WIZARD": 0,
            "G_ACTIVE": 1,
            "G_SELFCARE": 0,
            "G_DETAIL": null
        }
    ]
}

Request      

GET api/v3/customer-groups

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of groups to return per page (optional) Example: 10

page   integer  optional    

Page number to return (optional) Example: 1

ids   string  optional    

Filter by comma-separated IDs Example: 1,2,3

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Example: 1,2,3

active   string  optional    

Filter by active status. 'true' = active only (default), 'false' = inactive only, 'all' = both. Example: true

type   string  optional    

Filter by group type. Example: OTHER

search   string  optional    

Search by group name (partial match). Example: VIP

Response

Response Fields

data   object     
ID   integer     

Unique customer group identifier (primary key).

GROUP_NAME   string     

Name of the customer group.

CT   integer     

Company/tenant identifier — multi-tenant discriminator.

G_TARGET   string     

Target entity type for the group. Possible values: "user" (customer group), "premise" (premise group).

Must be one of:
  • user
  • premise
G_TYPE   string     

Group type. Possible values: "OTHER" (general purpose), "ACCESS" (operator access control), "SELFCARE" (product availability in selfcare), "SC_TYPE" (selfcare access type), "SELFCARE_MTT" (process display in selfcare).

Must be one of:
  • OTHER
  • ACCESS
  • SELFCARE
  • SC_TYPE
  • SELFCARE_MTT
G_ACTIVE   integer     

Active flag. 1 = active, 0 = inactive. Inactive groups are hidden by default.

G_VIRTUAL   integer     

Virtual group flag. 1 = virtual (membership is computed from rules, users cannot be directly assigned). 0 = regular group.

G_USER_DETAIL   integer     

Flag indicating the group is displayed in the customer detail view. 1 = shown.

G_WIZARD   integer     

Flag indicating the group is available in the new customer wizard. 1 = shown.

G_SELFCARE   integer     

Selfcare visibility flag.

NOTE   string     

Group note / description.

G_NOTE_BS   string     

Extended group note (rich text / business note).

G_UDF_COLOR   integer     

User-defined color for the group (stored as an integer color value).

G_DETAIL   integer     

Reference ID to additional group information in related tables.

members   object[]     

Group membership records — each entry links a customer to this group. Only included in the show (detail) endpoint.
ID   integer     

Unique membership record identifier.

GROUP_ID   integer     

Customer group ID. See GET /v3/customer-groups/{id}.

USER_ID   integer     

Customer ID. See GET /v3/customers/{id}.

Get Customer Group

requires authentication 

Retrieve a specific customer group by ID, including its user group memberships.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-groups/141" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-groups/141"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "ID": 2662,
        "G_TARGET": "user",
        "GROUP_NAME": "adipisci quidem nostrum",
        "NOTE": null,
        "G_NOTE_BS": null,
        "CT": 6,
        "G_TYPE": "SELFCARE",
        "G_UDF_COLOR": null,
        "G_VIRTUAL": 0,
        "G_USER_DETAIL": 0,
        "G_WIZARD": 0,
        "G_ACTIVE": 1,
        "G_SELFCARE": 0,
        "G_DETAIL": null,
        "members": [
            {
                "ID": 1367146,
                "GROUP_ID": 2662,
                "USER_ID": 1038
            }
        ]
    }
}

Request      

GET api/v3/customer-groups/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the customer group. Example: 141

Response

Response Fields

data   object     
ID   integer     

Unique customer group identifier (primary key).

GROUP_NAME   string     

Name of the customer group.

CT   integer     

Company/tenant identifier — multi-tenant discriminator.

G_TARGET   string     

Target entity type for the group. Possible values: "user" (customer group), "premise" (premise group).

Must be one of:
  • user
  • premise
G_TYPE   string     

Group type. Possible values: "OTHER" (general purpose), "ACCESS" (operator access control), "SELFCARE" (product availability in selfcare), "SC_TYPE" (selfcare access type), "SELFCARE_MTT" (process display in selfcare).

Must be one of:
  • OTHER
  • ACCESS
  • SELFCARE
  • SC_TYPE
  • SELFCARE_MTT
G_ACTIVE   integer     

Active flag. 1 = active, 0 = inactive. Inactive groups are hidden by default.

G_VIRTUAL   integer     

Virtual group flag. 1 = virtual (membership is computed from rules, users cannot be directly assigned). 0 = regular group.

G_USER_DETAIL   integer     

Flag indicating the group is displayed in the customer detail view. 1 = shown.

G_WIZARD   integer     

Flag indicating the group is available in the new customer wizard. 1 = shown.

G_SELFCARE   integer     

Selfcare visibility flag.

NOTE   string     

Group note / description.

G_NOTE_BS   string     

Extended group note (rich text / business note).

G_UDF_COLOR   integer     

User-defined color for the group (stored as an integer color value).

G_DETAIL   integer     

Reference ID to additional group information in related tables.

members   object[]     

Group membership records — each entry links a customer to this group. Only included in the show (detail) endpoint.
ID   integer     

Unique membership record identifier.

GROUP_ID   integer     

Customer group ID. See GET /v3/customer-groups/{id}.

USER_ID   integer     

Customer ID. See GET /v3/customers/{id}.

Customer Param Definitions

List Customer Param Definitions

requires authentication 

Retrieve a paginated list of customer parameter definitions.
By default, only enabled definitions (UPD_DISABLED=0) are returned.
Pass `disabled=all` to include disabled definitions.
Global definitions (UPD_CT IS NULL) are always included alongside
location-specific ones.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-param-definitions?per_page=10&page=1&ids=101%2C133%2C135&cts=31%2C101&disabled=all&target=user" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-param-definitions"
);

const params = {
    "per_page": "10",
    "page": "1",
    "ids": "101,133,135",
    "cts": "31,101",
    "disabled": "all",
    "target": "user",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "UPD_ID": 1034,
            "UPD_CT": 181,
            "UPD_TARGET": "user",
            "UPD_NAME": "QUIDEM",
            "UPD_DISPLAY": "nostrum qui",
            "UPD_DEFAULT_VALUE": "",
            "UPD_TYPE": "DATE",
            "UPD_INDEXED": 0,
            "UPD_DOMAIN": null,
            "UPD_NOTNULL": 0,
            "UPD_TIME_RESOLUTION": 0,
            "UPD_DISABLED": 0,
            "UPD_PUBLIC": 0,
            "UPD_L_ID": 709,
            "UPD_CREATED": "2026-03-13 12:50:02",
            "UPD_DOC_VARNAME": "",
            "UPD_SHOW": 1,
            "UPD_PAY_SHOW": 0,
            "UPD_PROVISIONING": 0,
            "UPD_SYSTEM": "N",
            "UPD_SC_VISIBLE": null,
            "UPD_SC_EDITABLE": null
        },
        {
            "UPD_ID": 1035,
            "UPD_CT": 180,
            "UPD_TARGET": "user",
            "UPD_NAME": "ET",
            "UPD_DISPLAY": "modi ipsum",
            "UPD_DEFAULT_VALUE": "",
            "UPD_TYPE": "NUM",
            "UPD_INDEXED": 0,
            "UPD_DOMAIN": null,
            "UPD_NOTNULL": 0,
            "UPD_TIME_RESOLUTION": 0,
            "UPD_DISABLED": 0,
            "UPD_PUBLIC": 0,
            "UPD_L_ID": 646,
            "UPD_CREATED": "2026-01-15 09:47:06",
            "UPD_DOC_VARNAME": "",
            "UPD_SHOW": 1,
            "UPD_PAY_SHOW": 0,
            "UPD_PROVISIONING": 0,
            "UPD_SYSTEM": "N",
            "UPD_SC_VISIBLE": null,
            "UPD_SC_EDITABLE": null
        }
    ]
}

Request      

GET api/v3/customer-param-definitions

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of definitions to return per page (optional) Example: 10

page   integer  optional    

Page number to return (optional) Example: 1

ids   string  optional    

Filter by comma-separated definition IDs Example: 101,133,135

cts   string  optional    

Filter by comma-separated location (installation) IDs. Returns global definitions (UPD_CT IS NULL) plus definitions for the specified CTs. Overrides X-CT header default. Example: 31,101

disabled   string  optional    

Filter by disabled status. Default (omitted): only enabled (UPD_DISABLED=0). 'true' = disabled only, 'all' = both enabled and disabled. Example: all

target   string  optional    

Filter by target entity type. Example: user

Response

Response Fields

data   object     
UPD_ID   integer     

Unique parameter definition ID (primary key).

UPD_CT   integer     

Location (installation) ID this definition belongs to. NULL = global definition available to all locations.

UPD_TARGET   string     

Target entity type: 'user' = customer parameter, 'premise' = premise parameter.

Must be one of:
  • user
  • premise
UPD_NAME   string     

Parameter name (unique within a CT or globally). Max 50 characters.

UPD_DISPLAY   string     

Display label shown in the UI.

UPD_DEFAULT_VALUE   string     

Default value for new parameter instances.

UPD_TYPE   string     

Data type of the parameter value.

Must be one of:
  • STRING
  • NUM
  • FLOAT
  • PRICE
  • BOOL
  • DATE
  • FILE
  • PREMISEIDBOX
  • PREMISEIDMEGA
  • SELECT
UPD_DOMAIN   string     

Value constraints / domain (e.g. allowed values for SELECT type). JSON or delimited format.

UPD_NOTNULL   integer     

Whether this parameter is required (1 = mandatory, 0 = optional).

UPD_TIME_RESOLUTION   integer     

Whether temporal (valid_from/valid_to) resolution is enabled for this parameter.

UPD_INDEXED   integer     

Whether the parameter values are indexed for search.

UPD_DISABLED   integer     

Whether the definition is disabled (1 = disabled, 0 = active). Disabled definitions are excluded from listings by default.

UPD_PUBLIC   integer     

Whether the parameter is publicly visible.

UPD_SHOW   integer     

Whether to display the parameter on customer detail views.

UPD_PAY_SHOW   integer     

Whether to display the parameter in payment/billing context.

UPD_PROVISIONING   integer     

Whether this parameter is provisioned to external systems (e.g. Portax).

UPD_SYSTEM   string     

System classification: 'N' = normal (user-defined), 'S' = system (managed by Mango), 'I' = internal (hidden from UI).

Must be one of:
  • N
  • S
  • I
UPD_SC_VISIBLE   integer     

Whether the parameter is visible in the customer self-care portal.

UPD_SC_EDITABLE   integer     

Whether the parameter is editable by the customer in the self-care portal.

UPD_DOC_VARNAME   string     

Variable name used in document templates for this parameter.

UPD_L_ID   integer     

ID of the login session that created this definition.

UPD_CREATED   string     

Timestamp when this definition was created. Format: YYYY-MM-DD HH:MM:SS.

Customer Service Discounts

List Customer Service Discounts

requires authentication

Returns a paginated list of discounts applied to customer services. Filterable by customer, service, discount definition, status, and more. CT scoping is indirect — resolved via the customer's location.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-service-discounts?per_page=15&page=1&ids=1%2C2%2C3&cts=1%2C2%2C3&customer=100&customer_service=500&discount_definition=10&status=ACTIVE%2CWAITING&active=1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-service-discounts"
);

const params = {
    "per_page": "15",
    "page": "1",
    "ids": "1,2,3",
    "cts": "1,2,3",
    "customer": "100",
    "customer_service": "500",
    "discount_definition": "10",
    "status": "ACTIVE,WAITING",
    "active": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "SAD_ID": 309330,
            "SAD_U_ID": 2878,
            "SAD_SA_ID": 2839,
            "SAD_SD_ID": 50,
            "SAD_DEP_SA_IDS": null,
            "SAD_TYPE": "definite",
            "SAD_VALUE": "66.2031",
            "SAD_START": null,
            "SAD_STOP": null,
            "SAD_CREATED": "2026-02-08 13:34:45",
            "SAD_CREATOR_L_ID": 3940,
            "SAD_STATUS": "ACTIVE",
            "SAD_POINTS": null,
            "SAD_SD_START_RECREATE": null,
            "SAD_SADG_ID": null,
            "SAD_END_NOTIFIED": null,
            "SAD_STOP_FLOATING": null
        },
        {
            "SAD_ID": 309331,
            "SAD_U_ID": 336,
            "SAD_SA_ID": 4086,
            "SAD_SD_ID": 50,
            "SAD_DEP_SA_IDS": null,
            "SAD_TYPE": "percentage",
            "SAD_VALUE": "88.5325",
            "SAD_START": null,
            "SAD_STOP": null,
            "SAD_CREATED": "2026-02-24 13:30:25",
            "SAD_CREATOR_L_ID": 7018,
            "SAD_STATUS": "ACTIVE",
            "SAD_POINTS": null,
            "SAD_SD_START_RECREATE": null,
            "SAD_SADG_ID": null,
            "SAD_END_NOTIFIED": null,
            "SAD_STOP_FLOATING": null
        }
    ]
}

Request      

GET api/v3/customer-service-discounts

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of results per page. Example: 15

page   integer  optional    

Page number. Example: 1

ids   string  optional    

Filter by comma-separated customer service discount IDs. Example: 1,2,3

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Resolves indirectly via customer. Example: 1,2,3

customer   integer  optional    

Filter by customer (user) ID. Example: 100

customer_service   integer  optional    

Filter by customer service (services_active) ID. Example: 500

discount_definition   integer  optional    

Filter by discount definition (campaign) ID. Example: 10

status   string  optional    

Filter by status. Comma-separated for multiple values. Example: ACTIVE,WAITING

active   boolean  optional    

Shorthand: when true, returns only ACTIVE discounts. Ignored when status is provided. Example: true

Response

Response Fields

data   object     
SAD_ID   integer     

Active discount ID (primary key).

SAD_U_ID   integer     

Customer ID. The customer who owns the discounted service. See GET /v3/customers/{id}.

SAD_SA_ID   integer     

Active service ID. The service this discount is applied to. See GET /v3/customer-services/{id}.

SAD_SD_ID   integer     

Discount definition ID. The discount campaign template this instance is based on. See GET /v3/discount-definitions/{id}.

SAD_TYPE   string     

Discount type. Determines how SAD_VALUE is interpreted.

Must be one of:
  • percentage
  • definite
  • credit
  • points
SAD_VALUE   number     

Discount value. Interpretation depends on SAD_TYPE: percentage = % off, definite = fixed currency amount, credit = credit amount, points = point value.

SAD_POINTS   integer     

Loyalty/bonus points associated with this discount.

SAD_START   string     

Discount validity start date (YYYY-MM-DD). If null, defaults to the service billing start (ACCOUNT_FROM).

SAD_STOP   string     

Discount validity end date (YYYY-MM-DD). If null, the discount runs until the service billing end.

SAD_STOP_FLOATING   string     

Floating (relative) end date for the discount (YYYY-MM-DD). Used when the discount duration is relative rather than fixed.

SAD_STATUS   string     

Current status of the discount.

Must be one of:
  • ACTIVE
  • WAITING
  • FINISHED
SAD_DEP_SA_IDS   string     

Comma-separated list of dependent active service IDs. Links the discount to specific dependent services.

SAD_SADG_ID   integer     

Discount group ID. Groups related discounts together.

SAD_SD_START_RECREATE   integer     

Flag indicating whether the discount should be recreated on group discount start. 1 = recreate on start.

SAD_CREATED   string     

Timestamp when this discount was created (YYYY-MM-DD HH:MM:SS).

SAD_CREATOR_L_ID   integer     

Creator operator (login) ID. The admin/operator who created this discount.

SAD_END_NOTIFIED   string     

Timestamp when the discount end notification was sent (YYYY-MM-DD HH:MM:SS).

Get Customer Service Discount

requires authentication

Returns a single customer service discount by ID.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-service-discounts/474" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-service-discounts/474"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "SAD_ID": 309332,
        "SAD_U_ID": 2878,
        "SAD_SA_ID": 2839,
        "SAD_SD_ID": 50,
        "SAD_DEP_SA_IDS": null,
        "SAD_TYPE": "definite",
        "SAD_VALUE": "66.2031",
        "SAD_START": null,
        "SAD_STOP": null,
        "SAD_CREATED": "2026-02-08 13:34:45",
        "SAD_CREATOR_L_ID": 3940,
        "SAD_STATUS": "ACTIVE",
        "SAD_POINTS": null,
        "SAD_SD_START_RECREATE": null,
        "SAD_SADG_ID": null,
        "SAD_END_NOTIFIED": null,
        "SAD_STOP_FLOATING": null
    }
}

Request      

GET api/v3/customer-service-discounts/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the customer service discount. Example: 474

Response

Response Fields

data   object     
SAD_ID   integer     

Active discount ID (primary key).

SAD_U_ID   integer     

Customer ID. The customer who owns the discounted service. See GET /v3/customers/{id}.

SAD_SA_ID   integer     

Active service ID. The service this discount is applied to. See GET /v3/customer-services/{id}.

SAD_SD_ID   integer     

Discount definition ID. The discount campaign template this instance is based on. See GET /v3/discount-definitions/{id}.

SAD_TYPE   string     

Discount type. Determines how SAD_VALUE is interpreted.

Must be one of:
  • percentage
  • definite
  • credit
  • points
SAD_VALUE   number     

Discount value. Interpretation depends on SAD_TYPE: percentage = % off, definite = fixed currency amount, credit = credit amount, points = point value.

SAD_POINTS   integer     

Loyalty/bonus points associated with this discount.

SAD_START   string     

Discount validity start date (YYYY-MM-DD). If null, defaults to the service billing start (ACCOUNT_FROM).

SAD_STOP   string     

Discount validity end date (YYYY-MM-DD). If null, the discount runs until the service billing end.

SAD_STOP_FLOATING   string     

Floating (relative) end date for the discount (YYYY-MM-DD). Used when the discount duration is relative rather than fixed.

SAD_STATUS   string     

Current status of the discount.

Must be one of:
  • ACTIVE
  • WAITING
  • FINISHED
SAD_DEP_SA_IDS   string     

Comma-separated list of dependent active service IDs. Links the discount to specific dependent services.

SAD_SADG_ID   integer     

Discount group ID. Groups related discounts together.

SAD_SD_START_RECREATE   integer     

Flag indicating whether the discount should be recreated on group discount start. 1 = recreate on start.

SAD_CREATED   string     

Timestamp when this discount was created (YYYY-MM-DD HH:MM:SS).

SAD_CREATOR_L_ID   integer     

Creator operator (login) ID. The admin/operator who created this discount.

SAD_END_NOTIFIED   string     

Timestamp when the discount end notification was sent (YYYY-MM-DD HH:MM:SS).

Customer Service Event Types

List Service Event Types

requires authentication 

Retrieve a paginated list of service event types.
This is a global codelist — no CT scoping is applied.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-service-event-types?per_page=10&page=1&ids=1%2C2%2C3" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-service-event-types"
);

const params = {
    "per_page": "10",
    "page": "1",
    "ids": "1,2,3",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "ID": 4,
            "NAME": "Poznámka",
            "SET_PRICE_AFFECT": 0,
            "SET_ATTACHMENT": 0,
            "SET_MT_NAME": null,
            "SET_CAN_DELETE": 1,
            "SET_CAN_EDIT": 1,
            "SET_EU_SHOW": 0,
            "SET_PDC_ERASE": 1
        },
        {
            "ID": 63,
            "NAME": "Storno objednávky",
            "SET_PRICE_AFFECT": 1,
            "SET_ATTACHMENT": 0,
            "SET_MT_NAME": null,
            "SET_CAN_DELETE": 0,
            "SET_CAN_EDIT": 0,
            "SET_EU_SHOW": 0,
            "SET_PDC_ERASE": 1
        }
    ]
}

Request      

GET api/v3/customer-service-event-types

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of results per page (optional) Example: 10

page   integer  optional    

Page number to return (optional) Example: 1

ids   string  optional    

Filter by comma-separated IDs Example: 1,2,3

Response

Response Fields

data   object     
ID   integer     

Unique event type identifier.

NAME   string     

Event type name (e.g. "Aktivace služby", "Změna ceny").

SET_PRICE_AFFECT   integer     

Whether this event type affects pricing.

SET_ATTACHMENT   integer     

Whether this event type supports file attachments.

SET_MT_NAME   string     

Associated maintenance task type name.

SET_CAN_DELETE   integer     

Whether events of this type can be deleted (0=no, 1=yes, 2=conditional).

SET_CAN_EDIT   integer     

Whether events of this type can be edited.

SET_EU_SHOW   integer     

Whether this event type is visible in the end-user (selfcare) portal.

SET_PDC_ERASE   integer     

Whether events of this type are erased during personal data cleanup.

Customer Service History

List Service History

requires authentication 

Retrieve a paginated list of service history events.
At least one identifying filter (customer, service_id, customer_service, or event_type) is required.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-service-history?per_page=10&page=1&ids=1%2C2%2C3&cts=1%2C2%2C3&customer=100&service_id=50&customer_service=200&event_type=4&created_from=2024-01-01&created_to=2024-12-31&search=Aktivace" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-service-history"
);

const params = {
    "per_page": "10",
    "page": "1",
    "ids": "1,2,3",
    "cts": "1,2,3",
    "customer": "100",
    "service_id": "50",
    "customer_service": "200",
    "event_type": "4",
    "created_from": "2024-01-01",
    "created_to": "2024-12-31",
    "search": "Aktivace",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "ID": 779343307,
            "USER_ID": 641,
            "SERVICE_ID": 0,
            "USER_SERVICE_ID": 0,
            "TIME": "2026-01-28 02:36:52",
            "CHANGE_TIME": "1994-12-16",
            "EVENT_TYPE": 10,
            "PRICE": null,
            "PAYMENT_DEPRECATED": null,
            "SH_PERIOD": "none",
            "NOTE_TITLE": null,
            "NOTE_BODY": null,
            "ADD_PARAM": null,
            "AUTHOR": 0,
            "SH_TRANSFER": 0,
            "SH_CRM_CHANNEL": null,
            "SH_DR_ID": null,
            "SH_SELFCARE": 0,
            "params": [
                {
                    "SHP_ID": 20456534,
                    "SHP_SH_ID": 779343307,
                    "SHP_NAME": "cupiditate",
                    "SHP_VALUE": "Nemo deleniti repellat atque minima."
                }
            ]
        },
        {
            "ID": 779343308,
            "USER_ID": 583,
            "SERVICE_ID": 0,
            "USER_SERVICE_ID": 0,
            "TIME": "2026-02-16 22:27:47",
            "CHANGE_TIME": "2019-03-31",
            "EVENT_TYPE": 1,
            "PRICE": null,
            "PAYMENT_DEPRECATED": null,
            "SH_PERIOD": "none",
            "NOTE_TITLE": null,
            "NOTE_BODY": null,
            "ADD_PARAM": null,
            "AUTHOR": 0,
            "SH_TRANSFER": 0,
            "SH_CRM_CHANNEL": null,
            "SH_DR_ID": null,
            "SH_SELFCARE": 0,
            "params": [
                {
                    "SHP_ID": 20456535,
                    "SHP_SH_ID": 779343308,
                    "SHP_NAME": "repudiandae",
                    "SHP_VALUE": "Id dolor aut hic at at."
                }
            ]
        }
    ]
}

Request      

GET api/v3/customer-service-history

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of results per page (optional) Example: 10

page   integer  optional    

Page number to return (optional) Example: 1

ids   string  optional    

Filter by comma-separated service history IDs Example: 1,2,3

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Example: 1,2,3

customer   integer  optional    

Filter by customer ID (USER_ID) Example: 100

service_id   integer  optional    

Filter by service definition ID (SERVICE_ID) Example: 50

customer_service   integer  optional    

Filter by active service instance ID (USER_SERVICE_ID) Example: 200

event_type   integer  optional    

Filter by event type ID (EVENT_TYPE) Example: 4

created_from   string  optional    

Filter events created on or after this date/datetime (TIME column) Example: 2024-01-01

created_to   string  optional    

Filter events created on or before this date/datetime (TIME column) Example: 2024-12-31

search   string  optional    

Search by event note title (partial match on NOTE_TITLE) Example: Aktivace

Response

Response Fields

data   object     
ID   integer     

Unique service history event identifier.

USER_ID   integer     

Customer ID. See GET /v3/customers/{id}.

SERVICE_ID   integer     

Service definition ID. See GET /v3/service-definitions/{id}.

USER_SERVICE_ID   integer     

Active service instance ID. See GET /v3/customer-services/{id}.

EVENT_TYPE   integer     

Event type ID. See GET /v3/customer-service-event-types.

TIME   string     

Event creation timestamp (datetime).

CHANGE_TIME   string     

Event effective/validity date.

PRICE   number     

Event-related price value.

SH_PERIOD   string     

Billing period associated with this event.

NOTE_TITLE   string     

Event note title / short description.

NOTE_BODY   string     

Event detailed description (long text).

ADD_PARAM   string     

Additional parameter string.

AUTHOR   integer     

Login ID of the operator who created this event.

SH_TRANSFER   integer     

Transfer flag.

SH_CRM_CHANNEL   integer     

CRM/sales channel identifier.

SH_DR_ID   integer     

Debt recovery process ID.

SH_SELFCARE   integer     

Whether the event originated from selfcare (end-user portal).

params   object[]     

Historical parameter snapshots associated with this event.
SHP_ID   integer     

Parameter record identifier.

SHP_SH_ID   integer     

Parent service history event ID.

SHP_NAME   string     

Parameter name.

SHP_VALUE   string     

Parameter value.

Get Service History Event

requires authentication 

Retrieve a specific service history event by ID, including its parameter snapshots.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-service-history/123" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-service-history/123"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "ID": 779343309,
        "USER_ID": 2878,
        "SERVICE_ID": 0,
        "USER_SERVICE_ID": 0,
        "TIME": "2026-02-03 00:20:21",
        "CHANGE_TIME": "2006-09-25",
        "EVENT_TYPE": 3,
        "PRICE": null,
        "PAYMENT_DEPRECATED": null,
        "SH_PERIOD": "none",
        "NOTE_TITLE": null,
        "NOTE_BODY": null,
        "ADD_PARAM": null,
        "AUTHOR": 0,
        "SH_TRANSFER": 0,
        "SH_CRM_CHANNEL": null,
        "SH_DR_ID": null,
        "SH_SELFCARE": 0,
        "params": [
            {
                "SHP_ID": 20456536,
                "SHP_SH_ID": 779343309,
                "SHP_NAME": "qui",
                "SHP_VALUE": "Incidunt iure odit et et modi ipsum."
            }
        ]
    }
}

Request      

GET api/v3/customer-service-history/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the customer service history. Example: 123

Response

Response Fields

data   object     
ID   integer     

Unique service history event identifier.

USER_ID   integer     

Customer ID. See GET /v3/customers/{id}.

SERVICE_ID   integer     

Service definition ID. See GET /v3/service-definitions/{id}.

USER_SERVICE_ID   integer     

Active service instance ID. See GET /v3/customer-services/{id}.

EVENT_TYPE   integer     

Event type ID. See GET /v3/customer-service-event-types.

TIME   string     

Event creation timestamp (datetime).

CHANGE_TIME   string     

Event effective/validity date.

PRICE   number     

Event-related price value.

SH_PERIOD   string     

Billing period associated with this event.

NOTE_TITLE   string     

Event note title / short description.

NOTE_BODY   string     

Event detailed description (long text).

ADD_PARAM   string     

Additional parameter string.

AUTHOR   integer     

Login ID of the operator who created this event.

SH_TRANSFER   integer     

Transfer flag.

SH_CRM_CHANNEL   integer     

CRM/sales channel identifier.

SH_DR_ID   integer     

Debt recovery process ID.

SH_SELFCARE   integer     

Whether the event originated from selfcare (end-user portal).

params   object[]     

Historical parameter snapshots associated with this event.
SHP_ID   integer     

Parameter record identifier.

SHP_SH_ID   integer     

Parent service history event ID.

SHP_NAME   string     

Parameter name.

SHP_VALUE   string     

Parameter value.

Customer Services

List Customer Services

requires authentication

Returns a paginated list of customer services. By default, cancelled services (state 02) are excluded.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-services?ids=1%2C2%2C3&cts=1%2C2%2C3&user=100&state=01%2C03&periodic=true&dependent=true&base_service=500&device=200&provider=500&service_definition=10%2C20%2C30&billing_plan=42" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-services"
);

const params = {
    "ids": "1,2,3",
    "cts": "1,2,3",
    "user": "100",
    "state": "01,03",
    "periodic": "true",
    "dependent": "true",
    "base_service": "500",
    "device": "200",
    "provider": "500",
    "service_definition": "10,20,30",
    "billing_plan": "42",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "ID": 4591613,
            "USER_ID": "02878",
            "SERVICE_ID": "2839",
            "PRICE": "3668.8918",
            "DATE_START": "2015-01-19",
            "DATE_END": null,
            "STATE": "01",
            "PAYMENT_DEPRECATED": null,
            "ACCOUNT_FROM": "2022-12-14",
            "ACCOUNT_TO": null,
            "DUE_DATE": 30,
            "VAR_SYMBOL": null,
            "ACCORD_NUM": null,
            "TRADING_LIMIT": null,
            "SA_TRADING_LIMIT_ALERTED": 0,
            "CUSTOMER_CHANGE_DEPRECATED": null,
            "SA_PERIOD": "cyear",
            "SA_LOCATION": null,
            "SA_TAX_CLOSURE": null,
            "SA_TAX_PREV_CLOSURE": null,
            "NOTE": null,
            "SA_INV_NOTE": null,
            "SA_P_ID": null,
            "SA_CANCEL_REASON": null,
            "SA_AGREEMENT_DATE": null,
            "SA_NEEDS_PROCESS": null,
            "SA_CREATED": "2026-04-15 14:55:09",
            "SA_SALESMAN_ID": null,
            "SA_MOVING": 0,
            "SA_MOVE_DATA": null,
            "SA_BOND_START": null,
            "SA_NODEAVAIL_SGD_ID": null,
            "SA_NAME": null,
            "SA_PROVIDER_USER_ID": null,
            "SA_PAY_TO": null,
            "SA_DATE_BASE": null,
            "params": [
                {
                    "SP_ID": "0003567104",
                    "SP_SRV_ID": 4591613,
                    "SP_NAME": "msisdn",
                    "SP_VALID_FROM": "1973-12-17",
                    "SP_VALID_TO": null,
                    "SP_VALUE": "ipsum",
                    "SP_CREATED": "2026-02-24 13:31:05",
                    "SP_L_ID": "007018"
                }
            ],
            "discounts": [
                {
                    "SAD_ID": 309324,
                    "SAD_U_ID": 4486,
                    "SAD_SA_ID": 4591613,
                    "SAD_SD_ID": 50,
                    "SAD_DEP_SA_IDS": null,
                    "SAD_TYPE": "points",
                    "SAD_VALUE": "72.9772",
                    "SAD_START": "1997-06-20",
                    "SAD_STOP": null,
                    "SAD_CREATED": "2026-02-23 08:05:41",
                    "SAD_CREATOR_L_ID": 2327,
                    "SAD_STATUS": "FINISHED",
                    "SAD_POINTS": null,
                    "SAD_SD_START_RECREATE": null,
                    "SAD_SADG_ID": null,
                    "SAD_END_NOTIFIED": null,
                    "SAD_STOP_FLOATING": null
                }
            ]
        },
        {
            "ID": 4591614,
            "USER_ID": "05468",
            "SERVICE_ID": "5937",
            "PRICE": "8661.9358",
            "DATE_START": "2023-08-06",
            "DATE_END": null,
            "STATE": "02",
            "PAYMENT_DEPRECATED": null,
            "ACCOUNT_FROM": "1975-05-01",
            "ACCOUNT_TO": null,
            "DUE_DATE": 30,
            "VAR_SYMBOL": null,
            "ACCORD_NUM": null,
            "TRADING_LIMIT": null,
            "SA_TRADING_LIMIT_ALERTED": 0,
            "CUSTOMER_CHANGE_DEPRECATED": null,
            "SA_PERIOD": "none",
            "SA_LOCATION": "Daphneview",
            "SA_TAX_CLOSURE": null,
            "SA_TAX_PREV_CLOSURE": null,
            "NOTE": "Libero aliquam veniam corporis dolorem mollitia deleniti.",
            "SA_INV_NOTE": null,
            "SA_P_ID": null,
            "SA_CANCEL_REASON": null,
            "SA_AGREEMENT_DATE": null,
            "SA_NEEDS_PROCESS": null,
            "SA_CREATED": "2026-04-15 14:55:09",
            "SA_SALESMAN_ID": null,
            "SA_MOVING": 0,
            "SA_MOVE_DATA": null,
            "SA_BOND_START": null,
            "SA_NODEAVAIL_SGD_ID": null,
            "SA_NAME": null,
            "SA_PROVIDER_USER_ID": null,
            "SA_PAY_TO": null,
            "SA_DATE_BASE": null,
            "params": [
                {
                    "SP_ID": "0003567105",
                    "SP_SRV_ID": 4591614,
                    "SP_NAME": "msisdn",
                    "SP_VALID_FROM": "1976-09-02",
                    "SP_VALID_TO": null,
                    "SP_VALUE": "officia",
                    "SP_CREATED": "2026-04-02 21:12:33",
                    "SP_L_ID": "008925"
                }
            ],
            "discounts": [
                {
                    "SAD_ID": 309325,
                    "SAD_U_ID": 2531,
                    "SAD_SA_ID": 4591614,
                    "SAD_SD_ID": 50,
                    "SAD_DEP_SA_IDS": null,
                    "SAD_TYPE": "points",
                    "SAD_VALUE": "88.4282",
                    "SAD_START": null,
                    "SAD_STOP": null,
                    "SAD_CREATED": "2026-01-06 19:00:09",
                    "SAD_CREATOR_L_ID": 5560,
                    "SAD_STATUS": "WAITING",
                    "SAD_POINTS": null,
                    "SAD_SD_START_RECREATE": null,
                    "SAD_SADG_ID": null,
                    "SAD_END_NOTIFIED": null,
                    "SAD_STOP_FLOATING": null
                }
            ]
        }
    ]
}

Request      

GET api/v3/customer-services

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

ids   string  optional    

Filter by comma-separated service IDs Example: 1,2,3

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Example: 1,2,3

user   integer  optional    

Filter by customer (user) ID Example: 100

state   string  optional    

Filter by comma-separated state codes. Default: excludes cancelled (02) Example: 01,03

periodic   string  optional    

Filter by periodic billing: true = monthly (TYPE=M), false = one-time (TYPE=S) Example: true

dependent   string  optional    

Filter by dependency: true = dependent services, false = base services Example: true

base_service   integer  optional    

Filter dependent services linked to a specific base service ID Example: 500

device   integer  optional    

Filter services linked to a specific device (node) ID Example: 200

provider   integer  optional    

Filter by provider user ID Example: 500

service_definition   string  optional    

Filter by comma-separated service definition IDs Example: 10,20,30

billing_plan   integer  optional    

Filter by current billing plan ID Example: 42

Response

Response Fields

data   object     
ID   integer     

Active service ID (primary key).

USER_ID   integer     

Customer ID. The customer who owns this service. See GET /v3/customers/{id}.

SERVICE_ID   integer     

Service definition ID. The definition this active service is based on. See GET /v3/service-definitions/{id}.

STATE   integer     

Service state. 0 = blocked, 1 = active, 2 = cancelled, 3 = not connected (pending provisioning).

PRICE   number     

Price with VAT for this active service (one-time or per billing period).

DATE_START   string     

Service provision start date (YYYY-MM-DD).

DATE_END   string     

Service provision end date (YYYY-MM-DD). Null if the service is still active (open-ended).

ACCOUNT_FROM   string     

Billing start date (YYYY-MM-DD). Charges begin from this date.

ACCOUNT_TO   string     

Billing end date (YYYY-MM-DD). Null while billing is ongoing.

SA_AGREEMENT_DATE   string     

Agreement (contract) date for this service (YYYY-MM-DD).

SA_PERIOD   string     

Billing period. Possible values: 'month', 'cquarter', 'chalfyear', 'cyear', 'cyears2', 'cyears3', 'cmonths18', 'vmonth', 'vquarter', 'vhalfyear', 'vyear', 'vyears2', 'vyears3', 'vmonths18', 'all', 'none'. Prefix 'c' = calendar-aligned, 'v' = anniversary-aligned.

Must be one of:
  • all
  • chalfyear
  • cquarter
  • cyear
  • month
  • none
  • vhalfyear
  • vmonth
  • vquarter
  • vyear
  • cyears2
  • cyears3
  • cmonths18
  • vyears2
  • vyears3
  • vmonths18
DUE_DATE   integer     

Payment due period in days. Default: 30.

VAR_SYMBOL   integer     

Variable symbol (payment identifier) for this service.

SA_TAX_CLOSURE   string     

Last billing closure date for this service (YYYY-MM-DD).

SA_TAX_PREV_CLOSURE   string     

Previous billing closure date, before the last closure (YYYY-MM-DD).

SA_PAY_TO   string     

Service prepaid expiration date (YYYY-MM-DD). Paid until this date.

SA_DATE_BASE   string     

Base date for anniversary-based billing period calculations (YYYY-MM-DD).

SA_INV_NOTE   string     

Invoice note. Text printed on invoices for this service.

TRADING_LIMIT   string     

Minimum commitment (bond) expiration date (YYYY-MM-DD).

SA_TRADING_LIMIT_ALERTED   integer     

Flag indicating the TRADING_LIMIT has been changed but not yet alerted. 1 = change pending alert.

SA_BOND_START   string     

Minimum commitment (bond) start date (YYYY-MM-DD). Preserved across service transfers.

ACCORD_NUM   string     

Accord number (agreement/contract reference).

SA_LOCATION   string     

Service location identifier (free-text).

SA_P_ID   integer     

Premise ID (point of presence / service delivery location).

SA_MOVING   integer     

Moving flag. 1 = service is in the moving (relocation) processing phase. Relevant when the base service definition has SN_MOVE_SPLITTED = 1.

SA_MOVE_DATA   string     

Additional data for the service move operation.

SA_NEEDS_PROCESS   integer     

Process (maintenance ticket) ID required for provisioning this service.

SA_NODEAVAIL_SGD_ID   integer     

Node availability service group definition ID (process/technology group). See GET /v3/service-groups.

SA_NAME   string     

Commercial (custom) service name. Overrides the default service definition name when set.

SA_SALESMAN_ID   integer     

Salesman (admin/operator) ID who activated or manages this service.

SA_PROVIDER_USER_ID   integer     

Provider (operator) customer ID. See GET /v3/customers/{id}.

SA_CANCEL_REASON   integer     

Cancellation reason code (code list entry ID).

NOTE   string     

Note / remark for this service.

SA_CREATED   string     

Timestamp when this service was activated/created.

PAYMENT_DEPRECATED   string     

Deprecated payment field. No longer in active use.

CUSTOMER_CHANGE_DEPRECATED   integer     

Deprecated customer change flag. No longer in active use.

params   object[]     

Service parameter key-value pairs.
SP_ID   integer     

Service parameter ID (primary key).

SP_SRV_ID   integer     

Parent active service ID. See GET /v3/customer-services/{id}.

SP_NAME   string     

Parameter name (key), e.g. "msisdn", "sip_phone_number", "agr_max_down_speed".

SP_VALUE   string     

Parameter value. Stored as text; actual data type depends on the parameter definition.

SP_VALID_FROM   string     

Validity start date (YYYY-MM-DD).

SP_VALID_TO   string     

Validity end date (YYYY-MM-DD). Null means open-ended (no expiry).

SP_CREATED   string     

Timestamp when this parameter was created (YYYY-MM-DD HH:MM:SS).

SP_L_ID   integer     

Operator (login session) ID that created this parameter.

discounts   object[]     

Active discounts applied to this service.
SAD_ID   integer     

Active discount ID (primary key).

SAD_U_ID   integer     

Customer ID. See GET /v3/customers/{id}.

SAD_SA_ID   integer     

Active service ID. See GET /v3/customer-services/{id}.

SAD_SD_ID   integer     

Discount definition ID (a ServiceDiscount record — not directly exposed via API).

SAD_DEP_SA_IDS   string     

Comma-separated list of dependent active service IDs linked to this discount.

SAD_TYPE   string     

Discount type. Determines how SAD_VALUE is interpreted.

Must be one of:
  • percentage
  • definite
  • credit
  • points
SAD_VALUE   number     

Discount value. Interpretation depends on SAD_TYPE: percentage = % off, definite = fixed currency amount, credit = credit amount, points = point value.

SAD_START   string     

Discount validity start date (YYYY-MM-DD). If null, defaults to the service billing start.

SAD_STOP   string     

Discount validity end date (YYYY-MM-DD). If null, the discount runs until the service billing end.

SAD_CREATED   string     

Timestamp when this discount was created (YYYY-MM-DD HH:MM:SS).

SAD_CREATOR_L_ID   integer     

Operator (login session) ID that created this discount.

SAD_STATUS   string     

Current status of the discount.

Must be one of:
  • ACTIVE
  • WAITING
  • FINISHED
SAD_POINTS   integer     

Loyalty/bonus points associated with this discount.

SAD_SD_START_RECREATE   integer     

Flag indicating the discount should be recreated on group discount start. 1 = recreate on start.

SAD_SADG_ID   integer     

Discount group ID (groups related discounts together).

SAD_END_NOTIFIED   string     

Timestamp when the discount end notification was sent (YYYY-MM-DD HH:MM:SS).

SAD_STOP_FLOATING   string     

Floating (relative) end date for the discount (YYYY-MM-DD). Used when the discount duration is relative rather than fixed.

dependent_services   object[]     

Dependent (linked) services. Only included in single-resource (show) responses.
SAL_ID   integer     

Service linkage ID (primary key).

SAL_TYPE   string     

Linkage type.

Must be one of:
  • motivation1
  • dependency
  • together
  • fixed
  • dependency_free
SAL_SA_ID   integer     

Parent active service ID. See GET /v3/customer-services/{id}.

SAL_LINKED_SA_ID   integer     

Linked (dependent) active service ID. See GET /v3/customer-services/{id}.

SAL_VALID_FROM   string     

Linkage validity start date (YYYY-MM-DD).

SAL_VALID_TO   string     

Linkage validity end date (YYYY-MM-DD).

SAL_SAD_ID   integer     

Associated discount ID (a ServiceActiveDiscount record).

SAL_CREATED   string     

Timestamp when this linkage was created (YYYY-MM-DD HH:MM:SS).

SAL_CREATOR_ID   integer     

Operator (login session) ID that created this linkage.

Activate Customer Service

requires authentication

Activates (creates) a new customer service.

Example request:
curl --request POST \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-services" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"user_id\": 100,
    \"date_start\": \"2026-01-01\",
    \"date_from\": \"2026-01-01\",
    \"service_id\": 50,
    \"date_min\": \"architecto\",
    \"price\": 299,
    \"bp_id\": 16,
    \"billing_data\": [],
    \"period\": \"month\",
    \"location\": \"architecto\",
    \"note\": \"architecto\",
    \"service_params\": [],
    \"invoice_note\": \"architecto\",
    \"not_use_connect\": 16,
    \"due_days\": \"architecto\",
    \"premise_id\": 16,
    \"add_param\": \"architecto\",
    \"node_id\": 16,
    \"needs_process\": 16,
    \"salesman_id\": 16,
    \"agreement_date\": \"architecto\",
    \"crm_channel\": 16,
    \"base_service_id\": 16,
    \"unicredit_assign\": 16,
    \"autoconnect\": 16,
    \"uc_type\": \"architecto\",
    \"nodeavail_sgd_id\": 16,
    \"name\": \"architecto\",
    \"bp_user_default_change\": 16,
    \"snd_id\": 16,
    \"provider_user_id\": 16
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-services"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "user_id": 100,
    "date_start": "2026-01-01",
    "date_from": "2026-01-01",
    "service_id": 50,
    "date_min": "architecto",
    "price": 299,
    "bp_id": 16,
    "billing_data": [],
    "period": "month",
    "location": "architecto",
    "note": "architecto",
    "service_params": [],
    "invoice_note": "architecto",
    "not_use_connect": 16,
    "due_days": "architecto",
    "premise_id": 16,
    "add_param": "architecto",
    "node_id": 16,
    "needs_process": 16,
    "salesman_id": 16,
    "agreement_date": "architecto",
    "crm_channel": 16,
    "base_service_id": 16,
    "unicredit_assign": 16,
    "autoconnect": 16,
    "uc_type": "architecto",
    "nodeavail_sgd_id": 16,
    "name": "architecto",
    "bp_user_default_change": 16,
    "snd_id": 16,
    "provider_user_id": 16
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "data": {
        "ID": 4591615,
        "USER_ID": "02938",
        "SERVICE_ID": "4027",
        "PRICE": "6356.1332",
        "DATE_START": "1973-04-15",
        "DATE_END": null,
        "STATE": "01",
        "PAYMENT_DEPRECATED": null,
        "ACCOUNT_FROM": "2020-08-07",
        "ACCOUNT_TO": null,
        "DUE_DATE": 30,
        "VAR_SYMBOL": null,
        "ACCORD_NUM": null,
        "TRADING_LIMIT": null,
        "SA_TRADING_LIMIT_ALERTED": 0,
        "CUSTOMER_CHANGE_DEPRECATED": null,
        "SA_PERIOD": "vyear",
        "SA_LOCATION": null,
        "SA_TAX_CLOSURE": null,
        "SA_TAX_PREV_CLOSURE": null,
        "NOTE": "Harum mollitia modi deserunt aut ab provident perspiciatis quo.",
        "SA_INV_NOTE": null,
        "SA_P_ID": null,
        "SA_CANCEL_REASON": null,
        "SA_AGREEMENT_DATE": null,
        "SA_NEEDS_PROCESS": null,
        "SA_CREATED": "2026-04-15 14:55:09",
        "SA_SALESMAN_ID": null,
        "SA_MOVING": 0,
        "SA_MOVE_DATA": null,
        "SA_BOND_START": null,
        "SA_NODEAVAIL_SGD_ID": null,
        "SA_NAME": null,
        "SA_PROVIDER_USER_ID": null,
        "SA_PAY_TO": null,
        "SA_DATE_BASE": null,
        "params": [
            {
                "SP_ID": "0003567106",
                "SP_SRV_ID": 4591615,
                "SP_NAME": "msisdn",
                "SP_VALID_FROM": "1981-11-24",
                "SP_VALID_TO": null,
                "SP_VALUE": "adipisci",
                "SP_CREATED": "2026-03-19 17:08:29",
                "SP_L_ID": "002617"
            }
        ],
        "discounts": [
            {
                "SAD_ID": 309326,
                "SAD_U_ID": 8015,
                "SAD_SA_ID": 4591615,
                "SAD_SD_ID": 50,
                "SAD_DEP_SA_IDS": null,
                "SAD_TYPE": "credit",
                "SAD_VALUE": "19.6504",
                "SAD_START": null,
                "SAD_STOP": null,
                "SAD_CREATED": "2026-03-05 06:52:54",
                "SAD_CREATOR_L_ID": 1839,
                "SAD_STATUS": "WAITING",
                "SAD_POINTS": null,
                "SAD_SD_START_RECREATE": null,
                "SAD_SADG_ID": null,
                "SAD_END_NOTIFIED": null,
                "SAD_STOP_FLOATING": null
            }
        ]
    }
}

Request      

POST api/v3/customer-services

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Body Parameters

user_id   integer     

Customer (user) ID Example: 100

date_start   date     

Service start date Example: 2026-01-01

date_from   date     

Billing start date Example: 2026-01-01

service_id   integer     

Service definition ID (FK to services_name) Example: 50

date_min   date  optional    

Minimum contract date Example: architecto

price   number  optional    

Service price Example: 299

bp_id   integer  optional    

Billing plan ID Example: 16

billing_data   object  optional    

Billing data as key-value pairs

period   string  optional    

Billing period Example: month

location   string  optional    

Service location Example: architecto

note   string  optional    

Note Example: architecto

service_params   object  optional    

Service parameters as key-value pairs

invoice_note   string  optional    

Invoice note Example: architecto

not_use_connect   integer  optional    

Do not use connect Example: 16

due_days   string  optional    

Due days Example: architecto

premise_id   integer  optional    

Premise ID Example: 16

add_param   string  optional    

Additional parameter Example: architecto

node_id   integer  optional    

Device (node) ID Example: 16

needs_process   integer  optional    

Needs processing flag Example: 16

salesman_id   integer  optional    

Salesman ID Example: 16

agreement_date   date  optional    

Agreement date Example: architecto

crm_channel   integer  optional    

CRM channel Example: 16

base_service_id   integer  optional    

Base service ID (for dependent services) Example: 16

unicredit_assign   integer  optional    

UniCredit assign flag Example: 16

autoconnect   integer  optional    

Auto-connect flag Example: 16

uc_type   string  optional    

UniCredit type Example: architecto

nodeavail_sgd_id   integer  optional    

Node availability SGD ID Example: 16

name   string  optional    

Service name override Example: architecto

bp_user_default_change   integer  optional    

Billing plan user default change flag Example: 16

snd_id   integer  optional    

Service name detail ID Example: 16

provider_user_id   integer  optional    

Provider user ID Example: 16

Response

Response Fields

data   object     
ID   integer     

Active service ID (primary key).

USER_ID   integer     

Customer ID. The customer who owns this service. See GET /v3/customers/{id}.

SERVICE_ID   integer     

Service definition ID. The definition this active service is based on. See GET /v3/service-definitions/{id}.

STATE   integer     

Service state. 0 = blocked, 1 = active, 2 = cancelled, 3 = not connected (pending provisioning).

PRICE   number     

Price with VAT for this active service (one-time or per billing period).

DATE_START   string     

Service provision start date (YYYY-MM-DD).

DATE_END   string     

Service provision end date (YYYY-MM-DD). Null if the service is still active (open-ended).

ACCOUNT_FROM   string     

Billing start date (YYYY-MM-DD). Charges begin from this date.

ACCOUNT_TO   string     

Billing end date (YYYY-MM-DD). Null while billing is ongoing.

SA_AGREEMENT_DATE   string     

Agreement (contract) date for this service (YYYY-MM-DD).

SA_PERIOD   string     

Billing period. Possible values: 'month', 'cquarter', 'chalfyear', 'cyear', 'cyears2', 'cyears3', 'cmonths18', 'vmonth', 'vquarter', 'vhalfyear', 'vyear', 'vyears2', 'vyears3', 'vmonths18', 'all', 'none'. Prefix 'c' = calendar-aligned, 'v' = anniversary-aligned.

Must be one of:
  • all
  • chalfyear
  • cquarter
  • cyear
  • month
  • none
  • vhalfyear
  • vmonth
  • vquarter
  • vyear
  • cyears2
  • cyears3
  • cmonths18
  • vyears2
  • vyears3
  • vmonths18
DUE_DATE   integer     

Payment due period in days. Default: 30.

VAR_SYMBOL   integer     

Variable symbol (payment identifier) for this service.

SA_TAX_CLOSURE   string     

Last billing closure date for this service (YYYY-MM-DD).

SA_TAX_PREV_CLOSURE   string     

Previous billing closure date, before the last closure (YYYY-MM-DD).

SA_PAY_TO   string     

Service prepaid expiration date (YYYY-MM-DD). Paid until this date.

SA_DATE_BASE   string     

Base date for anniversary-based billing period calculations (YYYY-MM-DD).

SA_INV_NOTE   string     

Invoice note. Text printed on invoices for this service.

TRADING_LIMIT   string     

Minimum commitment (bond) expiration date (YYYY-MM-DD).

SA_TRADING_LIMIT_ALERTED   integer     

Flag indicating the TRADING_LIMIT has been changed but not yet alerted. 1 = change pending alert.

SA_BOND_START   string     

Minimum commitment (bond) start date (YYYY-MM-DD). Preserved across service transfers.

ACCORD_NUM   string     

Accord number (agreement/contract reference).

SA_LOCATION   string     

Service location identifier (free-text).

SA_P_ID   integer     

Premise ID (point of presence / service delivery location).

SA_MOVING   integer     

Moving flag. 1 = service is in the moving (relocation) processing phase. Relevant when the base service definition has SN_MOVE_SPLITTED = 1.

SA_MOVE_DATA   string     

Additional data for the service move operation.

SA_NEEDS_PROCESS   integer     

Process (maintenance ticket) ID required for provisioning this service.

SA_NODEAVAIL_SGD_ID   integer     

Node availability service group definition ID (process/technology group). See GET /v3/service-groups.

SA_NAME   string     

Commercial (custom) service name. Overrides the default service definition name when set.

SA_SALESMAN_ID   integer     

Salesman (admin/operator) ID who activated or manages this service.

SA_PROVIDER_USER_ID   integer     

Provider (operator) customer ID. See GET /v3/customers/{id}.

SA_CANCEL_REASON   integer     

Cancellation reason code (code list entry ID).

NOTE   string     

Note / remark for this service.

SA_CREATED   string     

Timestamp when this service was activated/created.

PAYMENT_DEPRECATED   string     

Deprecated payment field. No longer in active use.

CUSTOMER_CHANGE_DEPRECATED   integer     

Deprecated customer change flag. No longer in active use.

params   object[]     

Service parameter key-value pairs.
SP_ID   integer     

Service parameter ID (primary key).

SP_SRV_ID   integer     

Parent active service ID. See GET /v3/customer-services/{id}.

SP_NAME   string     

Parameter name (key), e.g. "msisdn", "sip_phone_number", "agr_max_down_speed".

SP_VALUE   string     

Parameter value. Stored as text; actual data type depends on the parameter definition.

SP_VALID_FROM   string     

Validity start date (YYYY-MM-DD).

SP_VALID_TO   string     

Validity end date (YYYY-MM-DD). Null means open-ended (no expiry).

SP_CREATED   string     

Timestamp when this parameter was created (YYYY-MM-DD HH:MM:SS).

SP_L_ID   integer     

Operator (login session) ID that created this parameter.

discounts   object[]     

Active discounts applied to this service.
SAD_ID   integer     

Active discount ID (primary key).

SAD_U_ID   integer     

Customer ID. See GET /v3/customers/{id}.

SAD_SA_ID   integer     

Active service ID. See GET /v3/customer-services/{id}.

SAD_SD_ID   integer     

Discount definition ID (a ServiceDiscount record — not directly exposed via API).

SAD_DEP_SA_IDS   string     

Comma-separated list of dependent active service IDs linked to this discount.

SAD_TYPE   string     

Discount type. Determines how SAD_VALUE is interpreted.

Must be one of:
  • percentage
  • definite
  • credit
  • points
SAD_VALUE   number     

Discount value. Interpretation depends on SAD_TYPE: percentage = % off, definite = fixed currency amount, credit = credit amount, points = point value.

SAD_START   string     

Discount validity start date (YYYY-MM-DD). If null, defaults to the service billing start.

SAD_STOP   string     

Discount validity end date (YYYY-MM-DD). If null, the discount runs until the service billing end.

SAD_CREATED   string     

Timestamp when this discount was created (YYYY-MM-DD HH:MM:SS).

SAD_CREATOR_L_ID   integer     

Operator (login session) ID that created this discount.

SAD_STATUS   string     

Current status of the discount.

Must be one of:
  • ACTIVE
  • WAITING
  • FINISHED
SAD_POINTS   integer     

Loyalty/bonus points associated with this discount.

SAD_SD_START_RECREATE   integer     

Flag indicating the discount should be recreated on group discount start. 1 = recreate on start.

SAD_SADG_ID   integer     

Discount group ID (groups related discounts together).

SAD_END_NOTIFIED   string     

Timestamp when the discount end notification was sent (YYYY-MM-DD HH:MM:SS).

SAD_STOP_FLOATING   string     

Floating (relative) end date for the discount (YYYY-MM-DD). Used when the discount duration is relative rather than fixed.

dependent_services   object[]     

Dependent (linked) services. Only included in single-resource (show) responses.
SAL_ID   integer     

Service linkage ID (primary key).

SAL_TYPE   string     

Linkage type.

Must be one of:
  • motivation1
  • dependency
  • together
  • fixed
  • dependency_free
SAL_SA_ID   integer     

Parent active service ID. See GET /v3/customer-services/{id}.

SAL_LINKED_SA_ID   integer     

Linked (dependent) active service ID. See GET /v3/customer-services/{id}.

SAL_VALID_FROM   string     

Linkage validity start date (YYYY-MM-DD).

SAL_VALID_TO   string     

Linkage validity end date (YYYY-MM-DD).

SAL_SAD_ID   integer     

Associated discount ID (a ServiceActiveDiscount record).

SAL_CREATED   string     

Timestamp when this linkage was created (YYYY-MM-DD HH:MM:SS).

SAL_CREATOR_ID   integer     

Operator (login session) ID that created this linkage.

Get Customer Service

requires authentication

Returns a single customer service by ID.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-services/105" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-services/105"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "ID": 4591616,
        "USER_ID": "02878",
        "SERVICE_ID": "2839",
        "PRICE": "3668.8918",
        "DATE_START": "2015-01-19",
        "DATE_END": null,
        "STATE": "01",
        "PAYMENT_DEPRECATED": null,
        "ACCOUNT_FROM": "2022-12-14",
        "ACCOUNT_TO": null,
        "DUE_DATE": 30,
        "VAR_SYMBOL": null,
        "ACCORD_NUM": null,
        "TRADING_LIMIT": null,
        "SA_TRADING_LIMIT_ALERTED": 0,
        "CUSTOMER_CHANGE_DEPRECATED": null,
        "SA_PERIOD": "cyear",
        "SA_LOCATION": null,
        "SA_TAX_CLOSURE": null,
        "SA_TAX_PREV_CLOSURE": null,
        "NOTE": null,
        "SA_INV_NOTE": null,
        "SA_P_ID": null,
        "SA_CANCEL_REASON": null,
        "SA_AGREEMENT_DATE": null,
        "SA_NEEDS_PROCESS": null,
        "SA_CREATED": "2026-04-15 14:55:09",
        "SA_SALESMAN_ID": null,
        "SA_MOVING": 0,
        "SA_MOVE_DATA": null,
        "SA_BOND_START": null,
        "SA_NODEAVAIL_SGD_ID": null,
        "SA_NAME": null,
        "SA_PROVIDER_USER_ID": null,
        "SA_PAY_TO": null,
        "SA_DATE_BASE": null,
        "params": [
            {
                "SP_ID": "0003567107",
                "SP_SRV_ID": 4591616,
                "SP_NAME": "msisdn",
                "SP_VALID_FROM": "1973-12-17",
                "SP_VALID_TO": null,
                "SP_VALUE": "ipsum",
                "SP_CREATED": "2026-02-24 13:31:05",
                "SP_L_ID": "007018"
            }
        ],
        "discounts": [
            {
                "SAD_ID": 309327,
                "SAD_U_ID": 4486,
                "SAD_SA_ID": 4591616,
                "SAD_SD_ID": 50,
                "SAD_DEP_SA_IDS": null,
                "SAD_TYPE": "points",
                "SAD_VALUE": "72.9772",
                "SAD_START": "1997-06-20",
                "SAD_STOP": null,
                "SAD_CREATED": "2026-02-23 08:05:41",
                "SAD_CREATOR_L_ID": 2327,
                "SAD_STATUS": "FINISHED",
                "SAD_POINTS": null,
                "SAD_SD_START_RECREATE": null,
                "SAD_SADG_ID": null,
                "SAD_END_NOTIFIED": null,
                "SAD_STOP_FLOATING": null
            }
        ],
        "dependent_services": [
            {
                "SAL_ID": "00000197980",
                "SAL_TYPE": "fixed",
                "SAL_SA_ID": 4591616,
                "SAL_LINKED_SA_ID": 7048,
                "SAL_VALID_FROM": null,
                "SAL_VALID_TO": null,
                "SAL_SAD_ID": null,
                "SAL_CREATED": "2026-01-11 18:42:26",
                "SAL_CREATOR_ID": "007602"
            }
        ]
    }
}

Request      

GET api/v3/customer-services/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the customer service. Example: 105

Response

Response Fields

data   object     
ID   integer     

Active service ID (primary key).

USER_ID   integer     

Customer ID. The customer who owns this service. See GET /v3/customers/{id}.

SERVICE_ID   integer     

Service definition ID. The definition this active service is based on. See GET /v3/service-definitions/{id}.

STATE   integer     

Service state. 0 = blocked, 1 = active, 2 = cancelled, 3 = not connected (pending provisioning).

PRICE   number     

Price with VAT for this active service (one-time or per billing period).

DATE_START   string     

Service provision start date (YYYY-MM-DD).

DATE_END   string     

Service provision end date (YYYY-MM-DD). Null if the service is still active (open-ended).

ACCOUNT_FROM   string     

Billing start date (YYYY-MM-DD). Charges begin from this date.

ACCOUNT_TO   string     

Billing end date (YYYY-MM-DD). Null while billing is ongoing.

SA_AGREEMENT_DATE   string     

Agreement (contract) date for this service (YYYY-MM-DD).

SA_PERIOD   string     

Billing period. Possible values: 'month', 'cquarter', 'chalfyear', 'cyear', 'cyears2', 'cyears3', 'cmonths18', 'vmonth', 'vquarter', 'vhalfyear', 'vyear', 'vyears2', 'vyears3', 'vmonths18', 'all', 'none'. Prefix 'c' = calendar-aligned, 'v' = anniversary-aligned.

Must be one of:
  • all
  • chalfyear
  • cquarter
  • cyear
  • month
  • none
  • vhalfyear
  • vmonth
  • vquarter
  • vyear
  • cyears2
  • cyears3
  • cmonths18
  • vyears2
  • vyears3
  • vmonths18
DUE_DATE   integer     

Payment due period in days. Default: 30.

VAR_SYMBOL   integer     

Variable symbol (payment identifier) for this service.

SA_TAX_CLOSURE   string     

Last billing closure date for this service (YYYY-MM-DD).

SA_TAX_PREV_CLOSURE   string     

Previous billing closure date, before the last closure (YYYY-MM-DD).

SA_PAY_TO   string     

Service prepaid expiration date (YYYY-MM-DD). Paid until this date.

SA_DATE_BASE   string     

Base date for anniversary-based billing period calculations (YYYY-MM-DD).

SA_INV_NOTE   string     

Invoice note. Text printed on invoices for this service.

TRADING_LIMIT   string     

Minimum commitment (bond) expiration date (YYYY-MM-DD).

SA_TRADING_LIMIT_ALERTED   integer     

Flag indicating the TRADING_LIMIT has been changed but not yet alerted. 1 = change pending alert.

SA_BOND_START   string     

Minimum commitment (bond) start date (YYYY-MM-DD). Preserved across service transfers.

ACCORD_NUM   string     

Accord number (agreement/contract reference).

SA_LOCATION   string     

Service location identifier (free-text).

SA_P_ID   integer     

Premise ID (point of presence / service delivery location).

SA_MOVING   integer     

Moving flag. 1 = service is in the moving (relocation) processing phase. Relevant when the base service definition has SN_MOVE_SPLITTED = 1.

SA_MOVE_DATA   string     

Additional data for the service move operation.

SA_NEEDS_PROCESS   integer     

Process (maintenance ticket) ID required for provisioning this service.

SA_NODEAVAIL_SGD_ID   integer     

Node availability service group definition ID (process/technology group). See GET /v3/service-groups.

SA_NAME   string     

Commercial (custom) service name. Overrides the default service definition name when set.

SA_SALESMAN_ID   integer     

Salesman (admin/operator) ID who activated or manages this service.

SA_PROVIDER_USER_ID   integer     

Provider (operator) customer ID. See GET /v3/customers/{id}.

SA_CANCEL_REASON   integer     

Cancellation reason code (code list entry ID).

NOTE   string     

Note / remark for this service.

SA_CREATED   string     

Timestamp when this service was activated/created.

PAYMENT_DEPRECATED   string     

Deprecated payment field. No longer in active use.

CUSTOMER_CHANGE_DEPRECATED   integer     

Deprecated customer change flag. No longer in active use.

params   object[]     

Service parameter key-value pairs.
SP_ID   integer     

Service parameter ID (primary key).

SP_SRV_ID   integer     

Parent active service ID. See GET /v3/customer-services/{id}.

SP_NAME   string     

Parameter name (key), e.g. "msisdn", "sip_phone_number", "agr_max_down_speed".

SP_VALUE   string     

Parameter value. Stored as text; actual data type depends on the parameter definition.

SP_VALID_FROM   string     

Validity start date (YYYY-MM-DD).

SP_VALID_TO   string     

Validity end date (YYYY-MM-DD). Null means open-ended (no expiry).

SP_CREATED   string     

Timestamp when this parameter was created (YYYY-MM-DD HH:MM:SS).

SP_L_ID   integer     

Operator (login session) ID that created this parameter.

discounts   object[]     

Active discounts applied to this service.
SAD_ID   integer     

Active discount ID (primary key).

SAD_U_ID   integer     

Customer ID. See GET /v3/customers/{id}.

SAD_SA_ID   integer     

Active service ID. See GET /v3/customer-services/{id}.

SAD_SD_ID   integer     

Discount definition ID (a ServiceDiscount record — not directly exposed via API).

SAD_DEP_SA_IDS   string     

Comma-separated list of dependent active service IDs linked to this discount.

SAD_TYPE   string     

Discount type. Determines how SAD_VALUE is interpreted.

Must be one of:
  • percentage
  • definite
  • credit
  • points
SAD_VALUE   number     

Discount value. Interpretation depends on SAD_TYPE: percentage = % off, definite = fixed currency amount, credit = credit amount, points = point value.

SAD_START   string     

Discount validity start date (YYYY-MM-DD). If null, defaults to the service billing start.

SAD_STOP   string     

Discount validity end date (YYYY-MM-DD). If null, the discount runs until the service billing end.

SAD_CREATED   string     

Timestamp when this discount was created (YYYY-MM-DD HH:MM:SS).

SAD_CREATOR_L_ID   integer     

Operator (login session) ID that created this discount.

SAD_STATUS   string     

Current status of the discount.

Must be one of:
  • ACTIVE
  • WAITING
  • FINISHED
SAD_POINTS   integer     

Loyalty/bonus points associated with this discount.

SAD_SD_START_RECREATE   integer     

Flag indicating the discount should be recreated on group discount start. 1 = recreate on start.

SAD_SADG_ID   integer     

Discount group ID (groups related discounts together).

SAD_END_NOTIFIED   string     

Timestamp when the discount end notification was sent (YYYY-MM-DD HH:MM:SS).

SAD_STOP_FLOATING   string     

Floating (relative) end date for the discount (YYYY-MM-DD). Used when the discount duration is relative rather than fixed.

dependent_services   object[]     

Dependent (linked) services. Only included in single-resource (show) responses.
SAL_ID   integer     

Service linkage ID (primary key).

SAL_TYPE   string     

Linkage type.

Must be one of:
  • motivation1
  • dependency
  • together
  • fixed
  • dependency_free
SAL_SA_ID   integer     

Parent active service ID. See GET /v3/customer-services/{id}.

SAL_LINKED_SA_ID   integer     

Linked (dependent) active service ID. See GET /v3/customer-services/{id}.

SAL_VALID_FROM   string     

Linkage validity start date (YYYY-MM-DD).

SAL_VALID_TO   string     

Linkage validity end date (YYYY-MM-DD).

SAL_SAD_ID   integer     

Associated discount ID (a ServiceActiveDiscount record).

SAL_CREATED   string     

Timestamp when this linkage was created (YYYY-MM-DD HH:MM:SS).

SAL_CREATOR_ID   integer     

Operator (login session) ID that created this linkage.

Change Customer Service

requires authentication

Changes (edits) an existing customer service via services_active_change.

Example request:
curl --request PUT \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-services/105" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"date\": \"2026-01-01\",
    \"price\": 399,
    \"bp_id\": 16,
    \"billing_data\": [],
    \"period\": \"month\",
    \"note\": \"architecto\",
    \"service_params\": [],
    \"date_min\": \"architecto\",
    \"nodeavail_sgd_id\": 16,
    \"salesman_id\": 16,
    \"name\": \"architecto\",
    \"bp_user_default_change\": 16,
    \"period_dep\": 16
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-services/105"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "date": "2026-01-01",
    "price": 399,
    "bp_id": 16,
    "billing_data": [],
    "period": "month",
    "note": "architecto",
    "service_params": [],
    "date_min": "architecto",
    "nodeavail_sgd_id": 16,
    "salesman_id": 16,
    "name": "architecto",
    "bp_user_default_change": 16,
    "period_dep": 16
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "data": {
        "ID": 4591617,
        "USER_ID": "02938",
        "SERVICE_ID": "4027",
        "PRICE": "6356.1332",
        "DATE_START": "1973-04-15",
        "DATE_END": null,
        "STATE": "01",
        "PAYMENT_DEPRECATED": null,
        "ACCOUNT_FROM": "2020-08-07",
        "ACCOUNT_TO": null,
        "DUE_DATE": 30,
        "VAR_SYMBOL": null,
        "ACCORD_NUM": null,
        "TRADING_LIMIT": null,
        "SA_TRADING_LIMIT_ALERTED": 0,
        "CUSTOMER_CHANGE_DEPRECATED": null,
        "SA_PERIOD": "vyear",
        "SA_LOCATION": null,
        "SA_TAX_CLOSURE": null,
        "SA_TAX_PREV_CLOSURE": null,
        "NOTE": "Harum mollitia modi deserunt aut ab provident perspiciatis quo.",
        "SA_INV_NOTE": null,
        "SA_P_ID": null,
        "SA_CANCEL_REASON": null,
        "SA_AGREEMENT_DATE": null,
        "SA_NEEDS_PROCESS": null,
        "SA_CREATED": "2026-04-15 14:55:09",
        "SA_SALESMAN_ID": null,
        "SA_MOVING": 0,
        "SA_MOVE_DATA": null,
        "SA_BOND_START": null,
        "SA_NODEAVAIL_SGD_ID": null,
        "SA_NAME": null,
        "SA_PROVIDER_USER_ID": null,
        "SA_PAY_TO": null,
        "SA_DATE_BASE": null,
        "params": [
            {
                "SP_ID": "0003567108",
                "SP_SRV_ID": 4591617,
                "SP_NAME": "msisdn",
                "SP_VALID_FROM": "1981-11-24",
                "SP_VALID_TO": null,
                "SP_VALUE": "adipisci",
                "SP_CREATED": "2026-03-19 17:08:29",
                "SP_L_ID": "002617"
            }
        ],
        "discounts": [
            {
                "SAD_ID": 309328,
                "SAD_U_ID": 8015,
                "SAD_SA_ID": 4591617,
                "SAD_SD_ID": 50,
                "SAD_DEP_SA_IDS": null,
                "SAD_TYPE": "credit",
                "SAD_VALUE": "19.6504",
                "SAD_START": null,
                "SAD_STOP": null,
                "SAD_CREATED": "2026-03-05 06:52:54",
                "SAD_CREATOR_L_ID": 1839,
                "SAD_STATUS": "WAITING",
                "SAD_POINTS": null,
                "SAD_SD_START_RECREATE": null,
                "SAD_SADG_ID": null,
                "SAD_END_NOTIFIED": null,
                "SAD_STOP_FLOATING": null
            }
        ]
    }
}

Request      

PUT api/v3/customer-services/{id}

PATCH api/v3/customer-services/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the customer service. Example: 105

Body Parameters

date   date  optional    

Change effective date Example: 2026-01-01

price   number  optional    

New price Example: 399

bp_id   integer  optional    

Billing plan ID Example: 16

billing_data   object  optional    

Billing data as key-value pairs

period   string  optional    

Billing period Example: month

note   string  optional    

Note Example: architecto

service_params   object  optional    

Service parameters as key-value pairs

date_min   date  optional    

Minimum contract date Example: architecto

nodeavail_sgd_id   integer  optional    

Node availability SGD ID Example: 16

salesman_id   integer  optional    

Salesman ID Example: 16

name   string  optional    

Service name override Example: architecto

bp_user_default_change   integer  optional    

Billing plan user default change flag Example: 16

period_dep   integer  optional    

Period dependency flag Example: 16

Response

Response Fields

data   object     
ID   integer     

Active service ID (primary key).

USER_ID   integer     

Customer ID. The customer who owns this service. See GET /v3/customers/{id}.

SERVICE_ID   integer     

Service definition ID. The definition this active service is based on. See GET /v3/service-definitions/{id}.

STATE   integer     

Service state. 0 = blocked, 1 = active, 2 = cancelled, 3 = not connected (pending provisioning).

PRICE   number     

Price with VAT for this active service (one-time or per billing period).

DATE_START   string     

Service provision start date (YYYY-MM-DD).

DATE_END   string     

Service provision end date (YYYY-MM-DD). Null if the service is still active (open-ended).

ACCOUNT_FROM   string     

Billing start date (YYYY-MM-DD). Charges begin from this date.

ACCOUNT_TO   string     

Billing end date (YYYY-MM-DD). Null while billing is ongoing.

SA_AGREEMENT_DATE   string     

Agreement (contract) date for this service (YYYY-MM-DD).

SA_PERIOD   string     

Billing period. Possible values: 'month', 'cquarter', 'chalfyear', 'cyear', 'cyears2', 'cyears3', 'cmonths18', 'vmonth', 'vquarter', 'vhalfyear', 'vyear', 'vyears2', 'vyears3', 'vmonths18', 'all', 'none'. Prefix 'c' = calendar-aligned, 'v' = anniversary-aligned.

Must be one of:
  • all
  • chalfyear
  • cquarter
  • cyear
  • month
  • none
  • vhalfyear
  • vmonth
  • vquarter
  • vyear
  • cyears2
  • cyears3
  • cmonths18
  • vyears2
  • vyears3
  • vmonths18
DUE_DATE   integer     

Payment due period in days. Default: 30.

VAR_SYMBOL   integer     

Variable symbol (payment identifier) for this service.

SA_TAX_CLOSURE   string     

Last billing closure date for this service (YYYY-MM-DD).

SA_TAX_PREV_CLOSURE   string     

Previous billing closure date, before the last closure (YYYY-MM-DD).

SA_PAY_TO   string     

Service prepaid expiration date (YYYY-MM-DD). Paid until this date.

SA_DATE_BASE   string     

Base date for anniversary-based billing period calculations (YYYY-MM-DD).

SA_INV_NOTE   string     

Invoice note. Text printed on invoices for this service.

TRADING_LIMIT   string     

Minimum commitment (bond) expiration date (YYYY-MM-DD).

SA_TRADING_LIMIT_ALERTED   integer     

Flag indicating the TRADING_LIMIT has been changed but not yet alerted. 1 = change pending alert.

SA_BOND_START   string     

Minimum commitment (bond) start date (YYYY-MM-DD). Preserved across service transfers.

ACCORD_NUM   string     

Accord number (agreement/contract reference).

SA_LOCATION   string     

Service location identifier (free-text).

SA_P_ID   integer     

Premise ID (point of presence / service delivery location).

SA_MOVING   integer     

Moving flag. 1 = service is in the moving (relocation) processing phase. Relevant when the base service definition has SN_MOVE_SPLITTED = 1.

SA_MOVE_DATA   string     

Additional data for the service move operation.

SA_NEEDS_PROCESS   integer     

Process (maintenance ticket) ID required for provisioning this service.

SA_NODEAVAIL_SGD_ID   integer     

Node availability service group definition ID (process/technology group). See GET /v3/service-groups.

SA_NAME   string     

Commercial (custom) service name. Overrides the default service definition name when set.

SA_SALESMAN_ID   integer     

Salesman (admin/operator) ID who activated or manages this service.

SA_PROVIDER_USER_ID   integer     

Provider (operator) customer ID. See GET /v3/customers/{id}.

SA_CANCEL_REASON   integer     

Cancellation reason code (code list entry ID).

NOTE   string     

Note / remark for this service.

SA_CREATED   string     

Timestamp when this service was activated/created.

PAYMENT_DEPRECATED   string     

Deprecated payment field. No longer in active use.

CUSTOMER_CHANGE_DEPRECATED   integer     

Deprecated customer change flag. No longer in active use.

params   object[]     

Service parameter key-value pairs.
SP_ID   integer     

Service parameter ID (primary key).

SP_SRV_ID   integer     

Parent active service ID. See GET /v3/customer-services/{id}.

SP_NAME   string     

Parameter name (key), e.g. "msisdn", "sip_phone_number", "agr_max_down_speed".

SP_VALUE   string     

Parameter value. Stored as text; actual data type depends on the parameter definition.

SP_VALID_FROM   string     

Validity start date (YYYY-MM-DD).

SP_VALID_TO   string     

Validity end date (YYYY-MM-DD). Null means open-ended (no expiry).

SP_CREATED   string     

Timestamp when this parameter was created (YYYY-MM-DD HH:MM:SS).

SP_L_ID   integer     

Operator (login session) ID that created this parameter.

discounts   object[]     

Active discounts applied to this service.
SAD_ID   integer     

Active discount ID (primary key).

SAD_U_ID   integer     

Customer ID. See GET /v3/customers/{id}.

SAD_SA_ID   integer     

Active service ID. See GET /v3/customer-services/{id}.

SAD_SD_ID   integer     

Discount definition ID (a ServiceDiscount record — not directly exposed via API).

SAD_DEP_SA_IDS   string     

Comma-separated list of dependent active service IDs linked to this discount.

SAD_TYPE   string     

Discount type. Determines how SAD_VALUE is interpreted.

Must be one of:
  • percentage
  • definite
  • credit
  • points
SAD_VALUE   number     

Discount value. Interpretation depends on SAD_TYPE: percentage = % off, definite = fixed currency amount, credit = credit amount, points = point value.

SAD_START   string     

Discount validity start date (YYYY-MM-DD). If null, defaults to the service billing start.

SAD_STOP   string     

Discount validity end date (YYYY-MM-DD). If null, the discount runs until the service billing end.

SAD_CREATED   string     

Timestamp when this discount was created (YYYY-MM-DD HH:MM:SS).

SAD_CREATOR_L_ID   integer     

Operator (login session) ID that created this discount.

SAD_STATUS   string     

Current status of the discount.

Must be one of:
  • ACTIVE
  • WAITING
  • FINISHED
SAD_POINTS   integer     

Loyalty/bonus points associated with this discount.

SAD_SD_START_RECREATE   integer     

Flag indicating the discount should be recreated on group discount start. 1 = recreate on start.

SAD_SADG_ID   integer     

Discount group ID (groups related discounts together).

SAD_END_NOTIFIED   string     

Timestamp when the discount end notification was sent (YYYY-MM-DD HH:MM:SS).

SAD_STOP_FLOATING   string     

Floating (relative) end date for the discount (YYYY-MM-DD). Used when the discount duration is relative rather than fixed.

dependent_services   object[]     

Dependent (linked) services. Only included in single-resource (show) responses.
SAL_ID   integer     

Service linkage ID (primary key).

SAL_TYPE   string     

Linkage type.

Must be one of:
  • motivation1
  • dependency
  • together
  • fixed
  • dependency_free
SAL_SA_ID   integer     

Parent active service ID. See GET /v3/customer-services/{id}.

SAL_LINKED_SA_ID   integer     

Linked (dependent) active service ID. See GET /v3/customer-services/{id}.

SAL_VALID_FROM   string     

Linkage validity start date (YYYY-MM-DD).

SAL_VALID_TO   string     

Linkage validity end date (YYYY-MM-DD).

SAL_SAD_ID   integer     

Associated discount ID (a ServiceActiveDiscount record).

SAL_CREATED   string     

Timestamp when this linkage was created (YYYY-MM-DD HH:MM:SS).

SAL_CREATOR_ID   integer     

Operator (login session) ID that created this linkage.

Cancel Customer Service

requires authentication

Cancels (deactivates) a customer service. This is a soft cancel, not a hard delete.

Example request:
curl --request DELETE \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-services/105" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-services/105"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

Example response (204):

Empty response

Request      

DELETE api/v3/customer-services/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the customer service. Example: 105

Block Customer Service

requires authentication

Blocks an active customer service.

Example request:
curl --request POST \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-services/105/block" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"date\": \"2026-01-01\",
    \"note\": \"architecto\",
    \"interrupt\": 16,
    \"blocked_billing\": 16,
    \"blocked_auto\": 16,
    \"credit_create\": 16
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-services/105/block"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "date": "2026-01-01",
    "note": "architecto",
    "interrupt": 16,
    "blocked_billing": 16,
    "blocked_auto": 16,
    "credit_create": 16
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (204):

Empty response

Request      

POST api/v3/customer-services/{id}/block

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the customer service. Example: 105

Body Parameters

date   date     

Block effective date Example: 2026-01-01

note   string  optional    

Note Example: architecto

interrupt   integer  optional    

Interrupt flag Example: 16

blocked_billing   integer  optional    

Block billing flag Example: 16

blocked_auto   integer  optional    

Auto-block flag Example: 16

credit_create   integer  optional    

Create credit flag Example: 16

Unblock Customer Service

requires authentication

Unblocks a blocked customer service.

Example request:
curl --request POST \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-services/105/unblock" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"date\": \"architecto\",
    \"note\": \"architecto\",
    \"interrupt\": 16,
    \"blocked_billing\": 16,
    \"sn_id_list\": [
        16
    ],
    \"blocked_auto\": 16,
    \"create_credit\": 16
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-services/105/unblock"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "date": "architecto",
    "note": "architecto",
    "interrupt": 16,
    "blocked_billing": 16,
    "sn_id_list": [
        16
    ],
    "blocked_auto": 16,
    "create_credit": 16
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (204):

Empty response

Request      

POST api/v3/customer-services/{id}/unblock

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the customer service. Example: 105

Body Parameters

date   date  optional    

Unblock effective date Example: architecto

note   string  optional    

Note Example: architecto

interrupt   integer  optional    

Interrupt flag Example: 16

blocked_billing   integer  optional    

Blocked billing flag Example: 16

sn_id_list   integer[]  optional    

List of service name IDs to unblock

blocked_auto   integer  optional    

Auto-blocked flag Example: 16

create_credit   integer  optional    

Create credit flag Example: 16

Customer Units

List Customer Units

requires authentication

Retrieve a paginated list of customer units (residential/business premises). Customer units are connection points in the network where customer services are delivered.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-units?per_page=10&page=1&ids=1%2C2%2C3&cts=1%2C2%2C3&customer=100&customer_service=500&unit_city=1234&unit_citypart=5678&unit_street=9012&unit_address=3456&region=10" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-units"
);

const params = {
    "per_page": "10",
    "page": "1",
    "ids": "1,2,3",
    "cts": "1,2,3",
    "customer": "100",
    "customer_service": "500",
    "unit_city": "1234",
    "unit_citypart": "5678",
    "unit_street": "9012",
    "unit_address": "3456",
    "region": "10",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "ID": 1792676,
            "NAME": "UNIT-uwpwlv",
            "NOTE": "Odit et et modi.",
            "MANAGED": 0,
            "MANAG_IP": null,
            "PARENT_NODE": null,
            "F_TYPE": null,
            "N_TYPE": "BLK_DEVICE",
            "N_DEVICE_TYPE": "blk_device",
            "N_CUSTOMER": 1,
            "USER_SERVICE_ID": 0,
            "CUSTOMER_PARENT": 1,
            "CUSTOMER_TYPE": null,
            "CUSTOMER_LOCATION": 0,
            "MAC": null,
            "UPDATE_FLAG": 0,
            "AGR_GROUP": null,
            "STREET": null,
            "HOUSE_ID": null,
            "N_ZIP": null,
            "N_CITY": null,
            "SOCKET": null,
            "N_COUNTER_ID": 0,
            "N_PRODUCER": null,
            "N_SERIAL_NUM": null,
            "N_LAST_RESPONSE": null,
            "N_CT": 76,
            "N_CREATED": null,
            "N_L_ID": 568,
            "N_GPS_LATITUDE": null,
            "N_GPS_LONGITUDE": null,
            "N_UCP_ID": null,
            "N_US_ID": null,
            "N_UA_ID": null,
            "N_CACHE_NAME": "omnis",
            "N_CACHE_LAST_WS_ID": null,
            "N_DELETED": null,
            "params": [
                {
                    "ID": 301268718,
                    "NODE_ID": 1792676,
                    "NI_NPI_ID": 0,
                    "PAR_NAME": "blkdevice_flat_number",
                    "PAR_INDEX": 0,
                    "VALUE": null,
                    "CONTENT": null,
                    "TEXT_CONTENT": null
                }
            ],
            "customer_service_devices": [
                {
                    "NS_ID": 2148176,
                    "NS_N_ID": 1792676,
                    "NS_U_ID": 1038,
                    "NS_SA_ID": null,
                    "NS_TIME": "2026-03-24 18:46:05",
                    "NS_L_ID": 1,
                    "NS_NEEDS_UPDATE": 0
                }
            ]
        },
        {
            "ID": 1792677,
            "NAME": "UNIT-snrwtu",
            "NOTE": "Quis adipisci molestias fugit deleniti distinctio eum.",
            "MANAGED": 0,
            "MANAG_IP": null,
            "PARENT_NODE": null,
            "F_TYPE": null,
            "N_TYPE": "BLK_DEVICE",
            "N_DEVICE_TYPE": "blk_device",
            "N_CUSTOMER": 1,
            "USER_SERVICE_ID": 0,
            "CUSTOMER_PARENT": 1,
            "CUSTOMER_TYPE": null,
            "CUSTOMER_LOCATION": 0,
            "MAC": null,
            "UPDATE_FLAG": 0,
            "AGR_GROUP": null,
            "STREET": null,
            "HOUSE_ID": null,
            "N_ZIP": null,
            "N_CITY": null,
            "SOCKET": null,
            "N_COUNTER_ID": 0,
            "N_PRODUCER": null,
            "N_SERIAL_NUM": null,
            "N_LAST_RESPONSE": null,
            "N_CT": 74,
            "N_CREATED": null,
            "N_L_ID": 535,
            "N_GPS_LATITUDE": null,
            "N_GPS_LONGITUDE": null,
            "N_UCP_ID": null,
            "N_US_ID": null,
            "N_UA_ID": null,
            "N_CACHE_NAME": "aut",
            "N_CACHE_LAST_WS_ID": null,
            "N_DELETED": null,
            "params": [
                {
                    "ID": 301268719,
                    "NODE_ID": 1792677,
                    "NI_NPI_ID": 0,
                    "PAR_NAME": "blkdevice_connection_type",
                    "PAR_INDEX": 0,
                    "VALUE": null,
                    "CONTENT": null,
                    "TEXT_CONTENT": null
                }
            ],
            "customer_service_devices": [
                {
                    "NS_ID": 2148177,
                    "NS_N_ID": 1792677,
                    "NS_U_ID": 1038,
                    "NS_SA_ID": null,
                    "NS_TIME": "2026-01-15 01:05:56",
                    "NS_L_ID": 1,
                    "NS_NEEDS_UPDATE": 0
                }
            ]
        }
    ]
}

Request      

GET api/v3/customer-units

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of items per page. Example: 10

page   integer  optional    

Page number. Example: 1

ids   string  optional    

Filter by comma-separated customer unit IDs. Example: 1,2,3

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Example: 1,2,3

customer   integer  optional    

Filter by customer ID — returns units linked to this customer via nodes_services. Example: 100

customer_service   integer  optional    

Filter by customer service ID — returns units linked to this service via nodes_services. Example: 500

unit_city   integer  optional    

Filter by UIR city ID (via uir_city_parts registry). Example: 1234

unit_citypart   integer  optional    

Filter by UIR city part ID (N_UCP_ID). Example: 5678

unit_street   integer  optional    

Filter by UIR street ID (N_US_ID). Example: 9012

unit_address   integer  optional    

Filter by UIR address ID (N_UA_ID). Example: 3456

region   integer  optional    

Filter by address region group ID (groups_address). Matches units whose UIR address falls within the region. Example: 10

Response

Response Fields

data   object     
ID   integer     

Unique customer unit identifier (primary key).

NAME   string     

Unit name (up to 30 characters).

NOTE   string     

Free-text note.

N_TYPE   string     

Node type. Always 'BLK_DEVICE' for customer units.

N_DEVICE_TYPE   string     

Specific unit/device type identifier (references nodes_device_types).

F_TYPE   string     

Functional type. Possible values: AP, BRIDGE, IP, OLT, ONU, ROUTER, SIP, SWITCH.

N_CUSTOMER   integer     

Customer device flag. Always 1 for customer units.

CUSTOMER_PARENT   integer     

Flag indicating this unit can host child devices (CPE). 1 = open for customer connections.

CUSTOMER_TYPE   string     

Customer device sub-type classification.

MANAGED   integer     

Flag indicating the unit is managed (configured) by the Mango system. 1 = managed.

MANAG_IP   string     

Management IP address.

UPDATE_FLAG   integer     

Flag indicating configuration needs to be pushed/updated. 1 = update pending.

MAC   string     

MAC address.

N_LAST_RESPONSE   string     

Datetime of the last successful SNMP monitoring response.

PARENT_NODE   integer     

ID of the parent device in the network topology.

USER_SERVICE_ID   integer     

ID of the associated customer service.

N_CT   integer     

Location / installation (CT) identifier.

STREET   string     

Street name of the unit location.

HOUSE_ID   string     

House number (cislo popisne).

N_ZIP   string     

ZIP / postal code (up to 5 characters).

N_CITY   string     

City of the unit location.

SOCKET   string     

Apartment/socket identifier at the address.

N_GPS_LATITUDE   number     

GPS latitude.

N_GPS_LONGITUDE   number     

GPS longitude.

N_UCP_ID   integer     

UIR registry city part ID.

N_US_ID   integer     

UIR registry street ID.

N_UA_ID   integer     

UIR registry address ID (RUIAN code).

N_PRODUCER   string     

Device manufacturer / producer.

N_SERIAL_NUM   string     

Serial number.

N_CREATED   string     

Datetime when the unit record was created.

N_L_ID   integer     

ID of the operator (login) who last modified this unit.

N_CACHE_NAME   string     

Cached display name combining class, type and unit name.

N_CACHE_LAST_WS_ID   integer     

Cached ID of the last work session that touched this unit.

CUSTOMER_LOCATION   integer     

Deprecated. Former customer location reference (now via nodes_cust_locations).

AGR_GROUP   integer     

Deprecated. Former aggregation group reference.

N_COUNTER_ID   integer     

Deprecated. Former counter ID (now stored as a unit parameter).

normalized_address   string     

Full normalized address from the UIR/RUIAN registry (based on N_UA_ID). Null when N_UA_ID is not set.

params   object[]     

Unit parameters — collection of key-value pairs from the node_info table.
ID   integer     

Unique parameter record identifier.

NODE_ID   integer     

ID of the parent customer unit.

NI_NPI_ID   integer     

Network interface ID. 0 = unit-level parameter.

PAR_NAME   string     

Parameter name / key.

PAR_INDEX   integer     

Index for multi-valued parameters.

VALUE   string     

Parameter value (up to 255 characters).

CONTENT   string     

Binary content (base64-encoded longblob).

TEXT_CONTENT   string     

Large text content (longtext).

customer_service_devices   object[]     

Services bound to this unit — junction records linking units to customers and their services.
NS_ID   integer     

Unique customer-service-device binding ID.

NS_N_ID   integer     

Customer unit ID this service is bound to.

NS_U_ID   integer     

Customer ID who owns the service on this unit. See GET /v3/customers/{id}.

NS_SA_ID   integer     

Customer service ID. Null when binding exists without a specific active service. See GET /v3/customer-services/{id}.

NS_TIME   string     

Datetime when the service was bound to the unit.

NS_L_ID   integer     

Operator (login) ID who created or last modified this binding.

NS_NEEDS_UPDATE   integer     

Flag indicating a pending configuration update. 0 = no, 1 = yes.

Get Customer Unit

requires authentication

Retrieve a specific customer unit by ID.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-units/116416" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customer-units/116416"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "ID": 1792678,
        "NAME": "UNIT-qwrsit",
        "NOTE": null,
        "MANAGED": 0,
        "MANAG_IP": null,
        "PARENT_NODE": null,
        "F_TYPE": null,
        "N_TYPE": "BLK_DEVICE",
        "N_DEVICE_TYPE": "blk_device",
        "N_CUSTOMER": 1,
        "USER_SERVICE_ID": 0,
        "CUSTOMER_PARENT": 1,
        "CUSTOMER_TYPE": null,
        "CUSTOMER_LOCATION": 0,
        "MAC": null,
        "UPDATE_FLAG": 0,
        "AGR_GROUP": null,
        "STREET": null,
        "HOUSE_ID": null,
        "N_ZIP": null,
        "N_CITY": null,
        "SOCKET": null,
        "N_COUNTER_ID": 0,
        "N_PRODUCER": null,
        "N_SERIAL_NUM": null,
        "N_LAST_RESPONSE": null,
        "N_CT": 46,
        "N_CREATED": null,
        "N_L_ID": 646,
        "N_GPS_LATITUDE": null,
        "N_GPS_LONGITUDE": null,
        "N_UCP_ID": null,
        "N_US_ID": null,
        "N_UA_ID": null,
        "N_CACHE_NAME": "autem",
        "N_CACHE_LAST_WS_ID": null,
        "N_DELETED": null,
        "params": [
            {
                "ID": 301268720,
                "NODE_ID": 1792678,
                "NI_NPI_ID": 0,
                "PAR_NAME": "blkdevice_connection_type",
                "PAR_INDEX": 0,
                "VALUE": null,
                "CONTENT": null,
                "TEXT_CONTENT": null
            }
        ],
        "customer_service_devices": [
            {
                "NS_ID": 2148178,
                "NS_N_ID": 1792678,
                "NS_U_ID": 1038,
                "NS_SA_ID": null,
                "NS_TIME": "2026-02-11 22:12:44",
                "NS_L_ID": 1,
                "NS_NEEDS_UPDATE": 0
            }
        ]
    }
}

Request      

GET api/v3/customer-units/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the customer unit. Example: 116416

Response

Response Fields

data   object     
ID   integer     

Unique customer unit identifier (primary key).

NAME   string     

Unit name (up to 30 characters).

NOTE   string     

Free-text note.

N_TYPE   string     

Node type. Always 'BLK_DEVICE' for customer units.

N_DEVICE_TYPE   string     

Specific unit/device type identifier (references nodes_device_types).

F_TYPE   string     

Functional type. Possible values: AP, BRIDGE, IP, OLT, ONU, ROUTER, SIP, SWITCH.

N_CUSTOMER   integer     

Customer device flag. Always 1 for customer units.

CUSTOMER_PARENT   integer     

Flag indicating this unit can host child devices (CPE). 1 = open for customer connections.

CUSTOMER_TYPE   string     

Customer device sub-type classification.

MANAGED   integer     

Flag indicating the unit is managed (configured) by the Mango system. 1 = managed.

MANAG_IP   string     

Management IP address.

UPDATE_FLAG   integer     

Flag indicating configuration needs to be pushed/updated. 1 = update pending.

MAC   string     

MAC address.

N_LAST_RESPONSE   string     

Datetime of the last successful SNMP monitoring response.

PARENT_NODE   integer     

ID of the parent device in the network topology.

USER_SERVICE_ID   integer     

ID of the associated customer service.

N_CT   integer     

Location / installation (CT) identifier.

STREET   string     

Street name of the unit location.

HOUSE_ID   string     

House number (cislo popisne).

N_ZIP   string     

ZIP / postal code (up to 5 characters).

N_CITY   string     

City of the unit location.

SOCKET   string     

Apartment/socket identifier at the address.

N_GPS_LATITUDE   number     

GPS latitude.

N_GPS_LONGITUDE   number     

GPS longitude.

N_UCP_ID   integer     

UIR registry city part ID.

N_US_ID   integer     

UIR registry street ID.

N_UA_ID   integer     

UIR registry address ID (RUIAN code).

N_PRODUCER   string     

Device manufacturer / producer.

N_SERIAL_NUM   string     

Serial number.

N_CREATED   string     

Datetime when the unit record was created.

N_L_ID   integer     

ID of the operator (login) who last modified this unit.

N_CACHE_NAME   string     

Cached display name combining class, type and unit name.

N_CACHE_LAST_WS_ID   integer     

Cached ID of the last work session that touched this unit.

CUSTOMER_LOCATION   integer     

Deprecated. Former customer location reference (now via nodes_cust_locations).

AGR_GROUP   integer     

Deprecated. Former aggregation group reference.

N_COUNTER_ID   integer     

Deprecated. Former counter ID (now stored as a unit parameter).

normalized_address   string     

Full normalized address from the UIR/RUIAN registry (based on N_UA_ID). Null when N_UA_ID is not set.

params   object[]     

Unit parameters — collection of key-value pairs from the node_info table.
ID   integer     

Unique parameter record identifier.

NODE_ID   integer     

ID of the parent customer unit.

NI_NPI_ID   integer     

Network interface ID. 0 = unit-level parameter.

PAR_NAME   string     

Parameter name / key.

PAR_INDEX   integer     

Index for multi-valued parameters.

VALUE   string     

Parameter value (up to 255 characters).

CONTENT   string     

Binary content (base64-encoded longblob).

TEXT_CONTENT   string     

Large text content (longtext).

customer_service_devices   object[]     

Services bound to this unit — junction records linking units to customers and their services.
NS_ID   integer     

Unique customer-service-device binding ID.

NS_N_ID   integer     

Customer unit ID this service is bound to.

NS_U_ID   integer     

Customer ID who owns the service on this unit. See GET /v3/customers/{id}.

NS_SA_ID   integer     

Customer service ID. Null when binding exists without a specific active service. See GET /v3/customer-services/{id}.

NS_TIME   string     

Datetime when the service was bound to the unit.

NS_L_ID   integer     

Operator (login) ID who created or last modified this binding.

NS_NEEDS_UPDATE   integer     

Flag indicating a pending configuration update. 0 = no, 1 = yes.

Customers

List Customers

requires authentication

This endpoint gets a list of customers. The list can be filtered and sorted.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/customers?per_page=10&page=1&active=true&ids=1%2C2%2C3&cts=1%2C2%2C3&search=Smith&groups_all=1%2C2&groups_any=1%2C2&device=4967" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customers"
);

const params = {
    "per_page": "10",
    "page": "1",
    "active": "true",
    "ids": "1,2,3",
    "cts": "1,2,3",
    "search": "Smith",
    "groups_all": "1,2",
    "groups_any": "1,2",
    "device": "4967",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "USER_ID": 1977197,
            "LOGIN": "price.amber",
            "PASSWORD": "<m5L[)~",
            "U_PASS_QUESTION": null,
            "U_PASS_ANSWER": null,
            "TYPE": "S",
            "P_TITLE": null,
            "FIRST_NAME": "Bailee",
            "LAST_NAME": "Leffler",
            "COMPANY": "Mitchell-VonRueden",
            "STREET": "Vesta Coves",
            "HOUSE_ID": "47809",
            "CITY": "Considinehaven",
            "ZIP": "36080-",
            "U_UC_ID": null,
            "U_US_ID": null,
            "U_UA_ID": null,
            "U_CL_ID": null,
            "ADR2": null,
            "U_RECIPIENT2": null,
            "STREET2": null,
            "HOUSE_ID2": null,
            "CITY2": null,
            "ZIP2": null,
            "U_UC_ID2": null,
            "U_US_ID2": null,
            "U_UA_ID2": null,
            "U_CL_ID2": null,
            "ADR3": null,
            "U_RECIPIENT3": null,
            "STREET3": null,
            "HOUSE_ID3": null,
            "CITY3": null,
            "ZIP3": null,
            "U_UC_ID3": null,
            "U_US_ID3": null,
            "U_UA_ID3": null,
            "U_CL_ID3": null,
            "FAX": null,
            "SERVICES": "doloremque",
            "COMP_ID": null,
            "COMP_FID": null,
            "ACTIVATION": "1900-01-01 00:00:00",
            "U_ACTIVATION_LAST": "2026-04-08 02:50:06",
            "INFO_MAIL": 1,
            "INFO_POST": null,
            "USER_NOTE": null,
            "INTERNAL_NOTE": null,
            "CT": "008",
            "FLAT": null,
            "NOTE1": null,
            "NOTE2": null,
            "NOTE3": null,
            "NOTE4": null,
            "NOTE5": null,
            "NOTE6": null,
            "NOTE7": null,
            "NOTE8": null,
            "SIPO_NUM": null,
            "DATE_BEGIN": null,
            "DATE_END": null,
            "SIPO_DATE_FROM": null,
            "GROUP_ID": null,
            "VAR_SYMBOL": null,
            "AGR_NAME": null,
            "PERSON_ID_NUMBER": null,
            "U_BIRTHDAY": null,
            "U_PERSONAL_NUMBER": null,
            "U_DOCUMENT_NUMBER": null,
            "ACCOUNT_PRE_NUMBER": null,
            "ACCOUNT_NUMBER": null,
            "ACCOUNT_BANK": null,
            "U_IBAN": null,
            "U_ACCOUNT_ATTACH": null,
            "U_ACCOUNT_SPECSYM": null,
            "SALESMAN": null,
            "U_BIRTH_NUMBER": null,
            "U_TECH_LOC": null,
            "U_FLAT_TYPE": null,
            "U_TECH_NAME": null,
            "U_PREMISES": 0,
            "U_INV_NOTE": null,
            "U_CODENAME": null,
            "U_ACTIVE": 1,
            "LOG_LEVEL": "INFO",
            "U_INFO_SMS": 0,
            "U_PERSON_ID": null,
            "U_STATUTARY": null,
            "U_COMP_VATID": null,
            "U_DEFAULT_BP_ID": null,
            "U_EU_FIRST_LOGIN": 1,
            "U_PASS_EXPIRE": null,
            "U_PASS_CHANGE": null,
            "U_REGENERATE": null,
            "U_REGENERATE_L_ID": null,
            "U_REGENERATE_PAYMENTS": null,
            "U_REGENERATE_PAYMENTS_L_ID": null,
            "U_PROV_LEVEL": 10,
            "U_DEGREE_BEHIND": null,
            "U_PROVISIONING": 0,
            "U_CODE_REFERENCES": null,
            "U_BATCH": null,
            "U_VALUATION": null,
            "U_PROVIDER_USER_ID": null,
            "U_PROVIDER_TYPE": "NONE",
            "U_PROVIDER_LABEL": null,
            "U_PROVIDER_ACTIVE": null,
            "U_INFO_MARKETING": null,
            "U_OFF_LIMIT": null,
            "U_LAST_USAGE": null,
            "U_LAST_CHANGE": null,
            "U_DEBTS_GENERATE": 0,
            "U_EXTRA_WORK_DETAIL": 0,
            "U_WORKS_COUNT_STRATEGY": "MINS",
            "U_GROUP_COMP_FID": 0,
            "params": [
                {
                    "UP_ID": "0000988046",
                    "UP_USER_ID": 1977197,
                    "UP_NAME": "param_qbew",
                    "UP_VALID_FROM": "2026-01-15",
                    "UP_VALID_TO": null,
                    "UP_VALUE": "Deleniti nemo odit.",
                    "UP_CONTENT": null,
                    "UP_CREATED": "2026-03-23 07:14:23",
                    "UP_L_ID": "000488"
                }
            ],
            "contact_phone_numbers": [
                {
                    "CPN_ID": 1105898,
                    "CPN_SUBJ_ID": 1977197,
                    "CPN_VALID": 1,
                    "CPN_PHONE": 608371679,
                    "CPN_L_ID": 3465,
                    "CPN_LAST_UPDATE": "2026-02-26 19:01:25"
                }
            ],
            "contact_email_addresses": [
                {
                    "CEA_ID": 445985,
                    "CEA_SUBJ_ID": 1977197,
                    "CEA_VALID": 1,
                    "CEA_EMAIL": "[email protected]",
                    "CEA_L_ID": 6144,
                    "CEA_LAST_UPDATE": "2026-02-20 19:35:09"
                }
            ]
        },
        {
            "USER_ID": 1977198,
            "LOGIN": "franecki.brennon",
            "PASSWORD": "}76z|?jMYV",
            "U_PASS_QUESTION": 9,
            "U_PASS_ANSWER": "reiciendis",
            "TYPE": "S",
            "P_TITLE": null,
            "FIRST_NAME": "Mireille",
            "LAST_NAME": "Ullrich",
            "COMPANY": "Grady Ltd",
            "STREET": "Tobin Highway",
            "HOUSE_ID": "4151",
            "CITY": "Klockoton",
            "ZIP": "61235-",
            "U_UC_ID": null,
            "U_US_ID": null,
            "U_UA_ID": null,
            "U_CL_ID": null,
            "ADR2": null,
            "U_RECIPIENT2": null,
            "STREET2": null,
            "HOUSE_ID2": null,
            "CITY2": null,
            "ZIP2": null,
            "U_UC_ID2": null,
            "U_US_ID2": null,
            "U_UA_ID2": null,
            "U_CL_ID2": null,
            "ADR3": null,
            "U_RECIPIENT3": null,
            "STREET3": null,
            "HOUSE_ID3": null,
            "CITY3": null,
            "ZIP3": null,
            "U_UC_ID3": null,
            "U_US_ID3": null,
            "U_UA_ID3": null,
            "U_CL_ID3": null,
            "FAX": null,
            "SERVICES": "ut",
            "COMP_ID": null,
            "COMP_FID": null,
            "ACTIVATION": "1900-01-01 00:00:00",
            "U_ACTIVATION_LAST": "2026-01-28 18:29:54",
            "INFO_MAIL": 1,
            "INFO_POST": null,
            "USER_NOTE": null,
            "INTERNAL_NOTE": null,
            "CT": "008",
            "FLAT": null,
            "NOTE1": null,
            "NOTE2": null,
            "NOTE3": null,
            "NOTE4": null,
            "NOTE5": null,
            "NOTE6": null,
            "NOTE7": null,
            "NOTE8": null,
            "SIPO_NUM": null,
            "DATE_BEGIN": null,
            "DATE_END": null,
            "SIPO_DATE_FROM": null,
            "GROUP_ID": null,
            "VAR_SYMBOL": null,
            "AGR_NAME": null,
            "PERSON_ID_NUMBER": null,
            "U_BIRTHDAY": null,
            "U_PERSONAL_NUMBER": null,
            "U_DOCUMENT_NUMBER": null,
            "ACCOUNT_PRE_NUMBER": null,
            "ACCOUNT_NUMBER": null,
            "ACCOUNT_BANK": null,
            "U_IBAN": null,
            "U_ACCOUNT_ATTACH": null,
            "U_ACCOUNT_SPECSYM": null,
            "SALESMAN": null,
            "U_BIRTH_NUMBER": null,
            "U_TECH_LOC": null,
            "U_FLAT_TYPE": null,
            "U_TECH_NAME": null,
            "U_PREMISES": 0,
            "U_INV_NOTE": null,
            "U_CODENAME": null,
            "U_ACTIVE": 1,
            "LOG_LEVEL": "INFO",
            "U_INFO_SMS": 0,
            "U_PERSON_ID": null,
            "U_STATUTARY": null,
            "U_COMP_VATID": null,
            "U_DEFAULT_BP_ID": null,
            "U_EU_FIRST_LOGIN": 1,
            "U_PASS_EXPIRE": null,
            "U_PASS_CHANGE": null,
            "U_REGENERATE": null,
            "U_REGENERATE_L_ID": null,
            "U_REGENERATE_PAYMENTS": null,
            "U_REGENERATE_PAYMENTS_L_ID": null,
            "U_PROV_LEVEL": 10,
            "U_DEGREE_BEHIND": null,
            "U_PROVISIONING": 0,
            "U_CODE_REFERENCES": null,
            "U_BATCH": null,
            "U_VALUATION": null,
            "U_PROVIDER_USER_ID": null,
            "U_PROVIDER_TYPE": "NONE",
            "U_PROVIDER_LABEL": null,
            "U_PROVIDER_ACTIVE": null,
            "U_INFO_MARKETING": null,
            "U_OFF_LIMIT": null,
            "U_LAST_USAGE": null,
            "U_LAST_CHANGE": null,
            "U_DEBTS_GENERATE": 0,
            "U_EXTRA_WORK_DETAIL": 0,
            "U_WORKS_COUNT_STRATEGY": "MINS",
            "U_GROUP_COMP_FID": 0,
            "params": [
                {
                    "UP_ID": "0000988047",
                    "UP_USER_ID": 1977198,
                    "UP_NAME": "param_crcv",
                    "UP_VALID_FROM": "2026-01-28",
                    "UP_VALID_TO": null,
                    "UP_VALUE": "Doloribus fugiat ut.",
                    "UP_CONTENT": "Error neque recusandae et ipsam dolorem et ut dicta. Assumenda consequatur ut et sunt quisquam. Repellendus ut eaque alias ratione dolores.",
                    "UP_CREATED": "2026-01-26 01:15:15",
                    "UP_L_ID": "000071"
                }
            ],
            "contact_phone_numbers": [
                {
                    "CPN_ID": 1105899,
                    "CPN_SUBJ_ID": 1977198,
                    "CPN_VALID": 0,
                    "CPN_PHONE": 758140065,
                    "CPN_L_ID": 4908,
                    "CPN_LAST_UPDATE": "2026-04-04 07:07:48"
                }
            ],
            "contact_email_addresses": [
                {
                    "CEA_ID": 445986,
                    "CEA_SUBJ_ID": 1977198,
                    "CEA_VALID": 0,
                    "CEA_EMAIL": "[email protected]",
                    "CEA_L_ID": 6453,
                    "CEA_LAST_UPDATE": "2026-02-21 07:12:16"
                }
            ]
        }
    ]
}

Request      

GET api/v3/customers

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of users to return per page (optional) Example: 10

page   integer  optional    

Page number to return (optional) Example: 1

active   string  optional    

Filter by active status Example: true

ids   string  optional    

Filter by comma-separated IDs Example: 1,2,3

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Example: 1,2,3

search   string  optional    

Full-text search across FIRST_NAME, LAST_NAME, COMPANY (case-insensitive LIKE) Example: Smith

groups_all   string  optional    

Filter customers who are members of ALL specified group IDs (comma-separated, AND logic) Example: 1,2

groups_any   string  optional    

Filter customers who are members of ANY of the specified group IDs (comma-separated, OR logic) Example: 1,2

device   integer  optional    

Filter customers linked to a specific device (node) ID via nodes_services Example: 4967

Response

Response Fields

data   object     
USER_ID   integer     

Unique customer identifier (primary key).

LOGIN   string     

Login name for the customer portal (SelfCare).

PASSWORD   string     

Password hash (MD5, 32 chars).

U_PASS_QUESTION   integer     

Password recovery question number (a code list entry ID).

U_PASS_ANSWER   string     

Answer to the password recovery question.

U_EU_FIRST_LOGIN   integer     

Flag indicating the SelfCare account has not been authorized yet. 1 = not yet authorized.

U_PASS_EXPIRE   integer     

Password expiration setting (days).

U_PASS_CHANGE   string     

Datetime of the last password change.

TYPE   string     

Customer type. 'S' = private person, 'F' = self-employed / natural person with business, 'P' = legal entity / company.

Must be one of:
  • S
  • F
  • P
P_TITLE   string     

Title before name (e.g. Ing., Mgr.).

U_DEGREE_BEHIND   string     

Academic degree after name (e.g. Ph.D., CSc.).

FIRST_NAME   string     

Customer's first name.

LAST_NAME   string     

Customer's last name (surname).

COMPANY   string     

Company or organization name. Used as display name for TYPE 'P' and 'F'.

U_BIRTHDAY   string     

Date of birth (YYYY-MM-DD).

U_PERSONAL_NUMBER   string     

Personal identification number (rodné číslo / birth number).

U_BIRTH_NUMBER   string     

Birth number (rodné číslo). Alternative field for personal identification.

PERSON_ID_NUMBER   string     

National personal ID number.

U_PERSON_ID   string     

Person identifier (up to 12 chars).

U_DOCUMENT_NUMBER   string     

Identity document number (e.g. national ID card number).

COMP_ID   string     

Company registration number (IČO).

COMP_FID   string     

Tax identification number (DIČ).

U_COMP_VATID   string     

VAT identification number (IČ DPH).

U_GROUP_COMP_FID   integer     

Flag indicating a group tax ID (skupinové DIČ). 1 = group DIČ is used.

U_STATUTARY   string     

Statutory body / authorized signatory of the contract.

STREET   string     

Primary address — street name.

HOUSE_ID   string     

Primary address — house number (číslo popisné).

FLAT   string     

Primary address — flat/apartment number.

CITY   string     

Primary address — city.

ZIP   string     

Primary address — postal code (PSČ).

U_UC_ID   integer     

Primary address — UIR registry city ID.

U_US_ID   integer     

Primary address — UIR registry street ID.

U_UA_ID   integer     

Primary address — UIR registry address ID.

U_CL_ID   integer     

Primary address — code list reference ID.

ADR2   string     

Shipping/mailing address mode. 'AS1' = same as primary address, 'OWN' = custom address.

Must be one of:
  • AS1
  • OWN
U_RECIPIENT2   string     

Shipping address — recipient name.

STREET2   string     

Shipping address — street name.

HOUSE_ID2   string     

Shipping address — house number.

CITY2   string     

Shipping address — city.

ZIP2   string     

Shipping address — postal code (PSČ).

U_UC_ID2   integer     

Shipping address — UIR registry city ID.

U_US_ID2   integer     

Shipping address — UIR registry street ID.

U_UA_ID2   integer     

Shipping address — UIR registry address ID.

U_CL_ID2   integer     

Shipping address — code list reference ID.

ADR3   string     

Invoice address mode. 'AS1' = same as primary, 'AS2' = same as shipping, 'OWN' = custom address.

Must be one of:
  • AS1
  • AS2
  • OWN
U_RECIPIENT3   string     

Invoice address — recipient name.

STREET3   string     

Invoice address — street name.

HOUSE_ID3   string     

Invoice address — house number.

CITY3   string     

Invoice address — city.

ZIP3   string     

Invoice address — postal code (PSČ).

U_UC_ID3   integer     

Invoice address — UIR registry city ID.

U_US_ID3   integer     

Invoice address — UIR registry street ID.

U_UA_ID3   integer     

Invoice address — UIR registry address ID.

U_CL_ID3   integer     

Invoice address — code list reference ID.

FAX   string     

Fax number.

INFO_MAIL   integer     

Email notification consent flag. 1 = opted in.

INFO_POST   integer     

Postal (print) notification flag.

U_INFO_SMS   integer     

SMS notification consent flag. 1 = opted in.

U_INFO_MARKETING   integer     

Marketing communication consent flag.

SERVICES   string     

Comma-separated list of service identifiers associated with the customer.

ACTIVATION   string     

Datetime of the customer's initial activation.

U_ACTIVATION_LAST   string     

Datetime of the customer's most recent activation.

DATE_BEGIN   string     

Contract start date (YYYY-MM-DD).

DATE_END   string     

Contract end date (YYYY-MM-DD).

AGR_NAME   string     

Agreement/contract number.

U_ACTIVE   integer     

Active customer flag. 1 = active, 0 = inactive.

CT   integer     

Company/tenant identifier — multi-tenant discriminator.

GROUP_ID   integer     

Customer group identifier.

VAR_SYMBOL   integer     

Variable symbol — unique payment identifier used in bank transfers.

SIPO_NUM   string     

SIPO number — postal payment connector number for recurring payments.

SIPO_DATE_FROM   string     

SIPO effective start datetime.

ACCOUNT_PRE_NUMBER   string     

Bank account prefix number (Czech format).

ACCOUNT_NUMBER   string     

Bank account number.

ACCOUNT_BANK   string     

Bank code (4-digit Czech bank code).

U_IBAN   string     

International Bank Account Number (IBAN).

U_ACCOUNT_ATTACH   integer     

Attachment ID linked to the bank account record.

U_ACCOUNT_SPECSYM   integer     

Specific symbol associated with the bank account.

U_DEFAULT_BP_ID   integer     

Default billing period ID.

U_VALUATION   integer     

Customer valuation in percent. Used for modifying prices in pricelist calculations.

U_DEBTS_GENERATE   integer     

Debts generation flag. 1 = automatic debt generation enabled.

U_OFF_LIMIT   integer     

Off-limit threshold value.

USER_NOTE   string     

Customer-visible note.

INTERNAL_NOTE   string     

Internal note — visible only to operators, not to the customer.

U_INV_NOTE   string     

Note printed on invoices.

NOTE1   string     

Custom note field 1.

NOTE2   string     

Custom note field 2.

NOTE3   string     

Custom note field 3.

NOTE4   string     

Custom note field 4.

NOTE5   string     

Custom note field 5.

NOTE6   string     

Custom note field 6.

NOTE7   string     

Custom note field 7.

NOTE8   string     

Custom note field 8.

SALESMAN   integer     

Sales representative (admin user) ID.

U_PREMISES   integer     

Business premises flag. 1 = customer has associated premises.

U_FLAT_TYPE   string     

Type of flat/premises (e.g. apartment category).

U_TECH_LOC   string     

Technical location identifier.

U_TECH_NAME   string     

Technical name / description of the location.

U_CODENAME   string     

Code identifier used by automated processors (e.g. SMS request handling).

U_CODE_REFERENCES   integer     

Referral/recommendation code (VIP).

U_EXTRA_WORK_DETAIL   integer     

Flag enabling extra work detail tracking.

U_WORKS_COUNT_STRATEGY   string     

Work time counting strategy.

Must be one of:
  • MINS
  • COMM_15
  • COMM_30
  • COMM_60
  • ROUND_15
  • ROUND_30
  • ROUND_60
U_PROV_LEVEL   integer     

Customer trust/provisioning level. Higher values indicate greater trust.

U_PROVISIONING   integer     

Provisioning status.

U_PROVIDER_USER_ID   integer     

User ID of the associated location provider.

U_PROVIDER_TYPE   string     

Provider type classification.

Must be one of:
  • NONE
  • PROVIDER
  • DEFAULT_PROVIDER
U_PROVIDER_LABEL   integer     

Provider label — used as a contract number or identifier when USER_ID range is too large.

U_PROVIDER_ACTIVE   integer     

Flag indicating whether the location provider is active.

LOG_LEVEL   string     

Logging level for this customer.

Must be one of:
  • EMERG
  • ALERT
  • CRIT
  • ERR
  • WARNING
  • NOTICE
  • INFO
  • DEBUG
U_REGENERATE   string     

Timestamp when user-dependent data regeneration started. Cleared after successful regeneration.

U_REGENERATE_L_ID   integer     

Operator ID who triggered the data regeneration.

U_REGENERATE_PAYMENTS   string     

Timestamp when payment data regeneration started.

U_REGENERATE_PAYMENTS_L_ID   integer     

Operator ID who triggered the payment data regeneration.

U_BATCH   string     

Batch processing data.

U_LAST_USAGE   string     

Date of the customer's last service usage (YYYY-MM-DD).

U_LAST_CHANGE   string     

Datetime of the last modification to this customer record.

full_name   string     

Computed display name. For TYPE 'P' returns COMPANY; for TYPE 'F' with COMPANY set returns COMPANY; otherwise returns LAST_NAME + FIRST_NAME.

normalized_address   string     

Full normalized primary address string from the UIR registry (based on U_UA_ID).

normalized_shipping_address   string     

Full normalized shipping address string from the UIR registry (based on U_UA_ID2).

normalized_invoice_address   string     

Full normalized invoice address string from the UIR registry (based on U_UA_ID3).

params   object[]     

Customer parameters — collection of key-value pairs.
UP_ID   integer     

Unique customer parameter record ID.

UP_USER_ID   integer     

Customer ID this parameter belongs to.

UP_NAME   string     

Parameter name (max 30 chars).

UP_VALID_FROM   string     

Date from which this parameter is valid (YYYY-MM-DD).

UP_VALID_TO   string     

Date until which this parameter is valid. Null = no expiry.

UP_VALUE   string     

Parameter value (max 255 chars).

UP_CONTENT   string     

Binary/blob content (base64-encoded). Null when not present.

UP_CREATED   string     

Creation timestamp (YYYY-MM-DD HH:MM:SS).

UP_L_ID   integer     

Login session ID that created this record.

contact_phone_numbers   object[]     

Collection of customer's contact phone numbers.
CPN_ID   integer     

Unique phone number record ID.

CPN_SUBJ_ID   integer     

Customer ID. See GET /v3/customers/{id}.

CPN_VALID   integer     

Validity flag. 1 = active, 0 = inactive.

CPN_PHONE   integer     

Phone number in international format (without leading + or 00).

CPN_L_ID   integer     

ID of the operator who made the last change.

CPN_LAST_UPDATE   string     

Last update datetime (YYYY-MM-DD HH:MM:SS).

contact_email_addresses   object[]     

Collection of customer's contact email addresses.
CEA_ID   integer     

Unique email address record ID.

CEA_SUBJ_ID   integer     

Customer ID. See GET /v3/customers/{id}.

CEA_VALID   integer     

Validity flag. 1 = active, 0 = inactive.

CEA_EMAIL   string     

Email address.

CEA_L_ID   integer     

ID of the operator who made the last change.

CEA_LAST_UPDATE   string     

Last update datetime (YYYY-MM-DD HH:MM:SS).

Create Customer

requires authentication

This endpoint creates a new customer.

Example request:
curl --request POST \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customers" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"login\": \"john.doe\",
    \"password\": \"secret123\",
    \"type\": \"S\",
    \"first_name\": \"John\",
    \"last_name\": \"Doe\",
    \"company\": \"Doe Corp\",
    \"street\": \"Main Street 1\",
    \"house_id\": \"12A\",
    \"city\": \"New York\",
    \"zip\": \"10001\",
    \"phones\": [
        \"architecto\"
    ],
    \"emails\": [
        \"architecto\"
    ],
    \"comp_id\": \"12345678\",
    \"comp_fid\": \"CZ12345678\",
    \"comp_vatid\": \"SK1234567890\",
    \"active\": 1,
    \"pass_question\": \"architecto\",
    \"pass_answer\": \"architecto\",
    \"ptitle\": \"n\",
    \"adr2\": \"g\",
    \"recipient2\": \"z\",
    \"street2\": \"m\",
    \"house_id2\": \"i\",
    \"city2\": \"y\",
    \"zip2\": \"vdlj\",
    \"adr3\": \"n\",
    \"recipient3\": \"i\",
    \"street3\": \"k\",
    \"house_id3\": \"h\",
    \"city3\": \"w\",
    \"zip3\": \"aykc\",
    \"fax\": \"architecto\",
    \"personal_number\": \"architecto\",
    \"birthday\": \"2026-04-15T14:55:09\",
    \"info_mail\": 16,
    \"info_post\": 16,
    \"info_sms\": 16,
    \"premises\": \"architecto\",
    \"agr_name\": \"architecto\",
    \"varsym\": \"architecto\",
    \"sipo\": \"architecto\",
    \"account_pre_num\": \"architecto\",
    \"account_num\": \"architecto\",
    \"account_bank\": \"architecto\",
    \"account_specsym\": \"architecto\",
    \"note_user\": \"architecto\",
    \"note_internal\": \"architecto\",
    \"note_invoice\": \"architecto\",
    \"flat\": \"architecto\",
    \"flat_type\": \"architecto\",
    \"tech_loc\": \"architecto\",
    \"tech_name\": \"architecto\",
    \"codename\": \"architecto\",
    \"log_level\": 16,
    \"document_number\": \"architecto\",
    \"statutary\": \"architecto\",
    \"default_bp_id\": 16,
    \"eu_first_login\": 16,
    \"activation\": \"architecto\",
    \"prov_level\": 16,
    \"degree_behind\": \"architecto\",
    \"account_attach\": \"architecto\",
    \"code_references\": \"architecto\",
    \"valuation\": \"architecto\",
    \"uc_id\": 16,
    \"us_id\": 16,
    \"ua_id\": 16,
    \"uc_id2\": 16,
    \"us_id2\": 16,
    \"ua_id2\": 16,
    \"uc_id3\": 16,
    \"us_id3\": 16,
    \"ua_id3\": 16,
    \"bp_ids\": \"architecto\",
    \"provider_user_id\": 16,
    \"cl_id\": 16,
    \"cl_id2\": 16,
    \"cl_id3\": 16,
    \"iban\": \"architecto\",
    \"info_marketing\": 16,
    \"vat_registered\": 16,
    \"vat_registered_from\": \"2026-04-15T14:55:09\",
    \"group_comp_fid\": \"architecto\",
    \"consent\": 16,
    \"params\": [
        {
            \"name\": \"architecto\",
            \"value\": \"architecto\"
        }
    ]
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customers"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "login": "john.doe",
    "password": "secret123",
    "type": "S",
    "first_name": "John",
    "last_name": "Doe",
    "company": "Doe Corp",
    "street": "Main Street 1",
    "house_id": "12A",
    "city": "New York",
    "zip": "10001",
    "phones": [
        "architecto"
    ],
    "emails": [
        "architecto"
    ],
    "comp_id": "12345678",
    "comp_fid": "CZ12345678",
    "comp_vatid": "SK1234567890",
    "active": 1,
    "pass_question": "architecto",
    "pass_answer": "architecto",
    "ptitle": "n",
    "adr2": "g",
    "recipient2": "z",
    "street2": "m",
    "house_id2": "i",
    "city2": "y",
    "zip2": "vdlj",
    "adr3": "n",
    "recipient3": "i",
    "street3": "k",
    "house_id3": "h",
    "city3": "w",
    "zip3": "aykc",
    "fax": "architecto",
    "personal_number": "architecto",
    "birthday": "2026-04-15T14:55:09",
    "info_mail": 16,
    "info_post": 16,
    "info_sms": 16,
    "premises": "architecto",
    "agr_name": "architecto",
    "varsym": "architecto",
    "sipo": "architecto",
    "account_pre_num": "architecto",
    "account_num": "architecto",
    "account_bank": "architecto",
    "account_specsym": "architecto",
    "note_user": "architecto",
    "note_internal": "architecto",
    "note_invoice": "architecto",
    "flat": "architecto",
    "flat_type": "architecto",
    "tech_loc": "architecto",
    "tech_name": "architecto",
    "codename": "architecto",
    "log_level": 16,
    "document_number": "architecto",
    "statutary": "architecto",
    "default_bp_id": 16,
    "eu_first_login": 16,
    "activation": "architecto",
    "prov_level": 16,
    "degree_behind": "architecto",
    "account_attach": "architecto",
    "code_references": "architecto",
    "valuation": "architecto",
    "uc_id": 16,
    "us_id": 16,
    "ua_id": 16,
    "uc_id2": 16,
    "us_id2": 16,
    "ua_id2": 16,
    "uc_id3": 16,
    "us_id3": 16,
    "ua_id3": 16,
    "bp_ids": "architecto",
    "provider_user_id": 16,
    "cl_id": 16,
    "cl_id2": 16,
    "cl_id3": 16,
    "iban": "architecto",
    "info_marketing": 16,
    "vat_registered": 16,
    "vat_registered_from": "2026-04-15T14:55:09",
    "group_comp_fid": "architecto",
    "consent": 16,
    "params": [
        {
            "name": "architecto",
            "value": "architecto"
        }
    ]
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "data": {
        "USER_ID": 1977199,
        "LOGIN": "zbailey",
        "PASSWORD": "+-0pBNvYgxwmi/#iw",
        "U_PASS_QUESTION": null,
        "U_PASS_ANSWER": "quidem",
        "TYPE": "S",
        "P_TITLE": "Mr.",
        "FIRST_NAME": "Alayna",
        "LAST_NAME": "Leuschke",
        "COMPANY": "Fritsch-O'Keefe",
        "STREET": "Carey Greens",
        "HOUSE_ID": "57515",
        "CITY": "North Roderick",
        "ZIP": "06227",
        "U_UC_ID": null,
        "U_US_ID": null,
        "U_UA_ID": null,
        "U_CL_ID": null,
        "ADR2": null,
        "U_RECIPIENT2": null,
        "STREET2": null,
        "HOUSE_ID2": null,
        "CITY2": null,
        "ZIP2": null,
        "U_UC_ID2": null,
        "U_US_ID2": null,
        "U_UA_ID2": null,
        "U_CL_ID2": null,
        "ADR3": null,
        "U_RECIPIENT3": null,
        "STREET3": null,
        "HOUSE_ID3": null,
        "CITY3": null,
        "ZIP3": null,
        "U_UC_ID3": null,
        "U_US_ID3": null,
        "U_UA_ID3": null,
        "U_CL_ID3": null,
        "FAX": null,
        "SERVICES": "praesentium",
        "COMP_ID": null,
        "COMP_FID": null,
        "ACTIVATION": "1900-01-01 00:00:00",
        "U_ACTIVATION_LAST": "2026-02-22 02:16:59",
        "INFO_MAIL": 1,
        "INFO_POST": null,
        "USER_NOTE": null,
        "INTERNAL_NOTE": null,
        "CT": "006",
        "FLAT": null,
        "NOTE1": null,
        "NOTE2": null,
        "NOTE3": null,
        "NOTE4": null,
        "NOTE5": null,
        "NOTE6": null,
        "NOTE7": null,
        "NOTE8": null,
        "SIPO_NUM": null,
        "DATE_BEGIN": null,
        "DATE_END": null,
        "SIPO_DATE_FROM": null,
        "GROUP_ID": null,
        "VAR_SYMBOL": null,
        "AGR_NAME": null,
        "PERSON_ID_NUMBER": null,
        "U_BIRTHDAY": null,
        "U_PERSONAL_NUMBER": null,
        "U_DOCUMENT_NUMBER": null,
        "ACCOUNT_PRE_NUMBER": null,
        "ACCOUNT_NUMBER": null,
        "ACCOUNT_BANK": null,
        "U_IBAN": null,
        "U_ACCOUNT_ATTACH": null,
        "U_ACCOUNT_SPECSYM": null,
        "SALESMAN": null,
        "U_BIRTH_NUMBER": null,
        "U_TECH_LOC": null,
        "U_FLAT_TYPE": null,
        "U_TECH_NAME": null,
        "U_PREMISES": 0,
        "U_INV_NOTE": null,
        "U_CODENAME": null,
        "U_ACTIVE": 1,
        "LOG_LEVEL": "INFO",
        "U_INFO_SMS": 0,
        "U_PERSON_ID": null,
        "U_STATUTARY": null,
        "U_COMP_VATID": null,
        "U_DEFAULT_BP_ID": null,
        "U_EU_FIRST_LOGIN": 1,
        "U_PASS_EXPIRE": null,
        "U_PASS_CHANGE": null,
        "U_REGENERATE": null,
        "U_REGENERATE_L_ID": null,
        "U_REGENERATE_PAYMENTS": null,
        "U_REGENERATE_PAYMENTS_L_ID": null,
        "U_PROV_LEVEL": 10,
        "U_DEGREE_BEHIND": null,
        "U_PROVISIONING": 0,
        "U_CODE_REFERENCES": null,
        "U_BATCH": null,
        "U_VALUATION": null,
        "U_PROVIDER_USER_ID": null,
        "U_PROVIDER_TYPE": "NONE",
        "U_PROVIDER_LABEL": null,
        "U_PROVIDER_ACTIVE": null,
        "U_INFO_MARKETING": null,
        "U_OFF_LIMIT": null,
        "U_LAST_USAGE": null,
        "U_LAST_CHANGE": null,
        "U_DEBTS_GENERATE": 0,
        "U_EXTRA_WORK_DETAIL": 0,
        "U_WORKS_COUNT_STRATEGY": "MINS",
        "U_GROUP_COMP_FID": 0,
        "params": [
            {
                "UP_ID": "0000988048",
                "UP_USER_ID": 1977199,
                "UP_NAME": "param_xjkl",
                "UP_VALID_FROM": "2026-02-26",
                "UP_VALID_TO": null,
                "UP_VALUE": "Id aut libero.",
                "UP_CONTENT": "Dolorem mollitia deleniti nemo. Quia officia est dignissimos neque. Odio veritatis excepturi doloribus delectus fugit qui repudiandae. Est alias tenetur ratione.",
                "UP_CREATED": "2026-02-09 01:15:26",
                "UP_L_ID": "000868"
            }
        ],
        "contact_phone_numbers": [
            {
                "CPN_ID": 1105900,
                "CPN_SUBJ_ID": 1977199,
                "CPN_VALID": 1,
                "CPN_PHONE": 335213199,
                "CPN_L_ID": 4860,
                "CPN_LAST_UPDATE": "2026-02-06 14:48:42"
            }
        ],
        "contact_email_addresses": [
            {
                "CEA_ID": 445987,
                "CEA_SUBJ_ID": 1977199,
                "CEA_VALID": 0,
                "CEA_EMAIL": "[email protected]",
                "CEA_L_ID": 6058,
                "CEA_LAST_UPDATE": "2026-01-17 07:50:12"
            }
        ]
    }
}

Request      

POST api/v3/customers

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Body Parameters

login   string  optional    

Login name of the customer Example: john.doe

password   string  optional    

Password of the customer Example: secret123

type   string     

Type of the customer (S, F, P) Example: S

first_name   string  optional    

First name of the customer Example: John

last_name   string  optional    

Last name of the customer Example: Doe

company   string  optional    

Company name (required for type P) Example: Doe Corp

street   string  optional    

Street address Example: Main Street 1

house_id   string  optional    

House ID or number Example: 12A

city   string  optional    

City of the customer Example: New York

zip   string  optional    

ZIP Code Example: 10001

phones   string[]  optional    

Phone numbers of the customer

emails   string[]  optional    

Email addresses of the customer

comp_id   string  optional    

Company ID (ICO) Example: 12345678

comp_fid   string  optional    

Company Tax ID (DIC) Example: CZ12345678

comp_vatid   string  optional    

Company VAT ID (IC DPH) Example: SK1234567890

active   integer  optional    

Is customer active? 1=yes, 0=no Example: 1

pass_question   string  optional    

Example: architecto

pass_answer   string  optional    

Example: architecto

ptitle   string  optional    

Must not be greater than 255 characters. Example: n

adr2   string  optional    

Must not be greater than 255 characters. Example: g

recipient2   string  optional    

Must not be greater than 255 characters. Example: z

street2   string  optional    

Must not be greater than 255 characters. Example: m

house_id2   string  optional    

Must not be greater than 15 characters. Example: i

city2   string  optional    

Must not be greater than 255 characters. Example: y

zip2   string  optional    

Must not be greater than 6 characters. Example: vdlj

adr3   string  optional    

Must not be greater than 255 characters. Example: n

recipient3   string  optional    

Must not be greater than 255 characters. Example: i

street3   string  optional    

Must not be greater than 255 characters. Example: k

house_id3   string  optional    

Must not be greater than 15 characters. Example: h

city3   string  optional    

Must not be greater than 255 characters. Example: w

zip3   string  optional    

Must not be greater than 6 characters. Example: aykc

fax   string  optional    

Example: architecto

personal_number   string  optional    

Example: architecto

birthday   string  optional    

Must be a valid date. Example: 2026-04-15T14:55:09

info_mail   integer  optional    

Example: 16

info_post   integer  optional    

Example: 16

info_sms   integer  optional    

Example: 16

premises   string  optional    

Example: architecto

agr_name   string  optional    

Example: architecto

varsym   string  optional    

Example: architecto

sipo   string  optional    

Example: architecto

account_pre_num   string  optional    

Example: architecto

account_num   string  optional    

Example: architecto

account_bank   string  optional    

Example: architecto

account_specsym   string  optional    

Example: architecto

note_user   string  optional    

Example: architecto

note_internal   string  optional    

Example: architecto

note_invoice   string  optional    

Example: architecto

flat   string  optional    

Example: architecto

flat_type   string  optional    

Example: architecto

tech_loc   string  optional    

Example: architecto

tech_name   string  optional    

Example: architecto

codename   string  optional    

Example: architecto

log_level   integer  optional    

Example: 16

document_number   string  optional    

Example: architecto

statutary   string  optional    

Example: architecto

default_bp_id   integer  optional    

Example: 16

eu_first_login   integer  optional    

Example: 16

activation   string  optional    

Example: architecto

prov_level   integer  optional    

Example: 16

degree_behind   string  optional    

Example: architecto

account_attach   string  optional    

Example: architecto

code_references   string  optional    

Example: architecto

valuation   string  optional    

Example: architecto

uc_id   integer  optional    

Example: 16

us_id   integer  optional    

Example: 16

ua_id   integer  optional    

Example: 16

uc_id2   integer  optional    

Example: 16

us_id2   integer  optional    

Example: 16

ua_id2   integer  optional    

Example: 16

uc_id3   integer  optional    

Example: 16

us_id3   integer  optional    

Example: 16

ua_id3   integer  optional    

Example: 16

bp_ids   string  optional    

Example: architecto

provider_user_id   integer  optional    

Example: 16

cl_id   integer  optional    

Example: 16

cl_id2   integer  optional    

Example: 16

cl_id3   integer  optional    

Example: 16

iban   string  optional    

Example: architecto

info_marketing   integer  optional    

Example: 16

vat_registered   integer  optional    

Example: 16

vat_registered_from   string  optional    

Must be a valid date. Example: 2026-04-15T14:55:09

group_comp_fid   string  optional    

Example: architecto

params   object[]  optional    
name   string  optional    

This field is required when params is present. Example: architecto

value   string  optional    

This field is required when params is present. Example: architecto

consent   integer  optional    

Example: 16

Response

Response Fields

data   object     
USER_ID   integer     

Unique customer identifier (primary key).

LOGIN   string     

Login name for the customer portal (SelfCare).

PASSWORD   string     

Password hash (MD5, 32 chars).

U_PASS_QUESTION   integer     

Password recovery question number (a code list entry ID).

U_PASS_ANSWER   string     

Answer to the password recovery question.

U_EU_FIRST_LOGIN   integer     

Flag indicating the SelfCare account has not been authorized yet. 1 = not yet authorized.

U_PASS_EXPIRE   integer     

Password expiration setting (days).

U_PASS_CHANGE   string     

Datetime of the last password change.

TYPE   string     

Customer type. 'S' = private person, 'F' = self-employed / natural person with business, 'P' = legal entity / company.

Must be one of:
  • S
  • F
  • P
P_TITLE   string     

Title before name (e.g. Ing., Mgr.).

U_DEGREE_BEHIND   string     

Academic degree after name (e.g. Ph.D., CSc.).

FIRST_NAME   string     

Customer's first name.

LAST_NAME   string     

Customer's last name (surname).

COMPANY   string     

Company or organization name. Used as display name for TYPE 'P' and 'F'.

U_BIRTHDAY   string     

Date of birth (YYYY-MM-DD).

U_PERSONAL_NUMBER   string     

Personal identification number (rodné číslo / birth number).

U_BIRTH_NUMBER   string     

Birth number (rodné číslo). Alternative field for personal identification.

PERSON_ID_NUMBER   string     

National personal ID number.

U_PERSON_ID   string     

Person identifier (up to 12 chars).

U_DOCUMENT_NUMBER   string     

Identity document number (e.g. national ID card number).

COMP_ID   string     

Company registration number (IČO).

COMP_FID   string     

Tax identification number (DIČ).

U_COMP_VATID   string     

VAT identification number (IČ DPH).

U_GROUP_COMP_FID   integer     

Flag indicating a group tax ID (skupinové DIČ). 1 = group DIČ is used.

U_STATUTARY   string     

Statutory body / authorized signatory of the contract.

STREET   string     

Primary address — street name.

HOUSE_ID   string     

Primary address — house number (číslo popisné).

FLAT   string     

Primary address — flat/apartment number.

CITY   string     

Primary address — city.

ZIP   string     

Primary address — postal code (PSČ).

U_UC_ID   integer     

Primary address — UIR registry city ID.

U_US_ID   integer     

Primary address — UIR registry street ID.

U_UA_ID   integer     

Primary address — UIR registry address ID.

U_CL_ID   integer     

Primary address — code list reference ID.

ADR2   string     

Shipping/mailing address mode. 'AS1' = same as primary address, 'OWN' = custom address.

Must be one of:
  • AS1
  • OWN
U_RECIPIENT2   string     

Shipping address — recipient name.

STREET2   string     

Shipping address — street name.

HOUSE_ID2   string     

Shipping address — house number.

CITY2   string     

Shipping address — city.

ZIP2   string     

Shipping address — postal code (PSČ).

U_UC_ID2   integer     

Shipping address — UIR registry city ID.

U_US_ID2   integer     

Shipping address — UIR registry street ID.

U_UA_ID2   integer     

Shipping address — UIR registry address ID.

U_CL_ID2   integer     

Shipping address — code list reference ID.

ADR3   string     

Invoice address mode. 'AS1' = same as primary, 'AS2' = same as shipping, 'OWN' = custom address.

Must be one of:
  • AS1
  • AS2
  • OWN
U_RECIPIENT3   string     

Invoice address — recipient name.

STREET3   string     

Invoice address — street name.

HOUSE_ID3   string     

Invoice address — house number.

CITY3   string     

Invoice address — city.

ZIP3   string     

Invoice address — postal code (PSČ).

U_UC_ID3   integer     

Invoice address — UIR registry city ID.

U_US_ID3   integer     

Invoice address — UIR registry street ID.

U_UA_ID3   integer     

Invoice address — UIR registry address ID.

U_CL_ID3   integer     

Invoice address — code list reference ID.

FAX   string     

Fax number.

INFO_MAIL   integer     

Email notification consent flag. 1 = opted in.

INFO_POST   integer     

Postal (print) notification flag.

U_INFO_SMS   integer     

SMS notification consent flag. 1 = opted in.

U_INFO_MARKETING   integer     

Marketing communication consent flag.

SERVICES   string     

Comma-separated list of service identifiers associated with the customer.

ACTIVATION   string     

Datetime of the customer's initial activation.

U_ACTIVATION_LAST   string     

Datetime of the customer's most recent activation.

DATE_BEGIN   string     

Contract start date (YYYY-MM-DD).

DATE_END   string     

Contract end date (YYYY-MM-DD).

AGR_NAME   string     

Agreement/contract number.

U_ACTIVE   integer     

Active customer flag. 1 = active, 0 = inactive.

CT   integer     

Company/tenant identifier — multi-tenant discriminator.

GROUP_ID   integer     

Customer group identifier.

VAR_SYMBOL   integer     

Variable symbol — unique payment identifier used in bank transfers.

SIPO_NUM   string     

SIPO number — postal payment connector number for recurring payments.

SIPO_DATE_FROM   string     

SIPO effective start datetime.

ACCOUNT_PRE_NUMBER   string     

Bank account prefix number (Czech format).

ACCOUNT_NUMBER   string     

Bank account number.

ACCOUNT_BANK   string     

Bank code (4-digit Czech bank code).

U_IBAN   string     

International Bank Account Number (IBAN).

U_ACCOUNT_ATTACH   integer     

Attachment ID linked to the bank account record.

U_ACCOUNT_SPECSYM   integer     

Specific symbol associated with the bank account.

U_DEFAULT_BP_ID   integer     

Default billing period ID.

U_VALUATION   integer     

Customer valuation in percent. Used for modifying prices in pricelist calculations.

U_DEBTS_GENERATE   integer     

Debts generation flag. 1 = automatic debt generation enabled.

U_OFF_LIMIT   integer     

Off-limit threshold value.

USER_NOTE   string     

Customer-visible note.

INTERNAL_NOTE   string     

Internal note — visible only to operators, not to the customer.

U_INV_NOTE   string     

Note printed on invoices.

NOTE1   string     

Custom note field 1.

NOTE2   string     

Custom note field 2.

NOTE3   string     

Custom note field 3.

NOTE4   string     

Custom note field 4.

NOTE5   string     

Custom note field 5.

NOTE6   string     

Custom note field 6.

NOTE7   string     

Custom note field 7.

NOTE8   string     

Custom note field 8.

SALESMAN   integer     

Sales representative (admin user) ID.

U_PREMISES   integer     

Business premises flag. 1 = customer has associated premises.

U_FLAT_TYPE   string     

Type of flat/premises (e.g. apartment category).

U_TECH_LOC   string     

Technical location identifier.

U_TECH_NAME   string     

Technical name / description of the location.

U_CODENAME   string     

Code identifier used by automated processors (e.g. SMS request handling).

U_CODE_REFERENCES   integer     

Referral/recommendation code (VIP).

U_EXTRA_WORK_DETAIL   integer     

Flag enabling extra work detail tracking.

U_WORKS_COUNT_STRATEGY   string     

Work time counting strategy.

Must be one of:
  • MINS
  • COMM_15
  • COMM_30
  • COMM_60
  • ROUND_15
  • ROUND_30
  • ROUND_60
U_PROV_LEVEL   integer     

Customer trust/provisioning level. Higher values indicate greater trust.

U_PROVISIONING   integer     

Provisioning status.

U_PROVIDER_USER_ID   integer     

User ID of the associated location provider.

U_PROVIDER_TYPE   string     

Provider type classification.

Must be one of:
  • NONE
  • PROVIDER
  • DEFAULT_PROVIDER
U_PROVIDER_LABEL   integer     

Provider label — used as a contract number or identifier when USER_ID range is too large.

U_PROVIDER_ACTIVE   integer     

Flag indicating whether the location provider is active.

LOG_LEVEL   string     

Logging level for this customer.

Must be one of:
  • EMERG
  • ALERT
  • CRIT
  • ERR
  • WARNING
  • NOTICE
  • INFO
  • DEBUG
U_REGENERATE   string     

Timestamp when user-dependent data regeneration started. Cleared after successful regeneration.

U_REGENERATE_L_ID   integer     

Operator ID who triggered the data regeneration.

U_REGENERATE_PAYMENTS   string     

Timestamp when payment data regeneration started.

U_REGENERATE_PAYMENTS_L_ID   integer     

Operator ID who triggered the payment data regeneration.

U_BATCH   string     

Batch processing data.

U_LAST_USAGE   string     

Date of the customer's last service usage (YYYY-MM-DD).

U_LAST_CHANGE   string     

Datetime of the last modification to this customer record.

full_name   string     

Computed display name. For TYPE 'P' returns COMPANY; for TYPE 'F' with COMPANY set returns COMPANY; otherwise returns LAST_NAME + FIRST_NAME.

normalized_address   string     

Full normalized primary address string from the UIR registry (based on U_UA_ID).

normalized_shipping_address   string     

Full normalized shipping address string from the UIR registry (based on U_UA_ID2).

normalized_invoice_address   string     

Full normalized invoice address string from the UIR registry (based on U_UA_ID3).

params   object[]     

Customer parameters — collection of key-value pairs.
UP_ID   integer     

Unique customer parameter record ID.

UP_USER_ID   integer     

Customer ID this parameter belongs to.

UP_NAME   string     

Parameter name (max 30 chars).

UP_VALID_FROM   string     

Date from which this parameter is valid (YYYY-MM-DD).

UP_VALID_TO   string     

Date until which this parameter is valid. Null = no expiry.

UP_VALUE   string     

Parameter value (max 255 chars).

UP_CONTENT   string     

Binary/blob content (base64-encoded). Null when not present.

UP_CREATED   string     

Creation timestamp (YYYY-MM-DD HH:MM:SS).

UP_L_ID   integer     

Login session ID that created this record.

contact_phone_numbers   object[]     

Collection of customer's contact phone numbers.
CPN_ID   integer     

Unique phone number record ID.

CPN_SUBJ_ID   integer     

Customer ID. See GET /v3/customers/{id}.

CPN_VALID   integer     

Validity flag. 1 = active, 0 = inactive.

CPN_PHONE   integer     

Phone number in international format (without leading + or 00).

CPN_L_ID   integer     

ID of the operator who made the last change.

CPN_LAST_UPDATE   string     

Last update datetime (YYYY-MM-DD HH:MM:SS).

contact_email_addresses   object[]     

Collection of customer's contact email addresses.
CEA_ID   integer     

Unique email address record ID.

CEA_SUBJ_ID   integer     

Customer ID. See GET /v3/customers/{id}.

CEA_VALID   integer     

Validity flag. 1 = active, 0 = inactive.

CEA_EMAIL   string     

Email address.

CEA_L_ID   integer     

ID of the operator who made the last change.

CEA_LAST_UPDATE   string     

Last update datetime (YYYY-MM-DD HH:MM:SS).

Get Customer

requires authentication

This endpoint retrieves a specific customer by ID.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/customers/68" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customers/68"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "USER_ID": 1977200,
        "LOGIN": "imclaughlin",
        "PASSWORD": "=NG5a:x&S$hSn",
        "U_PASS_QUESTION": null,
        "U_PASS_ANSWER": "praesentium",
        "TYPE": "S",
        "P_TITLE": null,
        "FIRST_NAME": "Annabelle",
        "LAST_NAME": "Kshlerin",
        "COMPANY": "Hettinger, Nitzsche and Ankunding",
        "STREET": "Verlie Manors",
        "HOUSE_ID": "651",
        "CITY": "Lake Noahberg",
        "ZIP": "40837-",
        "U_UC_ID": null,
        "U_US_ID": null,
        "U_UA_ID": null,
        "U_CL_ID": null,
        "ADR2": null,
        "U_RECIPIENT2": null,
        "STREET2": null,
        "HOUSE_ID2": null,
        "CITY2": null,
        "ZIP2": null,
        "U_UC_ID2": null,
        "U_US_ID2": null,
        "U_UA_ID2": null,
        "U_CL_ID2": null,
        "ADR3": null,
        "U_RECIPIENT3": null,
        "STREET3": null,
        "HOUSE_ID3": null,
        "CITY3": null,
        "ZIP3": null,
        "U_UC_ID3": null,
        "U_US_ID3": null,
        "U_UA_ID3": null,
        "U_CL_ID3": null,
        "FAX": null,
        "SERVICES": "blanditiis",
        "COMP_ID": null,
        "COMP_FID": null,
        "ACTIVATION": "1900-01-01 00:00:00",
        "U_ACTIVATION_LAST": "2026-02-26 18:54:59",
        "INFO_MAIL": 1,
        "INFO_POST": null,
        "USER_NOTE": null,
        "INTERNAL_NOTE": null,
        "CT": "008",
        "FLAT": null,
        "NOTE1": null,
        "NOTE2": null,
        "NOTE3": null,
        "NOTE4": null,
        "NOTE5": null,
        "NOTE6": null,
        "NOTE7": null,
        "NOTE8": null,
        "SIPO_NUM": null,
        "DATE_BEGIN": null,
        "DATE_END": null,
        "SIPO_DATE_FROM": null,
        "GROUP_ID": null,
        "VAR_SYMBOL": null,
        "AGR_NAME": null,
        "PERSON_ID_NUMBER": null,
        "U_BIRTHDAY": null,
        "U_PERSONAL_NUMBER": null,
        "U_DOCUMENT_NUMBER": null,
        "ACCOUNT_PRE_NUMBER": null,
        "ACCOUNT_NUMBER": null,
        "ACCOUNT_BANK": null,
        "U_IBAN": null,
        "U_ACCOUNT_ATTACH": null,
        "U_ACCOUNT_SPECSYM": null,
        "SALESMAN": null,
        "U_BIRTH_NUMBER": null,
        "U_TECH_LOC": null,
        "U_FLAT_TYPE": null,
        "U_TECH_NAME": null,
        "U_PREMISES": 0,
        "U_INV_NOTE": null,
        "U_CODENAME": null,
        "U_ACTIVE": 1,
        "LOG_LEVEL": "INFO",
        "U_INFO_SMS": 0,
        "U_PERSON_ID": null,
        "U_STATUTARY": null,
        "U_COMP_VATID": null,
        "U_DEFAULT_BP_ID": null,
        "U_EU_FIRST_LOGIN": 1,
        "U_PASS_EXPIRE": null,
        "U_PASS_CHANGE": null,
        "U_REGENERATE": null,
        "U_REGENERATE_L_ID": null,
        "U_REGENERATE_PAYMENTS": null,
        "U_REGENERATE_PAYMENTS_L_ID": null,
        "U_PROV_LEVEL": 10,
        "U_DEGREE_BEHIND": null,
        "U_PROVISIONING": 0,
        "U_CODE_REFERENCES": null,
        "U_BATCH": null,
        "U_VALUATION": null,
        "U_PROVIDER_USER_ID": null,
        "U_PROVIDER_TYPE": "NONE",
        "U_PROVIDER_LABEL": null,
        "U_PROVIDER_ACTIVE": null,
        "U_INFO_MARKETING": null,
        "U_OFF_LIMIT": null,
        "U_LAST_USAGE": null,
        "U_LAST_CHANGE": null,
        "U_DEBTS_GENERATE": 0,
        "U_EXTRA_WORK_DETAIL": 0,
        "U_WORKS_COUNT_STRATEGY": "MINS",
        "U_GROUP_COMP_FID": 0,
        "params": [
            {
                "UP_ID": "0000988049",
                "UP_USER_ID": 1977200,
                "UP_NAME": "param_cvip",
                "UP_VALID_FROM": "2026-03-20",
                "UP_VALID_TO": null,
                "UP_VALUE": "Laboriosam est alias.",
                "UP_CONTENT": null,
                "UP_CREATED": "2026-01-25 18:50:08",
                "UP_L_ID": "000425"
            }
        ],
        "contact_phone_numbers": [
            {
                "CPN_ID": 1105901,
                "CPN_SUBJ_ID": 1977200,
                "CPN_VALID": 0,
                "CPN_PHONE": 590549722,
                "CPN_L_ID": 1012,
                "CPN_LAST_UPDATE": "2026-03-03 05:13:59"
            }
        ],
        "contact_email_addresses": [
            {
                "CEA_ID": 445988,
                "CEA_SUBJ_ID": 1977200,
                "CEA_VALID": 1,
                "CEA_EMAIL": "[email protected]",
                "CEA_L_ID": 1846,
                "CEA_LAST_UPDATE": "2026-01-18 08:23:28"
            }
        ]
    }
}

Request      

GET api/v3/customers/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the customer. Example: 68

Response

Response Fields

data   object     
USER_ID   integer     

Unique customer identifier (primary key).

LOGIN   string     

Login name for the customer portal (SelfCare).

PASSWORD   string     

Password hash (MD5, 32 chars).

U_PASS_QUESTION   integer     

Password recovery question number (a code list entry ID).

U_PASS_ANSWER   string     

Answer to the password recovery question.

U_EU_FIRST_LOGIN   integer     

Flag indicating the SelfCare account has not been authorized yet. 1 = not yet authorized.

U_PASS_EXPIRE   integer     

Password expiration setting (days).

U_PASS_CHANGE   string     

Datetime of the last password change.

TYPE   string     

Customer type. 'S' = private person, 'F' = self-employed / natural person with business, 'P' = legal entity / company.

Must be one of:
  • S
  • F
  • P
P_TITLE   string     

Title before name (e.g. Ing., Mgr.).

U_DEGREE_BEHIND   string     

Academic degree after name (e.g. Ph.D., CSc.).

FIRST_NAME   string     

Customer's first name.

LAST_NAME   string     

Customer's last name (surname).

COMPANY   string     

Company or organization name. Used as display name for TYPE 'P' and 'F'.

U_BIRTHDAY   string     

Date of birth (YYYY-MM-DD).

U_PERSONAL_NUMBER   string     

Personal identification number (rodné číslo / birth number).

U_BIRTH_NUMBER   string     

Birth number (rodné číslo). Alternative field for personal identification.

PERSON_ID_NUMBER   string     

National personal ID number.

U_PERSON_ID   string     

Person identifier (up to 12 chars).

U_DOCUMENT_NUMBER   string     

Identity document number (e.g. national ID card number).

COMP_ID   string     

Company registration number (IČO).

COMP_FID   string     

Tax identification number (DIČ).

U_COMP_VATID   string     

VAT identification number (IČ DPH).

U_GROUP_COMP_FID   integer     

Flag indicating a group tax ID (skupinové DIČ). 1 = group DIČ is used.

U_STATUTARY   string     

Statutory body / authorized signatory of the contract.

STREET   string     

Primary address — street name.

HOUSE_ID   string     

Primary address — house number (číslo popisné).

FLAT   string     

Primary address — flat/apartment number.

CITY   string     

Primary address — city.

ZIP   string     

Primary address — postal code (PSČ).

U_UC_ID   integer     

Primary address — UIR registry city ID.

U_US_ID   integer     

Primary address — UIR registry street ID.

U_UA_ID   integer     

Primary address — UIR registry address ID.

U_CL_ID   integer     

Primary address — code list reference ID.

ADR2   string     

Shipping/mailing address mode. 'AS1' = same as primary address, 'OWN' = custom address.

Must be one of:
  • AS1
  • OWN
U_RECIPIENT2   string     

Shipping address — recipient name.

STREET2   string     

Shipping address — street name.

HOUSE_ID2   string     

Shipping address — house number.

CITY2   string     

Shipping address — city.

ZIP2   string     

Shipping address — postal code (PSČ).

U_UC_ID2   integer     

Shipping address — UIR registry city ID.

U_US_ID2   integer     

Shipping address — UIR registry street ID.

U_UA_ID2   integer     

Shipping address — UIR registry address ID.

U_CL_ID2   integer     

Shipping address — code list reference ID.

ADR3   string     

Invoice address mode. 'AS1' = same as primary, 'AS2' = same as shipping, 'OWN' = custom address.

Must be one of:
  • AS1
  • AS2
  • OWN
U_RECIPIENT3   string     

Invoice address — recipient name.

STREET3   string     

Invoice address — street name.

HOUSE_ID3   string     

Invoice address — house number.

CITY3   string     

Invoice address — city.

ZIP3   string     

Invoice address — postal code (PSČ).

U_UC_ID3   integer     

Invoice address — UIR registry city ID.

U_US_ID3   integer     

Invoice address — UIR registry street ID.

U_UA_ID3   integer     

Invoice address — UIR registry address ID.

U_CL_ID3   integer     

Invoice address — code list reference ID.

FAX   string     

Fax number.

INFO_MAIL   integer     

Email notification consent flag. 1 = opted in.

INFO_POST   integer     

Postal (print) notification flag.

U_INFO_SMS   integer     

SMS notification consent flag. 1 = opted in.

U_INFO_MARKETING   integer     

Marketing communication consent flag.

SERVICES   string     

Comma-separated list of service identifiers associated with the customer.

ACTIVATION   string     

Datetime of the customer's initial activation.

U_ACTIVATION_LAST   string     

Datetime of the customer's most recent activation.

DATE_BEGIN   string     

Contract start date (YYYY-MM-DD).

DATE_END   string     

Contract end date (YYYY-MM-DD).

AGR_NAME   string     

Agreement/contract number.

U_ACTIVE   integer     

Active customer flag. 1 = active, 0 = inactive.

CT   integer     

Company/tenant identifier — multi-tenant discriminator.

GROUP_ID   integer     

Customer group identifier.

VAR_SYMBOL   integer     

Variable symbol — unique payment identifier used in bank transfers.

SIPO_NUM   string     

SIPO number — postal payment connector number for recurring payments.

SIPO_DATE_FROM   string     

SIPO effective start datetime.

ACCOUNT_PRE_NUMBER   string     

Bank account prefix number (Czech format).

ACCOUNT_NUMBER   string     

Bank account number.

ACCOUNT_BANK   string     

Bank code (4-digit Czech bank code).

U_IBAN   string     

International Bank Account Number (IBAN).

U_ACCOUNT_ATTACH   integer     

Attachment ID linked to the bank account record.

U_ACCOUNT_SPECSYM   integer     

Specific symbol associated with the bank account.

U_DEFAULT_BP_ID   integer     

Default billing period ID.

U_VALUATION   integer     

Customer valuation in percent. Used for modifying prices in pricelist calculations.

U_DEBTS_GENERATE   integer     

Debts generation flag. 1 = automatic debt generation enabled.

U_OFF_LIMIT   integer     

Off-limit threshold value.

USER_NOTE   string     

Customer-visible note.

INTERNAL_NOTE   string     

Internal note — visible only to operators, not to the customer.

U_INV_NOTE   string     

Note printed on invoices.

NOTE1   string     

Custom note field 1.

NOTE2   string     

Custom note field 2.

NOTE3   string     

Custom note field 3.

NOTE4   string     

Custom note field 4.

NOTE5   string     

Custom note field 5.

NOTE6   string     

Custom note field 6.

NOTE7   string     

Custom note field 7.

NOTE8   string     

Custom note field 8.

SALESMAN   integer     

Sales representative (admin user) ID.

U_PREMISES   integer     

Business premises flag. 1 = customer has associated premises.

U_FLAT_TYPE   string     

Type of flat/premises (e.g. apartment category).

U_TECH_LOC   string     

Technical location identifier.

U_TECH_NAME   string     

Technical name / description of the location.

U_CODENAME   string     

Code identifier used by automated processors (e.g. SMS request handling).

U_CODE_REFERENCES   integer     

Referral/recommendation code (VIP).

U_EXTRA_WORK_DETAIL   integer     

Flag enabling extra work detail tracking.

U_WORKS_COUNT_STRATEGY   string     

Work time counting strategy.

Must be one of:
  • MINS
  • COMM_15
  • COMM_30
  • COMM_60
  • ROUND_15
  • ROUND_30
  • ROUND_60
U_PROV_LEVEL   integer     

Customer trust/provisioning level. Higher values indicate greater trust.

U_PROVISIONING   integer     

Provisioning status.

U_PROVIDER_USER_ID   integer     

User ID of the associated location provider.

U_PROVIDER_TYPE   string     

Provider type classification.

Must be one of:
  • NONE
  • PROVIDER
  • DEFAULT_PROVIDER
U_PROVIDER_LABEL   integer     

Provider label — used as a contract number or identifier when USER_ID range is too large.

U_PROVIDER_ACTIVE   integer     

Flag indicating whether the location provider is active.

LOG_LEVEL   string     

Logging level for this customer.

Must be one of:
  • EMERG
  • ALERT
  • CRIT
  • ERR
  • WARNING
  • NOTICE
  • INFO
  • DEBUG
U_REGENERATE   string     

Timestamp when user-dependent data regeneration started. Cleared after successful regeneration.

U_REGENERATE_L_ID   integer     

Operator ID who triggered the data regeneration.

U_REGENERATE_PAYMENTS   string     

Timestamp when payment data regeneration started.

U_REGENERATE_PAYMENTS_L_ID   integer     

Operator ID who triggered the payment data regeneration.

U_BATCH   string     

Batch processing data.

U_LAST_USAGE   string     

Date of the customer's last service usage (YYYY-MM-DD).

U_LAST_CHANGE   string     

Datetime of the last modification to this customer record.

full_name   string     

Computed display name. For TYPE 'P' returns COMPANY; for TYPE 'F' with COMPANY set returns COMPANY; otherwise returns LAST_NAME + FIRST_NAME.

normalized_address   string     

Full normalized primary address string from the UIR registry (based on U_UA_ID).

normalized_shipping_address   string     

Full normalized shipping address string from the UIR registry (based on U_UA_ID2).

normalized_invoice_address   string     

Full normalized invoice address string from the UIR registry (based on U_UA_ID3).

params   object[]     

Customer parameters — collection of key-value pairs.
UP_ID   integer     

Unique customer parameter record ID.

UP_USER_ID   integer     

Customer ID this parameter belongs to.

UP_NAME   string     

Parameter name (max 30 chars).

UP_VALID_FROM   string     

Date from which this parameter is valid (YYYY-MM-DD).

UP_VALID_TO   string     

Date until which this parameter is valid. Null = no expiry.

UP_VALUE   string     

Parameter value (max 255 chars).

UP_CONTENT   string     

Binary/blob content (base64-encoded). Null when not present.

UP_CREATED   string     

Creation timestamp (YYYY-MM-DD HH:MM:SS).

UP_L_ID   integer     

Login session ID that created this record.

contact_phone_numbers   object[]     

Collection of customer's contact phone numbers.
CPN_ID   integer     

Unique phone number record ID.

CPN_SUBJ_ID   integer     

Customer ID. See GET /v3/customers/{id}.

CPN_VALID   integer     

Validity flag. 1 = active, 0 = inactive.

CPN_PHONE   integer     

Phone number in international format (without leading + or 00).

CPN_L_ID   integer     

ID of the operator who made the last change.

CPN_LAST_UPDATE   string     

Last update datetime (YYYY-MM-DD HH:MM:SS).

contact_email_addresses   object[]     

Collection of customer's contact email addresses.
CEA_ID   integer     

Unique email address record ID.

CEA_SUBJ_ID   integer     

Customer ID. See GET /v3/customers/{id}.

CEA_VALID   integer     

Validity flag. 1 = active, 0 = inactive.

CEA_EMAIL   string     

Email address.

CEA_L_ID   integer     

ID of the operator who made the last change.

CEA_LAST_UPDATE   string     

Last update datetime (YYYY-MM-DD HH:MM:SS).

Update Customer

requires authentication

This endpoint updates an existing customer.

Example request:
curl --request PUT \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customers/68" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"login\": \"john.doe\",
    \"password\": \"secret123\",
    \"type\": \"S\",
    \"first_name\": \"John\",
    \"last_name\": \"Doe\",
    \"company\": \"Doe Corp\",
    \"street\": \"Main Street 1\",
    \"house_id\": \"12A\",
    \"city\": \"New York\",
    \"zip\": \"10001\",
    \"comp_id\": \"12345678\",
    \"comp_fid\": \"CZ12345678\",
    \"comp_vatid\": \"SK1234567890\",
    \"active\": 1,
    \"pass_question\": \"architecto\",
    \"pass_answer\": \"architecto\",
    \"ptitle\": \"n\",
    \"adr2\": \"g\",
    \"recipient2\": \"z\",
    \"street2\": \"m\",
    \"house_id2\": \"i\",
    \"city2\": \"y\",
    \"zip2\": \"vdlj\",
    \"adr3\": \"n\",
    \"recipient3\": \"i\",
    \"street3\": \"k\",
    \"house_id3\": \"h\",
    \"city3\": \"w\",
    \"zip3\": \"aykc\",
    \"fax\": \"architecto\",
    \"personal_number\": \"architecto\",
    \"birthday\": \"2026-04-15T14:55:09\",
    \"info_mail\": 16,
    \"info_post\": 16,
    \"info_sms\": 16,
    \"premises\": \"architecto\",
    \"agr_name\": \"architecto\",
    \"varsym\": \"architecto\",
    \"sipo\": \"architecto\",
    \"account_pre_num\": \"architecto\",
    \"account_num\": \"architecto\",
    \"account_bank\": \"architecto\",
    \"account_specsym\": \"architecto\",
    \"note_user\": \"architecto\",
    \"note_internal\": \"architecto\",
    \"note_invoice\": \"architecto\",
    \"flat\": \"architecto\",
    \"flat_type\": \"architecto\",
    \"tech_loc\": \"architecto\",
    \"tech_name\": \"architecto\",
    \"codename\": \"architecto\",
    \"log_level\": 16,
    \"document_number\": \"architecto\",
    \"statutary\": \"architecto\",
    \"default_bp_id\": 16,
    \"eu_first_login\": 16,
    \"activation\": \"architecto\",
    \"prov_level\": 16,
    \"degree_behind\": \"architecto\",
    \"account_attach\": \"architecto\",
    \"code_references\": \"architecto\",
    \"valuation\": \"architecto\",
    \"uc_id\": 16,
    \"us_id\": 16,
    \"ua_id\": 16,
    \"uc_id2\": 16,
    \"us_id2\": 16,
    \"ua_id2\": 16,
    \"uc_id3\": 16,
    \"us_id3\": 16,
    \"ua_id3\": 16,
    \"bp_ids\": \"architecto\",
    \"provider_user_id\": 16,
    \"cl_id\": 16,
    \"cl_id2\": 16,
    \"cl_id3\": 16,
    \"iban\": \"architecto\",
    \"info_marketing\": 16,
    \"vat_registered\": 16,
    \"vat_registered_from\": \"2026-04-15T14:55:09\",
    \"group_comp_fid\": \"architecto\",
    \"consent\": 16
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customers/68"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "login": "john.doe",
    "password": "secret123",
    "type": "S",
    "first_name": "John",
    "last_name": "Doe",
    "company": "Doe Corp",
    "street": "Main Street 1",
    "house_id": "12A",
    "city": "New York",
    "zip": "10001",
    "comp_id": "12345678",
    "comp_fid": "CZ12345678",
    "comp_vatid": "SK1234567890",
    "active": 1,
    "pass_question": "architecto",
    "pass_answer": "architecto",
    "ptitle": "n",
    "adr2": "g",
    "recipient2": "z",
    "street2": "m",
    "house_id2": "i",
    "city2": "y",
    "zip2": "vdlj",
    "adr3": "n",
    "recipient3": "i",
    "street3": "k",
    "house_id3": "h",
    "city3": "w",
    "zip3": "aykc",
    "fax": "architecto",
    "personal_number": "architecto",
    "birthday": "2026-04-15T14:55:09",
    "info_mail": 16,
    "info_post": 16,
    "info_sms": 16,
    "premises": "architecto",
    "agr_name": "architecto",
    "varsym": "architecto",
    "sipo": "architecto",
    "account_pre_num": "architecto",
    "account_num": "architecto",
    "account_bank": "architecto",
    "account_specsym": "architecto",
    "note_user": "architecto",
    "note_internal": "architecto",
    "note_invoice": "architecto",
    "flat": "architecto",
    "flat_type": "architecto",
    "tech_loc": "architecto",
    "tech_name": "architecto",
    "codename": "architecto",
    "log_level": 16,
    "document_number": "architecto",
    "statutary": "architecto",
    "default_bp_id": 16,
    "eu_first_login": 16,
    "activation": "architecto",
    "prov_level": 16,
    "degree_behind": "architecto",
    "account_attach": "architecto",
    "code_references": "architecto",
    "valuation": "architecto",
    "uc_id": 16,
    "us_id": 16,
    "ua_id": 16,
    "uc_id2": 16,
    "us_id2": 16,
    "ua_id2": 16,
    "uc_id3": 16,
    "us_id3": 16,
    "ua_id3": 16,
    "bp_ids": "architecto",
    "provider_user_id": 16,
    "cl_id": 16,
    "cl_id2": 16,
    "cl_id3": 16,
    "iban": "architecto",
    "info_marketing": 16,
    "vat_registered": 16,
    "vat_registered_from": "2026-04-15T14:55:09",
    "group_comp_fid": "architecto",
    "consent": 16
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "data": {
        "USER_ID": 1977201,
        "LOGIN": "rempel.chadrick",
        "PASSWORD": "BNvYgxwmi/#iw/kX",
        "U_PASS_QUESTION": 2,
        "U_PASS_ANSWER": "incidunt",
        "TYPE": "S",
        "P_TITLE": "Dr.",
        "FIRST_NAME": "Marcelo",
        "LAST_NAME": "Predovic",
        "COMPANY": "McLaughlin and Sons",
        "STREET": "Leffler Ridges",
        "HOUSE_ID": "9947",
        "CITY": "Lefflerhaven",
        "ZIP": "47809",
        "U_UC_ID": null,
        "U_US_ID": null,
        "U_UA_ID": null,
        "U_CL_ID": null,
        "ADR2": null,
        "U_RECIPIENT2": null,
        "STREET2": null,
        "HOUSE_ID2": null,
        "CITY2": null,
        "ZIP2": null,
        "U_UC_ID2": null,
        "U_US_ID2": null,
        "U_UA_ID2": null,
        "U_CL_ID2": null,
        "ADR3": null,
        "U_RECIPIENT3": null,
        "STREET3": null,
        "HOUSE_ID3": null,
        "CITY3": null,
        "ZIP3": null,
        "U_UC_ID3": null,
        "U_US_ID3": null,
        "U_UA_ID3": null,
        "U_CL_ID3": null,
        "FAX": null,
        "SERVICES": "adipisci",
        "COMP_ID": null,
        "COMP_FID": null,
        "ACTIVATION": "1900-01-01 00:00:00",
        "U_ACTIVATION_LAST": "2026-03-18 04:16:43",
        "INFO_MAIL": 1,
        "INFO_POST": null,
        "USER_NOTE": null,
        "INTERNAL_NOTE": null,
        "CT": "005",
        "FLAT": null,
        "NOTE1": null,
        "NOTE2": null,
        "NOTE3": null,
        "NOTE4": null,
        "NOTE5": null,
        "NOTE6": null,
        "NOTE7": null,
        "NOTE8": null,
        "SIPO_NUM": null,
        "DATE_BEGIN": null,
        "DATE_END": null,
        "SIPO_DATE_FROM": null,
        "GROUP_ID": null,
        "VAR_SYMBOL": null,
        "AGR_NAME": null,
        "PERSON_ID_NUMBER": null,
        "U_BIRTHDAY": null,
        "U_PERSONAL_NUMBER": null,
        "U_DOCUMENT_NUMBER": null,
        "ACCOUNT_PRE_NUMBER": null,
        "ACCOUNT_NUMBER": null,
        "ACCOUNT_BANK": null,
        "U_IBAN": null,
        "U_ACCOUNT_ATTACH": null,
        "U_ACCOUNT_SPECSYM": null,
        "SALESMAN": null,
        "U_BIRTH_NUMBER": null,
        "U_TECH_LOC": null,
        "U_FLAT_TYPE": null,
        "U_TECH_NAME": null,
        "U_PREMISES": 0,
        "U_INV_NOTE": null,
        "U_CODENAME": null,
        "U_ACTIVE": 1,
        "LOG_LEVEL": "INFO",
        "U_INFO_SMS": 0,
        "U_PERSON_ID": null,
        "U_STATUTARY": null,
        "U_COMP_VATID": null,
        "U_DEFAULT_BP_ID": null,
        "U_EU_FIRST_LOGIN": 1,
        "U_PASS_EXPIRE": null,
        "U_PASS_CHANGE": null,
        "U_REGENERATE": null,
        "U_REGENERATE_L_ID": null,
        "U_REGENERATE_PAYMENTS": null,
        "U_REGENERATE_PAYMENTS_L_ID": null,
        "U_PROV_LEVEL": 10,
        "U_DEGREE_BEHIND": null,
        "U_PROVISIONING": 0,
        "U_CODE_REFERENCES": null,
        "U_BATCH": null,
        "U_VALUATION": null,
        "U_PROVIDER_USER_ID": null,
        "U_PROVIDER_TYPE": "NONE",
        "U_PROVIDER_LABEL": null,
        "U_PROVIDER_ACTIVE": null,
        "U_INFO_MARKETING": null,
        "U_OFF_LIMIT": null,
        "U_LAST_USAGE": null,
        "U_LAST_CHANGE": null,
        "U_DEBTS_GENERATE": 0,
        "U_EXTRA_WORK_DETAIL": 0,
        "U_WORKS_COUNT_STRATEGY": "MINS",
        "U_GROUP_COMP_FID": 0,
        "params": [
            {
                "UP_ID": "0000988050",
                "UP_USER_ID": 1977201,
                "UP_NAME": "param_klqp",
                "UP_VALID_FROM": "2026-04-08",
                "UP_VALID_TO": null,
                "UP_VALUE": "Libero aliquam veniam corporis.",
                "UP_CONTENT": "Nemo odit quia officia est dignissimos. Blanditiis odio veritatis excepturi doloribus delectus fugit. Repudiandae laboriosam est alias tenetur ratione.",
                "UP_CREATED": "2026-02-09 01:15:26",
                "UP_L_ID": "000868"
            }
        ],
        "contact_phone_numbers": [
            {
                "CPN_ID": 1105902,
                "CPN_SUBJ_ID": 1977201,
                "CPN_VALID": 1,
                "CPN_PHONE": 335213199,
                "CPN_L_ID": 4860,
                "CPN_LAST_UPDATE": "2026-02-06 14:48:42"
            }
        ],
        "contact_email_addresses": [
            {
                "CEA_ID": 445989,
                "CEA_SUBJ_ID": 1977201,
                "CEA_VALID": 0,
                "CEA_EMAIL": "[email protected]",
                "CEA_L_ID": 2602,
                "CEA_LAST_UPDATE": "2026-01-28 18:29:42"
            }
        ]
    }
}

Request      

PUT api/v3/customers/{id}

PATCH api/v3/customers/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the customer. Example: 68

Body Parameters

login   string  optional    

Login name of the customer Example: john.doe

password   string  optional    

Password of the customer Example: secret123

type   string  optional    

Type of the customer (S, F, P) Example: S

first_name   string  optional    

First name of the customer Example: John

last_name   string  optional    

Last name of the customer Example: Doe

company   string  optional    

Company name Example: Doe Corp

street   string  optional    

Street address Example: Main Street 1

house_id   string  optional    

House ID or number Example: 12A

city   string  optional    

City of the customer Example: New York

zip   string  optional    

ZIP Code Example: 10001

comp_id   string  optional    

Company ID (ICO) Example: 12345678

comp_fid   string  optional    

Company Tax ID (DIC) Example: CZ12345678

comp_vatid   string  optional    

Company VAT ID (IC DPH) Example: SK1234567890

active   integer  optional    

Is customer active? 1=yes, 0=no, -1=deleted Example: 1

pass_question   string  optional    

Example: architecto

pass_answer   string  optional    

Example: architecto

ptitle   string  optional    

Must not be greater than 255 characters. Example: n

adr2   string  optional    

Must not be greater than 255 characters. Example: g

recipient2   string  optional    

Must not be greater than 255 characters. Example: z

street2   string  optional    

Must not be greater than 255 characters. Example: m

house_id2   string  optional    

Must not be greater than 15 characters. Example: i

city2   string  optional    

Must not be greater than 255 characters. Example: y

zip2   string  optional    

Must not be greater than 6 characters. Example: vdlj

adr3   string  optional    

Must not be greater than 255 characters. Example: n

recipient3   string  optional    

Must not be greater than 255 characters. Example: i

street3   string  optional    

Must not be greater than 255 characters. Example: k

house_id3   string  optional    

Must not be greater than 15 characters. Example: h

city3   string  optional    

Must not be greater than 255 characters. Example: w

zip3   string  optional    

Must not be greater than 6 characters. Example: aykc

fax   string  optional    

Example: architecto

personal_number   string  optional    

Example: architecto

birthday   string  optional    

Must be a valid date. Example: 2026-04-15T14:55:09

info_mail   integer  optional    

Example: 16

info_post   integer  optional    

Example: 16

info_sms   integer  optional    

Example: 16

premises   string  optional    

Example: architecto

agr_name   string  optional    

Example: architecto

varsym   string  optional    

Example: architecto

sipo   string  optional    

Example: architecto

account_pre_num   string  optional    

Example: architecto

account_num   string  optional    

Example: architecto

account_bank   string  optional    

Example: architecto

account_specsym   string  optional    

Example: architecto

note_user   string  optional    

Example: architecto

note_internal   string  optional    

Example: architecto

note_invoice   string  optional    

Example: architecto

flat   string  optional    

Example: architecto

flat_type   string  optional    

Example: architecto

tech_loc   string  optional    

Example: architecto

tech_name   string  optional    

Example: architecto

codename   string  optional    

Example: architecto

log_level   integer  optional    

Example: 16

document_number   string  optional    

Example: architecto

statutary   string  optional    

Example: architecto

default_bp_id   integer  optional    

Example: 16

eu_first_login   integer  optional    

Example: 16

activation   string  optional    

Example: architecto

prov_level   integer  optional    

Example: 16

degree_behind   string  optional    

Example: architecto

account_attach   string  optional    

Example: architecto

code_references   string  optional    

Example: architecto

valuation   string  optional    

Example: architecto

uc_id   integer  optional    

Example: 16

us_id   integer  optional    

Example: 16

ua_id   integer  optional    

Example: 16

uc_id2   integer  optional    

Example: 16

us_id2   integer  optional    

Example: 16

ua_id2   integer  optional    

Example: 16

uc_id3   integer  optional    

Example: 16

us_id3   integer  optional    

Example: 16

ua_id3   integer  optional    

Example: 16

bp_ids   string  optional    

Example: architecto

provider_user_id   integer  optional    

Example: 16

cl_id   integer  optional    

Example: 16

cl_id2   integer  optional    

Example: 16

cl_id3   integer  optional    

Example: 16

iban   string  optional    

Example: architecto

info_marketing   integer  optional    

Example: 16

vat_registered   integer  optional    

Example: 16

vat_registered_from   string  optional    

Must be a valid date. Example: 2026-04-15T14:55:09

group_comp_fid   string  optional    

Example: architecto

consent   integer  optional    

Example: 16

Response

Response Fields

data   object     
USER_ID   integer     

Unique customer identifier (primary key).

LOGIN   string     

Login name for the customer portal (SelfCare).

PASSWORD   string     

Password hash (MD5, 32 chars).

U_PASS_QUESTION   integer     

Password recovery question number (a code list entry ID).

U_PASS_ANSWER   string     

Answer to the password recovery question.

U_EU_FIRST_LOGIN   integer     

Flag indicating the SelfCare account has not been authorized yet. 1 = not yet authorized.

U_PASS_EXPIRE   integer     

Password expiration setting (days).

U_PASS_CHANGE   string     

Datetime of the last password change.

TYPE   string     

Customer type. 'S' = private person, 'F' = self-employed / natural person with business, 'P' = legal entity / company.

Must be one of:
  • S
  • F
  • P
P_TITLE   string     

Title before name (e.g. Ing., Mgr.).

U_DEGREE_BEHIND   string     

Academic degree after name (e.g. Ph.D., CSc.).

FIRST_NAME   string     

Customer's first name.

LAST_NAME   string     

Customer's last name (surname).

COMPANY   string     

Company or organization name. Used as display name for TYPE 'P' and 'F'.

U_BIRTHDAY   string     

Date of birth (YYYY-MM-DD).

U_PERSONAL_NUMBER   string     

Personal identification number (rodné číslo / birth number).

U_BIRTH_NUMBER   string     

Birth number (rodné číslo). Alternative field for personal identification.

PERSON_ID_NUMBER   string     

National personal ID number.

U_PERSON_ID   string     

Person identifier (up to 12 chars).

U_DOCUMENT_NUMBER   string     

Identity document number (e.g. national ID card number).

COMP_ID   string     

Company registration number (IČO).

COMP_FID   string     

Tax identification number (DIČ).

U_COMP_VATID   string     

VAT identification number (IČ DPH).

U_GROUP_COMP_FID   integer     

Flag indicating a group tax ID (skupinové DIČ). 1 = group DIČ is used.

U_STATUTARY   string     

Statutory body / authorized signatory of the contract.

STREET   string     

Primary address — street name.

HOUSE_ID   string     

Primary address — house number (číslo popisné).

FLAT   string     

Primary address — flat/apartment number.

CITY   string     

Primary address — city.

ZIP   string     

Primary address — postal code (PSČ).

U_UC_ID   integer     

Primary address — UIR registry city ID.

U_US_ID   integer     

Primary address — UIR registry street ID.

U_UA_ID   integer     

Primary address — UIR registry address ID.

U_CL_ID   integer     

Primary address — code list reference ID.

ADR2   string     

Shipping/mailing address mode. 'AS1' = same as primary address, 'OWN' = custom address.

Must be one of:
  • AS1
  • OWN
U_RECIPIENT2   string     

Shipping address — recipient name.

STREET2   string     

Shipping address — street name.

HOUSE_ID2   string     

Shipping address — house number.

CITY2   string     

Shipping address — city.

ZIP2   string     

Shipping address — postal code (PSČ).

U_UC_ID2   integer     

Shipping address — UIR registry city ID.

U_US_ID2   integer     

Shipping address — UIR registry street ID.

U_UA_ID2   integer     

Shipping address — UIR registry address ID.

U_CL_ID2   integer     

Shipping address — code list reference ID.

ADR3   string     

Invoice address mode. 'AS1' = same as primary, 'AS2' = same as shipping, 'OWN' = custom address.

Must be one of:
  • AS1
  • AS2
  • OWN
U_RECIPIENT3   string     

Invoice address — recipient name.

STREET3   string     

Invoice address — street name.

HOUSE_ID3   string     

Invoice address — house number.

CITY3   string     

Invoice address — city.

ZIP3   string     

Invoice address — postal code (PSČ).

U_UC_ID3   integer     

Invoice address — UIR registry city ID.

U_US_ID3   integer     

Invoice address — UIR registry street ID.

U_UA_ID3   integer     

Invoice address — UIR registry address ID.

U_CL_ID3   integer     

Invoice address — code list reference ID.

FAX   string     

Fax number.

INFO_MAIL   integer     

Email notification consent flag. 1 = opted in.

INFO_POST   integer     

Postal (print) notification flag.

U_INFO_SMS   integer     

SMS notification consent flag. 1 = opted in.

U_INFO_MARKETING   integer     

Marketing communication consent flag.

SERVICES   string     

Comma-separated list of service identifiers associated with the customer.

ACTIVATION   string     

Datetime of the customer's initial activation.

U_ACTIVATION_LAST   string     

Datetime of the customer's most recent activation.

DATE_BEGIN   string     

Contract start date (YYYY-MM-DD).

DATE_END   string     

Contract end date (YYYY-MM-DD).

AGR_NAME   string     

Agreement/contract number.

U_ACTIVE   integer     

Active customer flag. 1 = active, 0 = inactive.

CT   integer     

Company/tenant identifier — multi-tenant discriminator.

GROUP_ID   integer     

Customer group identifier.

VAR_SYMBOL   integer     

Variable symbol — unique payment identifier used in bank transfers.

SIPO_NUM   string     

SIPO number — postal payment connector number for recurring payments.

SIPO_DATE_FROM   string     

SIPO effective start datetime.

ACCOUNT_PRE_NUMBER   string     

Bank account prefix number (Czech format).

ACCOUNT_NUMBER   string     

Bank account number.

ACCOUNT_BANK   string     

Bank code (4-digit Czech bank code).

U_IBAN   string     

International Bank Account Number (IBAN).

U_ACCOUNT_ATTACH   integer     

Attachment ID linked to the bank account record.

U_ACCOUNT_SPECSYM   integer     

Specific symbol associated with the bank account.

U_DEFAULT_BP_ID   integer     

Default billing period ID.

U_VALUATION   integer     

Customer valuation in percent. Used for modifying prices in pricelist calculations.

U_DEBTS_GENERATE   integer     

Debts generation flag. 1 = automatic debt generation enabled.

U_OFF_LIMIT   integer     

Off-limit threshold value.

USER_NOTE   string     

Customer-visible note.

INTERNAL_NOTE   string     

Internal note — visible only to operators, not to the customer.

U_INV_NOTE   string     

Note printed on invoices.

NOTE1   string     

Custom note field 1.

NOTE2   string     

Custom note field 2.

NOTE3   string     

Custom note field 3.

NOTE4   string     

Custom note field 4.

NOTE5   string     

Custom note field 5.

NOTE6   string     

Custom note field 6.

NOTE7   string     

Custom note field 7.

NOTE8   string     

Custom note field 8.

SALESMAN   integer     

Sales representative (admin user) ID.

U_PREMISES   integer     

Business premises flag. 1 = customer has associated premises.

U_FLAT_TYPE   string     

Type of flat/premises (e.g. apartment category).

U_TECH_LOC   string     

Technical location identifier.

U_TECH_NAME   string     

Technical name / description of the location.

U_CODENAME   string     

Code identifier used by automated processors (e.g. SMS request handling).

U_CODE_REFERENCES   integer     

Referral/recommendation code (VIP).

U_EXTRA_WORK_DETAIL   integer     

Flag enabling extra work detail tracking.

U_WORKS_COUNT_STRATEGY   string     

Work time counting strategy.

Must be one of:
  • MINS
  • COMM_15
  • COMM_30
  • COMM_60
  • ROUND_15
  • ROUND_30
  • ROUND_60
U_PROV_LEVEL   integer     

Customer trust/provisioning level. Higher values indicate greater trust.

U_PROVISIONING   integer     

Provisioning status.

U_PROVIDER_USER_ID   integer     

User ID of the associated location provider.

U_PROVIDER_TYPE   string     

Provider type classification.

Must be one of:
  • NONE
  • PROVIDER
  • DEFAULT_PROVIDER
U_PROVIDER_LABEL   integer     

Provider label — used as a contract number or identifier when USER_ID range is too large.

U_PROVIDER_ACTIVE   integer     

Flag indicating whether the location provider is active.

LOG_LEVEL   string     

Logging level for this customer.

Must be one of:
  • EMERG
  • ALERT
  • CRIT
  • ERR
  • WARNING
  • NOTICE
  • INFO
  • DEBUG
U_REGENERATE   string     

Timestamp when user-dependent data regeneration started. Cleared after successful regeneration.

U_REGENERATE_L_ID   integer     

Operator ID who triggered the data regeneration.

U_REGENERATE_PAYMENTS   string     

Timestamp when payment data regeneration started.

U_REGENERATE_PAYMENTS_L_ID   integer     

Operator ID who triggered the payment data regeneration.

U_BATCH   string     

Batch processing data.

U_LAST_USAGE   string     

Date of the customer's last service usage (YYYY-MM-DD).

U_LAST_CHANGE   string     

Datetime of the last modification to this customer record.

full_name   string     

Computed display name. For TYPE 'P' returns COMPANY; for TYPE 'F' with COMPANY set returns COMPANY; otherwise returns LAST_NAME + FIRST_NAME.

normalized_address   string     

Full normalized primary address string from the UIR registry (based on U_UA_ID).

normalized_shipping_address   string     

Full normalized shipping address string from the UIR registry (based on U_UA_ID2).

normalized_invoice_address   string     

Full normalized invoice address string from the UIR registry (based on U_UA_ID3).

params   object[]     

Customer parameters — collection of key-value pairs.
UP_ID   integer     

Unique customer parameter record ID.

UP_USER_ID   integer     

Customer ID this parameter belongs to.

UP_NAME   string     

Parameter name (max 30 chars).

UP_VALID_FROM   string     

Date from which this parameter is valid (YYYY-MM-DD).

UP_VALID_TO   string     

Date until which this parameter is valid. Null = no expiry.

UP_VALUE   string     

Parameter value (max 255 chars).

UP_CONTENT   string     

Binary/blob content (base64-encoded). Null when not present.

UP_CREATED   string     

Creation timestamp (YYYY-MM-DD HH:MM:SS).

UP_L_ID   integer     

Login session ID that created this record.

contact_phone_numbers   object[]     

Collection of customer's contact phone numbers.
CPN_ID   integer     

Unique phone number record ID.

CPN_SUBJ_ID   integer     

Customer ID. See GET /v3/customers/{id}.

CPN_VALID   integer     

Validity flag. 1 = active, 0 = inactive.

CPN_PHONE   integer     

Phone number in international format (without leading + or 00).

CPN_L_ID   integer     

ID of the operator who made the last change.

CPN_LAST_UPDATE   string     

Last update datetime (YYYY-MM-DD HH:MM:SS).

contact_email_addresses   object[]     

Collection of customer's contact email addresses.
CEA_ID   integer     

Unique email address record ID.

CEA_SUBJ_ID   integer     

Customer ID. See GET /v3/customers/{id}.

CEA_VALID   integer     

Validity flag. 1 = active, 0 = inactive.

CEA_EMAIL   string     

Email address.

CEA_L_ID   integer     

ID of the operator who made the last change.

CEA_LAST_UPDATE   string     

Last update datetime (YYYY-MM-DD HH:MM:SS).

Delete Customer

requires authentication

This endpoint deletes a customer.

Example request:
curl --request DELETE \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customers/68" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/customers/68"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

Example response (204):

Empty response

Request      

DELETE api/v3/customers/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the customer. Example: 68

Device Interfaces

List Device Interfaces

requires authentication

Retrieve a paginated list of physical network interfaces for a specific device.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/devices/48/interfaces" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/devices/48/interfaces"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "NPI_ID": 3312964,
            "NPI_N_ID": 353,
            "NPI_TYPE": 1562,
            "NPI_NAME": "ethf",
            "NPI_L_ID": 657,
            "NPI_CREATED": "2026-01-23 07:25:02",
            "NPI_CHANGED": null,
            "NPI_NOTE": ""
        },
        {
            "NPI_ID": 3312965,
            "NPI_N_ID": 353,
            "NPI_TYPE": 1411,
            "NPI_NAME": "ethd",
            "NPI_L_ID": 599,
            "NPI_CREATED": "2026-03-27 07:16:58",
            "NPI_CHANGED": null,
            "NPI_NOTE": ""
        }
    ]
}

Request      

GET api/v3/devices/{device_id}/interfaces

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

device_id   integer     

The ID of the device. Example: 48

device   integer     

The device ID Example: 39015

Response

Response Fields

data   object     
NPI_ID   integer     

Unique interface identifier (primary key).

NPI_N_ID   integer     

ID of the parent device (references nodes.ID). See GET /v3/devices/{id}.

NPI_TYPE   integer     

Interface type code (references code_list NODES_INT_TYPES). Common values: 1=Ethernet, 2=Wireless, 3=Optical.

NPI_NAME   string     

Interface name (e.g. eth0, wlan1, pon0). Up to 80 characters.

NPI_L_ID   integer     

ID of the operator (login session) who last modified this interface.

NPI_CREATED   string     

Datetime when the interface record was created (YYYY-MM-DD HH:MM:SS).

NPI_CHANGED   string     

Datetime when the interface record was last modified (YYYY-MM-DD HH:MM:SS).

NPI_NOTE   string     

Free-text note for the interface (up to 255 characters).

Create Device Interface

requires authentication

Create a new physical network interface on a device. The interface type cannot be changed after creation. Validates uniqueness of name per device and type, and checks interface count limits.

Example request:
curl --request POST \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/devices/48/interfaces" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"type\": 1,
    \"name\": \"eth0\",
    \"note\": \"Uplink port\"
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/devices/48/interfaces"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "type": 1,
    "name": "eth0",
    "note": "Uplink port"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "data": {
        "NPI_ID": 3312966,
        "NPI_N_ID": 353,
        "NPI_TYPE": 11,
        "NPI_NAME": "ethz",
        "NPI_L_ID": 225,
        "NPI_CREATED": "2026-03-29 23:08:04",
        "NPI_CHANGED": null,
        "NPI_NOTE": ""
    }
}

Request      

POST api/v3/devices/{device_id}/interfaces

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

device_id   integer     

The ID of the device. Example: 48

device   integer     

The device ID Example: 39015

Body Parameters

type   integer     

Interface type code (references NODES_INT_TYPES code list). Common values: 1=Ethernet, 2=Wireless, 3=Optical. Example: 1

name   string     

Interface name (e.g. eth0, wlan1, pon0). Must be unique per device and type. Example: eth0

note   string  optional    

Free-text note for the interface Example: Uplink port

Response

Response Fields

data   object     
NPI_ID   integer     

Unique interface identifier (primary key).

NPI_N_ID   integer     

ID of the parent device (references nodes.ID). See GET /v3/devices/{id}.

NPI_TYPE   integer     

Interface type code (references code_list NODES_INT_TYPES). Common values: 1=Ethernet, 2=Wireless, 3=Optical.

NPI_NAME   string     

Interface name (e.g. eth0, wlan1, pon0). Up to 80 characters.

NPI_L_ID   integer     

ID of the operator (login session) who last modified this interface.

NPI_CREATED   string     

Datetime when the interface record was created (YYYY-MM-DD HH:MM:SS).

NPI_CHANGED   string     

Datetime when the interface record was last modified (YYYY-MM-DD HH:MM:SS).

NPI_NOTE   string     

Free-text note for the interface (up to 255 characters).

Get Device Interface

requires authentication

Retrieve a specific physical network interface by ID.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/devices/48/interfaces/architecto" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/devices/48/interfaces/architecto"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "NPI_ID": 3312967,
        "NPI_N_ID": 353,
        "NPI_TYPE": 7,
        "NPI_NAME": "ethu",
        "NPI_L_ID": 751,
        "NPI_CREATED": "2026-03-19 16:57:41",
        "NPI_CHANGED": null,
        "NPI_NOTE": ""
    }
}

Request      

GET api/v3/devices/{device_id}/interfaces/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

device_id   integer     

The ID of the device. Example: 48

id   string     

The ID of the interface. Example: architecto

device   integer     

The device ID Example: 39015

interface   integer     

The interface ID Example: 18

Response

Response Fields

data   object     
NPI_ID   integer     

Unique interface identifier (primary key).

NPI_N_ID   integer     

ID of the parent device (references nodes.ID). See GET /v3/devices/{id}.

NPI_TYPE   integer     

Interface type code (references code_list NODES_INT_TYPES). Common values: 1=Ethernet, 2=Wireless, 3=Optical.

NPI_NAME   string     

Interface name (e.g. eth0, wlan1, pon0). Up to 80 characters.

NPI_L_ID   integer     

ID of the operator (login session) who last modified this interface.

NPI_CREATED   string     

Datetime when the interface record was created (YYYY-MM-DD HH:MM:SS).

NPI_CHANGED   string     

Datetime when the interface record was last modified (YYYY-MM-DD HH:MM:SS).

NPI_NOTE   string     

Free-text note for the interface (up to 255 characters).

Update Device Interface

requires authentication

Update a physical network interface. Only name and note can be changed; the interface type is immutable after creation.

Example request:
curl --request PUT \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/devices/48/interfaces/architecto" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"name\": \"eth1\",
    \"note\": \"Updated uplink port\"
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/devices/48/interfaces/architecto"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "name": "eth1",
    "note": "Updated uplink port"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "data": {
        "NPI_ID": 3312968,
        "NPI_N_ID": 353,
        "NPI_TYPE": 2517,
        "NPI_NAME": "ethm",
        "NPI_L_ID": 197,
        "NPI_CREATED": "2026-01-17 12:07:36",
        "NPI_CHANGED": null,
        "NPI_NOTE": ""
    }
}

Request      

PUT api/v3/devices/{device_id}/interfaces/{id}

PATCH api/v3/devices/{device_id}/interfaces/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

device_id   integer     

The ID of the device. Example: 48

id   string     

The ID of the interface. Example: architecto

device   integer     

The device ID Example: 39015

interface   integer     

The interface ID Example: 18

Body Parameters

name   string  optional    

Interface name (e.g. eth0, wlan1, pon0). Must be unique per device and type. Example: eth1

note   string  optional    

Free-text note for the interface Example: Updated uplink port

Response

Response Fields

data   object     
NPI_ID   integer     

Unique interface identifier (primary key).

NPI_N_ID   integer     

ID of the parent device (references nodes.ID). See GET /v3/devices/{id}.

NPI_TYPE   integer     

Interface type code (references code_list NODES_INT_TYPES). Common values: 1=Ethernet, 2=Wireless, 3=Optical.

NPI_NAME   string     

Interface name (e.g. eth0, wlan1, pon0). Up to 80 characters.

NPI_L_ID   integer     

ID of the operator (login session) who last modified this interface.

NPI_CREATED   string     

Datetime when the interface record was created (YYYY-MM-DD HH:MM:SS).

NPI_CHANGED   string     

Datetime when the interface record was last modified (YYYY-MM-DD HH:MM:SS).

NPI_NOTE   string     

Free-text note for the interface (up to 255 characters).

Delete Device Interface

requires authentication

Delete a physical network interface from a device. Fails if the interface has active connections or if deleting would violate minimum interface count requirements.

Example request:
curl --request DELETE \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/devices/48/interfaces/architecto" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/devices/48/interfaces/architecto"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

Example response (204):

Empty response

Request      

DELETE api/v3/devices/{device_id}/interfaces/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

device_id   integer     

The ID of the device. Example: 48

id   string     

The ID of the interface. Example: architecto

device   integer     

The device ID Example: 39015

interface   integer     

The interface ID Example: 18

Device Param Definitions

List Device Param Definitions

requires authentication 

Retrieve a paginated list of device parameter definitions.
These define the schema (name, type, constraints, visibility) of parameters
that can be set on devices of a given type.
Global definitions (NP_CT IS NULL) are always included alongside
location-specific ones.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/device-param-definitions?per_page=10&page=1&ids=1%2C8%2C15&cts=12%2C101&device_kind=MIKROTIK" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/device-param-definitions"
);

const params = {
    "per_page": "10",
    "page": "1",
    "ids": "1,8,15",
    "cts": "12,101",
    "device_kind": "MIKROTIK",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "ID": 4337,
            "NP_NPG_ID": null,
            "PAR_NAME": "NOSTRUM",
            "PAR_TYPE": "NUM",
            "NN_TITLE": "commodi incidunt",
            "N_TYPE": "SWITCH",
            "NP_INTERFACE": null,
            "NP_CT": 180,
            "INDEXED": 0,
            "NP_DISTINCT": 1,
            "NP_DOMAIN": null,
            "NP_NOTNULL": 0,
            "NP_UNIQUE": "",
            "DEFAULT_VALUE": null,
            "NP_CREATE": 1,
            "NP_EDITABLE": 1,
            "TYPE": "AUTO",
            "NP_PARENT_PARAM": null,
            "NP_PARENT_N_TYPE": null,
            "NP_NOTE": null,
            "DOC_VAR_NAME": null,
            "NP_VIEW": "",
            "NP_UPDATE_NODE": 1,
            "NP_ORDER": null,
            "NP_GROUP_NAME": null,
            "NP_DEPENDENCY": null
        },
        {
            "ID": 4338,
            "NP_NPG_ID": null,
            "PAR_NAME": "MODI",
            "PAR_TYPE": "CHAR",
            "NN_TITLE": "nostrum omnis",
            "N_TYPE": "ONT",
            "NP_INTERFACE": null,
            "NP_CT": 167,
            "INDEXED": 0,
            "NP_DISTINCT": 1,
            "NP_DOMAIN": null,
            "NP_NOTNULL": 0,
            "NP_UNIQUE": "",
            "DEFAULT_VALUE": null,
            "NP_CREATE": 1,
            "NP_EDITABLE": 1,
            "TYPE": "AUTO",
            "NP_PARENT_PARAM": null,
            "NP_PARENT_N_TYPE": null,
            "NP_NOTE": null,
            "DOC_VAR_NAME": null,
            "NP_VIEW": "",
            "NP_UPDATE_NODE": 1,
            "NP_ORDER": null,
            "NP_GROUP_NAME": null,
            "NP_DEPENDENCY": null
        }
    ]
}

Request      

GET api/v3/device-param-definitions

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of definitions to return per page (optional) Example: 10

page   integer  optional    

Page number to return (optional) Example: 1

ids   string  optional    

Filter by comma-separated definition IDs Example: 1,8,15

cts   string  optional    

Filter by comma-separated location (installation) IDs. Returns global definitions (NP_CT IS NULL) plus definitions for the specified CTs. Overrides X-CT header default. Example: 12,101

device_kind   string  optional    

Filter by device type (N_TYPE). Accepts a single device type string. Same concept as "kind" filter on /devices endpoint. Example: MIKROTIK

Response

Response Fields

data   object     
ID   integer     

Unique parameter definition ID (primary key).

NP_NPG_ID   integer     

Parameter group ID (FK to node_param_groups). Groups parameters visually/logically.

NP_CT   integer     

Location (installation) ID this definition belongs to. NULL = global definition available to all locations.

N_TYPE   string     

Device type this definition applies to (e.g. 'MIKROTIK', 'ONT', 'SWITCH'). Same concept as 'kind' on /devices.

PAR_NAME   string     

Parameter name/key (e.g. IP_ADDRESS, MAC_ADDRESS, SERVICE_STATE). Unique within a device type + CT scope.

PAR_TYPE   string     

Value data type: CHAR, NUM, IP, MAC, STRING, TEXT, FILE, FLOAT, etc. Determines storage location in device parameter values.

NN_TITLE   string     

Display label shown in the UI (human-readable name).

NP_INTERFACE   integer     

Interface type FK to code_list. NULL = applies to whole device, 8 = any interface.

NP_DOMAIN   string     

Value domain/constraints (e.g. list of allowed values for select-type parameters).

NP_NOTNULL   integer     

Whether this parameter is required (1 = mandatory, 0 = optional).

NP_UNIQUE   string     

Uniqueness constraint scope.

Must be one of:
  • location
  • cp
  • global
  • poolbranch
DEFAULT_VALUE   string     

Default value for new parameter instances.

INDEXED   integer     

Whether parameter can have multiple instances per device/interface (via PAR_INDEX).

NP_DISTINCT   integer     

Whether parameter value is distinct per device/interface (default 1).

NP_CREATE   integer     

Whether to auto-create this parameter when creating a new device (1 = yes).

NP_EDITABLE   integer     

Editability: 0 = never, 1 = always, 2 = not while in service, 3 = not while in maintenance.

TYPE   string     

Update type: how the parameter value is managed.

Must be one of:
  • AUTO
  • MANUAL
  • AUTO_REFRESH
NP_UPDATE_NODE   integer     

Whether changing this parameter triggers a device update action (1 = yes).

NP_PARENT_PARAM   string     

Parent parameter name for value inheritance from another device type.

NP_PARENT_N_TYPE   string     

Device type to copy parent parameter value from.

NP_VIEW   string     

Comma-separated visibility flags: helpdesk_info, nodes_last, export, link_external, templates, wizard, selfcare, ni_history, etc.

NP_ORDER   integer     

Display order among other parameters of the same device type.

NP_GROUP_NAME   string     

Parameter group name (text identifier for logical grouping).

NP_DEPENDENCY   string     

Dependency spec for conditional visibility (format: 'PARAM_NAME;VAL1,VAL2,...').

NP_NOTE   string     

Documentation note about this parameter.

DOC_VAR_NAME   string     

Variable name used in document templates.

Device Service History

List Device Service History

requires authentication 

Retrieve a paginated list of device service history events.
At least one identifying filter (customer, device, or customer_service) is required.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/device-service-history?per_page=10&page=1&ids=1%2C2%2C3&cts=1%2C2%2C3&customer=100&device=40022&customer_service=200&from=2024-01-01&to=2024-12-31" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/device-service-history"
);

const params = {
    "per_page": "10",
    "page": "1",
    "ids": "1,2,3",
    "cts": "1,2,3",
    "customer": "100",
    "device": "40022",
    "customer_service": "200",
    "from": "2024-01-01",
    "to": "2024-12-31",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "NSH_ID": 3399702,
            "NSH_N_ID": 759832,
            "NSH_U_ID": null,
            "NSH_SA_ID": null,
            "NSH_EVENT": 20,
            "NSH_L_ID": 339,
            "NSH_TIME": "2026-01-30 06:18:11",
            "NSH_CREATED": "2026-03-08 11:34:47",
            "NSH_NOTE": null,
            "NSH_NOTE_BODY": null
        },
        {
            "NSH_ID": 3399703,
            "NSH_N_ID": 314167,
            "NSH_U_ID": null,
            "NSH_SA_ID": null,
            "NSH_EVENT": 18,
            "NSH_L_ID": 274,
            "NSH_TIME": "2026-03-09 20:20:21",
            "NSH_CREATED": "2026-03-05 06:51:36",
            "NSH_NOTE": null,
            "NSH_NOTE_BODY": null
        }
    ]
}

Request      

GET api/v3/device-service-history

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of results per page (optional). Example: 10

page   integer  optional    

Page number to return (optional). Example: 1

ids   string  optional    

Filter by comma-separated device service history IDs. Example: 1,2,3

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Example: 1,2,3

customer   integer  optional    

Filter by customer ID (NSH_U_ID). Example: 100

device   integer  optional    

Filter by device (node) ID (NSH_N_ID). Example: 40022

customer_service   integer  optional    

Filter by active service instance ID (NSH_SA_ID). Example: 200

from   string  optional    

Filter events on or after this date/datetime (NSH_TIME column). Example: 2024-01-01

to   string  optional    

Filter events on or before this date/datetime (NSH_TIME column). Example: 2024-12-31

Response

Response Fields

data   object     
NSH_ID   integer     

Unique device service history event identifier.

NSH_N_ID   integer     

Device (node) ID. See GET /v3/devices/{id}.

NSH_U_ID   integer     

Customer ID. See GET /v3/customers/{id}.

NSH_SA_ID   integer     

Active service instance ID. See GET /v3/customer-services/{id}.

NSH_EVENT   integer     

Event type code (numeric). See event_name for the symbolic key.

event_name   string     

Symbolic event name resolved from code_list (e.g. NSH_ADD, NSH_DELETE).

NSH_L_ID   integer     

Login ID of the operator who created this event.

NSH_TIME   string     

Event timestamp (datetime).

NSH_CREATED   string     

Record creation timestamp (datetime).

NSH_NOTE   string     

Short note / event description.

NSH_NOTE_BODY   string     

Extended note body (long text).

Get Device Service History Event

requires authentication 

Retrieve a specific device service history event by ID, including the resolved event name.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/device-service-history/1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/device-service-history/1"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "NSH_ID": 3399704,
        "NSH_N_ID": 759832,
        "NSH_U_ID": null,
        "NSH_SA_ID": null,
        "NSH_EVENT": 20,
        "NSH_L_ID": 339,
        "NSH_TIME": "2026-01-30 06:18:11",
        "NSH_CREATED": "2026-03-08 11:34:47",
        "NSH_NOTE": null,
        "NSH_NOTE_BODY": null
    }
}

Request      

GET api/v3/device-service-history/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the device service history. Example: 1

Response

Response Fields

data   object     
NSH_ID   integer     

Unique device service history event identifier.

NSH_N_ID   integer     

Device (node) ID. See GET /v3/devices/{id}.

NSH_U_ID   integer     

Customer ID. See GET /v3/customers/{id}.

NSH_SA_ID   integer     

Active service instance ID. See GET /v3/customer-services/{id}.

NSH_EVENT   integer     

Event type code (numeric). See event_name for the symbolic key.

event_name   string     

Symbolic event name resolved from code_list (e.g. NSH_ADD, NSH_DELETE).

NSH_L_ID   integer     

Login ID of the operator who created this event.

NSH_TIME   string     

Event timestamp (datetime).

NSH_CREATED   string     

Record creation timestamp (datetime).

NSH_NOTE   string     

Short note / event description.

NSH_NOTE_BODY   string     

Extended note body (long text).

Devices

List Devices

requires authentication

Retrieve a paginated list of devices. Supports complex CT filtering (customer devices by N_CT, infrastructure by infra_loc param).

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/devices?ids=1%2C2%2C3&cts=1%2C2%2C3&kind=AP&parent_id=100&child_id=200&groups=5%2C10&service_ids=1%2C2&user_id=100" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/devices"
);

const params = {
    "ids": "1,2,3",
    "cts": "1,2,3",
    "kind": "AP",
    "parent_id": "100",
    "child_id": "200",
    "groups": "5,10",
    "service_ids": "1,2",
    "user_id": "100",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "ID": 1792669,
            "NAME": "DEV-uwpwlv",
            "NOTE": "Odit et et modi.",
            "MANAGED": 0,
            "MANAG_IP": null,
            "PARENT_NODE": null,
            "F_TYPE": "OLT",
            "N_TYPE": "CISCO",
            "N_DEVICE_TYPE": "switch",
            "N_CUSTOMER": 1,
            "USER_SERVICE_ID": 0,
            "CUSTOMER_PARENT": 0,
            "CUSTOMER_TYPE": null,
            "CUSTOMER_LOCATION": 0,
            "MAC": null,
            "UPDATE_FLAG": 0,
            "AGR_GROUP": null,
            "STREET": null,
            "HOUSE_ID": null,
            "N_ZIP": null,
            "N_CITY": null,
            "SOCKET": null,
            "N_COUNTER_ID": "000000",
            "N_PRODUCER": null,
            "N_SERIAL_NUM": null,
            "N_LAST_RESPONSE": null,
            "N_CT": "085",
            "N_CREATED": null,
            "N_L_ID": "000607",
            "N_GPS_LATITUDE": null,
            "N_GPS_LONGITUDE": null,
            "N_UCP_ID": null,
            "N_US_ID": null,
            "N_UA_ID": null,
            "N_CACHE_NAME": "enim",
            "N_CACHE_LAST_WS_ID": null,
            "N_DELETED": null,
            "params": [
                {
                    "ID": 301268711,
                    "NODE_ID": 1792669,
                    "NI_NPI_ID": 0,
                    "PAR_NAME": "SERVICE_STATE",
                    "PAR_INDEX": 0,
                    "VALUE": "ex",
                    "CONTENT": null,
                    "TEXT_CONTENT": null
                }
            ],
            "customer_service_devices": [
                {
                    "NS_ID": 2148169,
                    "NS_N_ID": 1792669,
                    "NS_U_ID": 1038,
                    "NS_SA_ID": null,
                    "NS_TIME": "2026-02-09 06:04:14",
                    "NS_L_ID": 1,
                    "NS_NEEDS_UPDATE": 0
                }
            ],
            "interfaces": [
                {
                    "NPI_ID": 3312957,
                    "NPI_N_ID": 1792669,
                    "NPI_TYPE": 1563,
                    "NPI_NAME": "ethw",
                    "NPI_L_ID": 258,
                    "NPI_CREATED": "2026-01-12 15:57:38",
                    "NPI_CHANGED": null,
                    "NPI_NOTE": ""
                }
            ]
        },
        {
            "ID": 1792670,
            "NAME": "DEV-xjklqp",
            "NOTE": "Libero aliquam veniam corporis dolorem mollitia deleniti.",
            "MANAGED": 0,
            "MANAG_IP": "54.95.112.197",
            "PARENT_NODE": null,
            "F_TYPE": "OLT",
            "N_TYPE": "MIKROTIK",
            "N_DEVICE_TYPE": "switch",
            "N_CUSTOMER": 1,
            "USER_SERVICE_ID": 0,
            "CUSTOMER_PARENT": 0,
            "CUSTOMER_TYPE": null,
            "CUSTOMER_LOCATION": 0,
            "MAC": null,
            "UPDATE_FLAG": 0,
            "AGR_GROUP": null,
            "STREET": null,
            "HOUSE_ID": null,
            "N_ZIP": null,
            "N_CITY": null,
            "SOCKET": null,
            "N_COUNTER_ID": "000000",
            "N_PRODUCER": null,
            "N_SERIAL_NUM": null,
            "N_LAST_RESPONSE": null,
            "N_CT": "098",
            "N_CREATED": null,
            "N_L_ID": "000970",
            "N_GPS_LATITUDE": null,
            "N_GPS_LONGITUDE": null,
            "N_UCP_ID": null,
            "N_US_ID": null,
            "N_UA_ID": null,
            "N_CACHE_NAME": "excepturi",
            "N_CACHE_LAST_WS_ID": null,
            "N_DELETED": null,
            "params": [
                {
                    "ID": 301268712,
                    "NODE_ID": 1792670,
                    "NI_NPI_ID": 0,
                    "PAR_NAME": "VIRTUAL_IP",
                    "PAR_INDEX": 0,
                    "VALUE": "qui",
                    "CONTENT": null,
                    "TEXT_CONTENT": null
                }
            ],
            "customer_service_devices": [
                {
                    "NS_ID": 2148170,
                    "NS_N_ID": 1792670,
                    "NS_U_ID": 1038,
                    "NS_SA_ID": null,
                    "NS_TIME": "2026-02-20 19:24:15",
                    "NS_L_ID": 1,
                    "NS_NEEDS_UPDATE": 0
                }
            ],
            "interfaces": [
                {
                    "NPI_ID": 3312958,
                    "NPI_N_ID": 1792670,
                    "NPI_TYPE": 5,
                    "NPI_NAME": "etha",
                    "NPI_L_ID": 754,
                    "NPI_CREATED": "2026-03-11 14:00:38",
                    "NPI_CHANGED": null,
                    "NPI_NOTE": ""
                }
            ]
        }
    ]
}

Request      

GET api/v3/devices

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

ids   string  optional    

Filter by comma-separated device IDs Example: 1,2,3

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Uses complex device CT logic. Example: 1,2,3

kind   string  optional    

Filter by device type (N_TYPE) Example: AP

parent_id   integer  optional    

Filter by parent device ID (devices connected under this parent) Example: 100

child_id   integer  optional    

Filter by child device ID (returns the parent device above this child) Example: 200

groups   string  optional    

Filter by device group ID(s), comma-separated Example: 5,10

service_ids   string  optional    

Filter by service IDs (comma-separated), devices linked to these services Example: 1,2

user_id   integer  optional    

Filter by customer ID, devices linked to this customer via nodes_services Example: 100

Response

Response Fields

data   object     
ID   integer     

Unique device identifier (primary key, zero-filled to 6 digits).

NAME   string     

Device name (up to 30 characters).

NOTE   string     

Free-text note.

N_TYPE   string     

Device class / node type (e.g. LINUX, MIKROTIK, SWITCH, ONT, WIFI, CISCO, DOCSIS, …). Defines the parameter schema available for the device.

N_DEVICE_TYPE   string     

Specific device model or hardware type (e.g. 'MikroTik RB750', 'UBNT NanoStation', …).

F_TYPE   string     

Functional type. Possible values: AP, BRIDGE, IP, OLT, ONU, ROUTER, SIP, SWITCH.

N_CUSTOMER   integer     

Customer device flag. 1 = end-user device (CPE), 0 = infrastructure device.

CUSTOMER_PARENT   integer     

Flag indicating this infrastructure device can host customer (end-user) devices. 1 = open for customer connections.

CUSTOMER_TYPE   string     

Customer device sub-type (only relevant when N_CUSTOMER=1). E.g. LINUX, NIC, WIFI, DECODER, DS_MODEM, SIP_DEVICE, CIBSROUTER, etc.

MANAGED   integer     

Flag indicating the device is managed (configured) by the Mango system. 1 = managed.

MANAG_IP   string     

Management IP address of the device.

UPDATE_FLAG   integer     

Flag indicating the device configuration needs to be pushed/updated. 1 = update pending.

MAC   string     

MAC address of the device.

N_LAST_RESPONSE   string     

Datetime of the last successful SNMP monitoring response.

PARENT_NODE   integer     

ID of the parent device in the network topology. See GET /v3/devices/{id}.

USER_SERVICE_ID   integer     

ID of the associated customer service. See GET /v3/customer-services/{id}.

N_CT   integer     

Location / installation CT ID (for customer devices when N_CUSTOMER=1).

STREET   string     

Street name of the device location.

HOUSE_ID   string     

House number (číslo popisné) of the device location.

N_ZIP   string     

ZIP / postal code (up to 5 characters).

N_CITY   string     

City of the device location.

SOCKET   string     

Socket / apartment identifier at the device location.

N_GPS_LATITUDE   number     

GPS latitude of the device.

N_GPS_LONGITUDE   number     

GPS longitude of the device.

N_UCP_ID   integer     

UIR registry city part ID.

N_US_ID   integer     

UIR registry street ID.

N_UA_ID   integer     

UIR registry address ID.

N_PRODUCER   string     

Device manufacturer / producer.

N_SERIAL_NUM   string     

Serial number of the device.

N_CREATED   string     

Datetime when the device record was created.

N_L_ID   integer     

ID of the operator (login session) who last modified this device.

N_CACHE_NAME   string     

Cached display name combining class, type and device name for quick lookups.

N_CACHE_LAST_WS_ID   integer     

Cached ID of the last work session that touched this device.

CUSTOMER_LOCATION   integer     

Deprecated. Former customer location reference (now handled via nodes_cust_locations).

AGR_GROUP   integer     

Deprecated. Former aggregation group reference.

N_COUNTER_ID   integer     

Deprecated. Former counter ID (now stored as a device parameter).

params   object[]     

Device parameters — collection of key-value pairs from the node_info table.
ID   integer     

Unique device parameter identifier (primary key, zero-filled bigint).

NODE_ID   integer     

ID of the parent device. See GET /v3/devices/{id}.

NI_NPI_ID   integer     

Parameter definition index ID. 0 = device-level parameter.

PAR_NAME   string     

Parameter name / key (e.g. IP_ADDRESS, DATA_COUNTER, SERVICE_STATE, VIRTUAL_IP).

PAR_INDEX   integer     

Index for multi-valued parameters. 0 = single/first value; higher values represent additional entries of the same parameter.

VALUE   string     

Parameter value as a string (up to 255 characters). Interpretation depends on PAR_NAME and the parameter type.

CONTENT   string     

Binary content (longblob) for file-type parameters (e.g. uploaded configuration files). Base64-encoded when serialized.

TEXT_CONTENT   string     

Large text content for parameters that exceed the 255-character VALUE limit (longtext).

customer_service_devices   object[]     

Services bound to this device — collection of customer-service-device bindings from the nodes_services table.
NS_ID   integer     

Unique customer-service-device binding ID (primary key).

NS_N_ID   integer     

Device ID this service is bound to. See GET /v3/devices/{id}.

NS_U_ID   integer     

Customer ID who owns the service on this device. See GET /v3/customers/{id}.

NS_SA_ID   integer     

Active service (CustomerService) ID. Null when the binding exists without a specific active service. See GET /v3/customer-services/{id}.

NS_TIME   string     

Datetime when the service was bound to the device (YYYY-MM-DD HH:MM:SS).

NS_L_ID   integer     

Operator (login session) ID who created or last modified this binding.

NS_NEEDS_UPDATE   integer     

Flag indicating the device needs to schedule a configuration update because the service is activated in the future. 0 = no update needed, 1 = update pending.

interfaces   object[]     

Physical network interfaces — collection of interface records from the nodes_physical_interfaces table.
NPI_ID   integer     

Unique interface identifier (primary key).

NPI_N_ID   integer     

ID of the parent device (references nodes.ID).

NPI_TYPE   integer     

Interface type code (references code_list NODES_INT_TYPES). Common values: 1=Ethernet, 2=Wireless, 3=Optical.

NPI_NAME   string     

Interface name (e.g. eth0, wlan1, pon0).

NPI_L_ID   integer     

Operator (login session) ID who last modified this interface.

NPI_CREATED   string     

Datetime when the interface record was created.

NPI_CHANGED   string     

Datetime when the interface record was last modified.

NPI_NOTE   string     

Free-text note for the interface.

Create Device

requires authentication

Create a new device.

Example request:
curl --request POST \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/devices" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"customer\": 1,
    \"type\": \"AP\",
    \"device_type\": \"MikroTik RB750\",
    \"name\": \"AP Roof\",
    \"interface\": \"eth0\",
    \"parent_node\": 100,
    \"parent_interface\": 16,
    \"premise_id\": 16,
    \"serial_num\": \"SN123456\",
    \"ct\": 5,
    \"user_id\": 16,
    \"services\": [
        16
    ],
    \"street\": \"Main Street\",
    \"house_id\": \"12A\",
    \"zip\": \"56001\",
    \"city\": \"Prague\",
    \"socket\": \"architecto\",
    \"note\": \"architecto\",
    \"gps_latitude\": 49.8175,
    \"gps_longitude\": 15.473,
    \"params\": [
        {
            \"name\": \"architecto\",
            \"value\": \"architecto\"
        }
    ],
    \"ucp_id\": 16,
    \"us_id\": 16,
    \"ua_id\": 16
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/devices"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "customer": 1,
    "type": "AP",
    "device_type": "MikroTik RB750",
    "name": "AP Roof",
    "interface": "eth0",
    "parent_node": 100,
    "parent_interface": 16,
    "premise_id": 16,
    "serial_num": "SN123456",
    "ct": 5,
    "user_id": 16,
    "services": [
        16
    ],
    "street": "Main Street",
    "house_id": "12A",
    "zip": "56001",
    "city": "Prague",
    "socket": "architecto",
    "note": "architecto",
    "gps_latitude": 49.8175,
    "gps_longitude": 15.473,
    "params": [
        {
            "name": "architecto",
            "value": "architecto"
        }
    ],
    "ucp_id": 16,
    "us_id": 16,
    "ua_id": 16
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "data": {
        "ID": 1792671,
        "NAME": "DEV-ngzmiy",
        "NOTE": "Nihil accusantium harum mollitia modi deserunt.",
        "MANAGED": 0,
        "MANAG_IP": null,
        "PARENT_NODE": null,
        "F_TYPE": "OLT",
        "N_TYPE": "CISCO",
        "N_DEVICE_TYPE": "router",
        "N_CUSTOMER": 0,
        "USER_SERVICE_ID": 0,
        "CUSTOMER_PARENT": 0,
        "CUSTOMER_TYPE": null,
        "CUSTOMER_LOCATION": 0,
        "MAC": null,
        "UPDATE_FLAG": 0,
        "AGR_GROUP": null,
        "STREET": null,
        "HOUSE_ID": null,
        "N_ZIP": null,
        "N_CITY": null,
        "SOCKET": null,
        "N_COUNTER_ID": "000000",
        "N_PRODUCER": null,
        "N_SERIAL_NUM": null,
        "N_LAST_RESPONSE": null,
        "N_CT": "007",
        "N_CREATED": null,
        "N_L_ID": "000592",
        "N_GPS_LATITUDE": null,
        "N_GPS_LONGITUDE": null,
        "N_UCP_ID": null,
        "N_US_ID": null,
        "N_UA_ID": null,
        "N_CACHE_NAME": "adipisci",
        "N_CACHE_LAST_WS_ID": null,
        "N_DELETED": null,
        "params": [
            {
                "ID": 301268713,
                "NODE_ID": 1792671,
                "NI_NPI_ID": 0,
                "PAR_NAME": "SERVICE_STATE",
                "PAR_INDEX": 0,
                "VALUE": null,
                "CONTENT": null,
                "TEXT_CONTENT": null
            }
        ],
        "customer_service_devices": [
            {
                "NS_ID": 2148171,
                "NS_N_ID": 1792671,
                "NS_U_ID": 1038,
                "NS_SA_ID": null,
                "NS_TIME": "2026-04-07 11:24:37",
                "NS_L_ID": 1,
                "NS_NEEDS_UPDATE": 0
            }
        ],
        "interfaces": [
            {
                "NPI_ID": 3312959,
                "NPI_N_ID": 1792671,
                "NPI_TYPE": 1562,
                "NPI_NAME": "ethr",
                "NPI_L_ID": 765,
                "NPI_CREATED": "2026-01-04 19:46:55",
                "NPI_CHANGED": null,
                "NPI_NOTE": ""
            }
        ]
    }
}

Request      

POST api/v3/devices

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Body Parameters

customer   integer     

Device kind: 0=infrastructure, 1=customer (CPE) Example: 1

type   string     

Node type (NIC, DSL_MODEM, NG_MODEM, ONT, AP, SWITCH, etc.) Example: AP

device_type   string     

Specific device type Example: MikroTik RB750

name   string     

Device name Example: AP Roof

interface   string  optional    

Interface name Example: eth0

parent_node   integer  optional    

Parent node ID Example: 100

parent_interface   integer  optional    

Parent interface ID Example: 16

premise_id   integer  optional    

Premise ID Example: 16

serial_num   string  optional    

Serial number Example: SN123456

ct   integer  optional    

Location/installation ID (for customer devices) Example: 5

user_id   integer  optional    

Customer ID to bind Example: 16

services   integer[]  optional    

Service IDs to bind (array of SA_IDs)

street   string  optional    

Street address Example: Main Street

house_id   string  optional    

House number Example: 12A

zip   string  optional    

ZIP code Example: 56001

city   string  optional    

City Example: Prague

socket   string  optional    

Socket identifier Example: architecto

note   string  optional    

Notes Example: architecto

gps_latitude   number  optional    

GPS latitude Example: 49.8175

gps_longitude   number  optional    

GPS longitude Example: 15.473

params   object[]  optional    

Parameters as array of {name, value}
name   string  optional    

This field is required when params is present. Example: architecto

value   string  optional    

This field is required when params is present. Example: architecto

ucp_id   integer  optional    

UIR city part ID Example: 16

us_id   integer  optional    

UIR street ID Example: 16

ua_id   integer  optional    

UIR address ID Example: 16

Response

Response Fields

data   object     
ID   integer     

Unique device identifier (primary key, zero-filled to 6 digits).

NAME   string     

Device name (up to 30 characters).

NOTE   string     

Free-text note.

N_TYPE   string     

Device class / node type (e.g. LINUX, MIKROTIK, SWITCH, ONT, WIFI, CISCO, DOCSIS, …). Defines the parameter schema available for the device.

N_DEVICE_TYPE   string     

Specific device model or hardware type (e.g. 'MikroTik RB750', 'UBNT NanoStation', …).

F_TYPE   string     

Functional type. Possible values: AP, BRIDGE, IP, OLT, ONU, ROUTER, SIP, SWITCH.

N_CUSTOMER   integer     

Customer device flag. 1 = end-user device (CPE), 0 = infrastructure device.

CUSTOMER_PARENT   integer     

Flag indicating this infrastructure device can host customer (end-user) devices. 1 = open for customer connections.

CUSTOMER_TYPE   string     

Customer device sub-type (only relevant when N_CUSTOMER=1). E.g. LINUX, NIC, WIFI, DECODER, DS_MODEM, SIP_DEVICE, CIBSROUTER, etc.

MANAGED   integer     

Flag indicating the device is managed (configured) by the Mango system. 1 = managed.

MANAG_IP   string     

Management IP address of the device.

UPDATE_FLAG   integer     

Flag indicating the device configuration needs to be pushed/updated. 1 = update pending.

MAC   string     

MAC address of the device.

N_LAST_RESPONSE   string     

Datetime of the last successful SNMP monitoring response.

PARENT_NODE   integer     

ID of the parent device in the network topology. See GET /v3/devices/{id}.

USER_SERVICE_ID   integer     

ID of the associated customer service. See GET /v3/customer-services/{id}.

N_CT   integer     

Location / installation CT ID (for customer devices when N_CUSTOMER=1).

STREET   string     

Street name of the device location.

HOUSE_ID   string     

House number (číslo popisné) of the device location.

N_ZIP   string     

ZIP / postal code (up to 5 characters).

N_CITY   string     

City of the device location.

SOCKET   string     

Socket / apartment identifier at the device location.

N_GPS_LATITUDE   number     

GPS latitude of the device.

N_GPS_LONGITUDE   number     

GPS longitude of the device.

N_UCP_ID   integer     

UIR registry city part ID.

N_US_ID   integer     

UIR registry street ID.

N_UA_ID   integer     

UIR registry address ID.

N_PRODUCER   string     

Device manufacturer / producer.

N_SERIAL_NUM   string     

Serial number of the device.

N_CREATED   string     

Datetime when the device record was created.

N_L_ID   integer     

ID of the operator (login session) who last modified this device.

N_CACHE_NAME   string     

Cached display name combining class, type and device name for quick lookups.

N_CACHE_LAST_WS_ID   integer     

Cached ID of the last work session that touched this device.

CUSTOMER_LOCATION   integer     

Deprecated. Former customer location reference (now handled via nodes_cust_locations).

AGR_GROUP   integer     

Deprecated. Former aggregation group reference.

N_COUNTER_ID   integer     

Deprecated. Former counter ID (now stored as a device parameter).

params   object[]     

Device parameters — collection of key-value pairs from the node_info table.
ID   integer     

Unique device parameter identifier (primary key, zero-filled bigint).

NODE_ID   integer     

ID of the parent device. See GET /v3/devices/{id}.

NI_NPI_ID   integer     

Parameter definition index ID. 0 = device-level parameter.

PAR_NAME   string     

Parameter name / key (e.g. IP_ADDRESS, DATA_COUNTER, SERVICE_STATE, VIRTUAL_IP).

PAR_INDEX   integer     

Index for multi-valued parameters. 0 = single/first value; higher values represent additional entries of the same parameter.

VALUE   string     

Parameter value as a string (up to 255 characters). Interpretation depends on PAR_NAME and the parameter type.

CONTENT   string     

Binary content (longblob) for file-type parameters (e.g. uploaded configuration files). Base64-encoded when serialized.

TEXT_CONTENT   string     

Large text content for parameters that exceed the 255-character VALUE limit (longtext).

customer_service_devices   object[]     

Services bound to this device — collection of customer-service-device bindings from the nodes_services table.
NS_ID   integer     

Unique customer-service-device binding ID (primary key).

NS_N_ID   integer     

Device ID this service is bound to. See GET /v3/devices/{id}.

NS_U_ID   integer     

Customer ID who owns the service on this device. See GET /v3/customers/{id}.

NS_SA_ID   integer     

Active service (CustomerService) ID. Null when the binding exists without a specific active service. See GET /v3/customer-services/{id}.

NS_TIME   string     

Datetime when the service was bound to the device (YYYY-MM-DD HH:MM:SS).

NS_L_ID   integer     

Operator (login session) ID who created or last modified this binding.

NS_NEEDS_UPDATE   integer     

Flag indicating the device needs to schedule a configuration update because the service is activated in the future. 0 = no update needed, 1 = update pending.

interfaces   object[]     

Physical network interfaces — collection of interface records from the nodes_physical_interfaces table.
NPI_ID   integer     

Unique interface identifier (primary key).

NPI_N_ID   integer     

ID of the parent device (references nodes.ID).

NPI_TYPE   integer     

Interface type code (references code_list NODES_INT_TYPES). Common values: 1=Ethernet, 2=Wireless, 3=Optical.

NPI_NAME   string     

Interface name (e.g. eth0, wlan1, pon0).

NPI_L_ID   integer     

Operator (login session) ID who last modified this interface.

NPI_CREATED   string     

Datetime when the interface record was created.

NPI_CHANGED   string     

Datetime when the interface record was last modified.

NPI_NOTE   string     

Free-text note for the interface.

Get Device

requires authentication

Retrieve a specific device by ID.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/devices/48" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/devices/48"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "ID": 1792672,
        "NAME": "DEV-qwrsit",
        "NOTE": null,
        "MANAGED": 1,
        "MANAG_IP": null,
        "PARENT_NODE": null,
        "F_TYPE": "SWITCH",
        "N_TYPE": "CISCO",
        "N_DEVICE_TYPE": "switch",
        "N_CUSTOMER": 1,
        "USER_SERVICE_ID": 0,
        "CUSTOMER_PARENT": 0,
        "CUSTOMER_TYPE": null,
        "CUSTOMER_LOCATION": 0,
        "MAC": null,
        "UPDATE_FLAG": 0,
        "AGR_GROUP": null,
        "STREET": null,
        "HOUSE_ID": null,
        "N_ZIP": null,
        "N_CITY": null,
        "SOCKET": null,
        "N_COUNTER_ID": "000000",
        "N_PRODUCER": null,
        "N_SERIAL_NUM": null,
        "N_LAST_RESPONSE": null,
        "N_CT": "085",
        "N_CREATED": null,
        "N_L_ID": "000185",
        "N_GPS_LATITUDE": null,
        "N_GPS_LONGITUDE": null,
        "N_UCP_ID": null,
        "N_US_ID": null,
        "N_UA_ID": null,
        "N_CACHE_NAME": "non",
        "N_CACHE_LAST_WS_ID": null,
        "N_DELETED": null,
        "params": [
            {
                "ID": 301268714,
                "NODE_ID": 1792672,
                "NI_NPI_ID": 0,
                "PAR_NAME": "infra_loc",
                "PAR_INDEX": 0,
                "VALUE": "voluptatem",
                "CONTENT": null,
                "TEXT_CONTENT": null
            }
        ],
        "customer_service_devices": [
            {
                "NS_ID": 2148172,
                "NS_N_ID": 1792672,
                "NS_U_ID": 1038,
                "NS_SA_ID": null,
                "NS_TIME": "2026-01-11 18:39:19",
                "NS_L_ID": 1,
                "NS_NEEDS_UPDATE": 0
            }
        ],
        "interfaces": [
            {
                "NPI_ID": 3312960,
                "NPI_N_ID": 1792672,
                "NPI_TYPE": 1561,
                "NPI_NAME": "ethv",
                "NPI_L_ID": 130,
                "NPI_CREATED": "2026-03-18 04:13:35",
                "NPI_CHANGED": null,
                "NPI_NOTE": ""
            }
        ]
    }
}

Request      

GET api/v3/devices/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the device. Example: 48

Response

Response Fields

data   object     
ID   integer     

Unique device identifier (primary key, zero-filled to 6 digits).

NAME   string     

Device name (up to 30 characters).

NOTE   string     

Free-text note.

N_TYPE   string     

Device class / node type (e.g. LINUX, MIKROTIK, SWITCH, ONT, WIFI, CISCO, DOCSIS, …). Defines the parameter schema available for the device.

N_DEVICE_TYPE   string     

Specific device model or hardware type (e.g. 'MikroTik RB750', 'UBNT NanoStation', …).

F_TYPE   string     

Functional type. Possible values: AP, BRIDGE, IP, OLT, ONU, ROUTER, SIP, SWITCH.

N_CUSTOMER   integer     

Customer device flag. 1 = end-user device (CPE), 0 = infrastructure device.

CUSTOMER_PARENT   integer     

Flag indicating this infrastructure device can host customer (end-user) devices. 1 = open for customer connections.

CUSTOMER_TYPE   string     

Customer device sub-type (only relevant when N_CUSTOMER=1). E.g. LINUX, NIC, WIFI, DECODER, DS_MODEM, SIP_DEVICE, CIBSROUTER, etc.

MANAGED   integer     

Flag indicating the device is managed (configured) by the Mango system. 1 = managed.

MANAG_IP   string     

Management IP address of the device.

UPDATE_FLAG   integer     

Flag indicating the device configuration needs to be pushed/updated. 1 = update pending.

MAC   string     

MAC address of the device.

N_LAST_RESPONSE   string     

Datetime of the last successful SNMP monitoring response.

PARENT_NODE   integer     

ID of the parent device in the network topology. See GET /v3/devices/{id}.

USER_SERVICE_ID   integer     

ID of the associated customer service. See GET /v3/customer-services/{id}.

N_CT   integer     

Location / installation CT ID (for customer devices when N_CUSTOMER=1).

STREET   string     

Street name of the device location.

HOUSE_ID   string     

House number (číslo popisné) of the device location.

N_ZIP   string     

ZIP / postal code (up to 5 characters).

N_CITY   string     

City of the device location.

SOCKET   string     

Socket / apartment identifier at the device location.

N_GPS_LATITUDE   number     

GPS latitude of the device.

N_GPS_LONGITUDE   number     

GPS longitude of the device.

N_UCP_ID   integer     

UIR registry city part ID.

N_US_ID   integer     

UIR registry street ID.

N_UA_ID   integer     

UIR registry address ID.

N_PRODUCER   string     

Device manufacturer / producer.

N_SERIAL_NUM   string     

Serial number of the device.

N_CREATED   string     

Datetime when the device record was created.

N_L_ID   integer     

ID of the operator (login session) who last modified this device.

N_CACHE_NAME   string     

Cached display name combining class, type and device name for quick lookups.

N_CACHE_LAST_WS_ID   integer     

Cached ID of the last work session that touched this device.

CUSTOMER_LOCATION   integer     

Deprecated. Former customer location reference (now handled via nodes_cust_locations).

AGR_GROUP   integer     

Deprecated. Former aggregation group reference.

N_COUNTER_ID   integer     

Deprecated. Former counter ID (now stored as a device parameter).

params   object[]     

Device parameters — collection of key-value pairs from the node_info table.
ID   integer     

Unique device parameter identifier (primary key, zero-filled bigint).

NODE_ID   integer     

ID of the parent device. See GET /v3/devices/{id}.

NI_NPI_ID   integer     

Parameter definition index ID. 0 = device-level parameter.

PAR_NAME   string     

Parameter name / key (e.g. IP_ADDRESS, DATA_COUNTER, SERVICE_STATE, VIRTUAL_IP).

PAR_INDEX   integer     

Index for multi-valued parameters. 0 = single/first value; higher values represent additional entries of the same parameter.

VALUE   string     

Parameter value as a string (up to 255 characters). Interpretation depends on PAR_NAME and the parameter type.

CONTENT   string     

Binary content (longblob) for file-type parameters (e.g. uploaded configuration files). Base64-encoded when serialized.

TEXT_CONTENT   string     

Large text content for parameters that exceed the 255-character VALUE limit (longtext).

customer_service_devices   object[]     

Services bound to this device — collection of customer-service-device bindings from the nodes_services table.
NS_ID   integer     

Unique customer-service-device binding ID (primary key).

NS_N_ID   integer     

Device ID this service is bound to. See GET /v3/devices/{id}.

NS_U_ID   integer     

Customer ID who owns the service on this device. See GET /v3/customers/{id}.

NS_SA_ID   integer     

Active service (CustomerService) ID. Null when the binding exists without a specific active service. See GET /v3/customer-services/{id}.

NS_TIME   string     

Datetime when the service was bound to the device (YYYY-MM-DD HH:MM:SS).

NS_L_ID   integer     

Operator (login session) ID who created or last modified this binding.

NS_NEEDS_UPDATE   integer     

Flag indicating the device needs to schedule a configuration update because the service is activated in the future. 0 = no update needed, 1 = update pending.

interfaces   object[]     

Physical network interfaces — collection of interface records from the nodes_physical_interfaces table.
NPI_ID   integer     

Unique interface identifier (primary key).

NPI_N_ID   integer     

ID of the parent device (references nodes.ID).

NPI_TYPE   integer     

Interface type code (references code_list NODES_INT_TYPES). Common values: 1=Ethernet, 2=Wireless, 3=Optical.

NPI_NAME   string     

Interface name (e.g. eth0, wlan1, pon0).

NPI_L_ID   integer     

Operator (login session) ID who last modified this interface.

NPI_CREATED   string     

Datetime when the interface record was created.

NPI_CHANGED   string     

Datetime when the interface record was last modified.

NPI_NOTE   string     

Free-text note for the interface.

Update Device

requires authentication

Update an existing device.

Example request:
curl --request PUT \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/devices/48" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"customer\": 1,
    \"device_type\": \"MikroTik RB750\",
    \"name\": \"AP Roof\",
    \"premise_id\": 16,
    \"serial_num\": \"SN123456\",
    \"ct\": 5,
    \"user_id\": 16,
    \"services\": [
        16
    ],
    \"street\": \"Main Street\",
    \"house_id\": \"12A\",
    \"zip\": \"56001\",
    \"city\": \"Prague\",
    \"socket\": \"architecto\",
    \"note\": \"architecto\",
    \"gps_latitude\": \"49.8175\",
    \"gps_longitude\": \"15.473\",
    \"params\": [
        {
            \"name\": \"architecto\",
            \"value\": \"architecto\"
        }
    ],
    \"ucp_id\": 16,
    \"us_id\": 16,
    \"ua_id\": 16
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/devices/48"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "customer": 1,
    "device_type": "MikroTik RB750",
    "name": "AP Roof",
    "premise_id": 16,
    "serial_num": "SN123456",
    "ct": 5,
    "user_id": 16,
    "services": [
        16
    ],
    "street": "Main Street",
    "house_id": "12A",
    "zip": "56001",
    "city": "Prague",
    "socket": "architecto",
    "note": "architecto",
    "gps_latitude": "49.8175",
    "gps_longitude": "15.473",
    "params": [
        {
            "name": "architecto",
            "value": "architecto"
        }
    ],
    "ucp_id": 16,
    "us_id": 16,
    "ua_id": 16
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "data": {
        "ID": 1792673,
        "NAME": "DEV-vdljni",
        "NOTE": null,
        "MANAGED": 1,
        "MANAG_IP": "41.168.31.124",
        "PARENT_NODE": null,
        "F_TYPE": "AP",
        "N_TYPE": "CISCO",
        "N_DEVICE_TYPE": "router",
        "N_CUSTOMER": 0,
        "USER_SERVICE_ID": 0,
        "CUSTOMER_PARENT": 0,
        "CUSTOMER_TYPE": null,
        "CUSTOMER_LOCATION": 0,
        "MAC": null,
        "UPDATE_FLAG": 0,
        "AGR_GROUP": null,
        "STREET": null,
        "HOUSE_ID": null,
        "N_ZIP": null,
        "N_CITY": null,
        "SOCKET": null,
        "N_COUNTER_ID": "000000",
        "N_PRODUCER": null,
        "N_SERIAL_NUM": null,
        "N_LAST_RESPONSE": null,
        "N_CT": "007",
        "N_CREATED": null,
        "N_L_ID": "000751",
        "N_GPS_LATITUDE": null,
        "N_GPS_LONGITUDE": null,
        "N_UCP_ID": null,
        "N_US_ID": null,
        "N_UA_ID": null,
        "N_CACHE_NAME": "quidem",
        "N_CACHE_LAST_WS_ID": null,
        "N_DELETED": null,
        "params": [
            {
                "ID": 301268715,
                "NODE_ID": 1792673,
                "NI_NPI_ID": 0,
                "PAR_NAME": "DATA_COUNTER",
                "PAR_INDEX": 0,
                "VALUE": "incidunt",
                "CONTENT": null,
                "TEXT_CONTENT": null
            }
        ],
        "customer_service_devices": [
            {
                "NS_ID": 2148173,
                "NS_N_ID": 1792673,
                "NS_U_ID": 1038,
                "NS_SA_ID": null,
                "NS_TIME": "2026-03-09 20:29:13",
                "NS_L_ID": 1,
                "NS_NEEDS_UPDATE": 0
            }
        ],
        "interfaces": [
            {
                "NPI_ID": 3312961,
                "NPI_N_ID": 1792673,
                "NPI_TYPE": 8,
                "NPI_NAME": "eths",
                "NPI_L_ID": 633,
                "NPI_CREATED": "2026-02-04 07:58:37",
                "NPI_CHANGED": null,
                "NPI_NOTE": ""
            }
        ]
    }
}

Request      

PUT api/v3/devices/{id}

PATCH api/v3/devices/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the device. Example: 48

Body Parameters

customer   integer  optional    

Device kind: 0=infrastructure, 1=customer (CPE) Example: 1

device_type   string  optional    

Specific device type Example: MikroTik RB750

name   string  optional    

Device name Example: AP Roof

premise_id   integer  optional    

Premise ID Example: 16

serial_num   string  optional    

Serial number Example: SN123456

ct   integer  optional    

Location/installation ID Example: 5

user_id   integer  optional    

Customer ID to bind Example: 16

services   integer[]  optional    

Service IDs to bind (array of SA_IDs)

street   string  optional    

Street address Example: Main Street

house_id   string  optional    

House number Example: 12A

zip   string  optional    

ZIP code Example: 56001

city   string  optional    

City Example: Prague

socket   string  optional    

Socket identifier Example: architecto

note   string  optional    

Notes Example: architecto

gps_latitude   string  optional    

GPS latitude (string to allow NULL) Example: 49.8175

gps_longitude   string  optional    

GPS longitude (string to allow NULL) Example: 15.473

params   object[]  optional    

Parameters as array of {name, value}
name   string  optional    

This field is required when params is present. Example: architecto

value   string  optional    

This field is required when params is present. Example: architecto

ucp_id   integer  optional    

UIR city part ID Example: 16

us_id   integer  optional    

UIR street ID Example: 16

ua_id   integer  optional    

UIR address ID Example: 16

Response

Response Fields

data   object     
ID   integer     

Unique device identifier (primary key, zero-filled to 6 digits).

NAME   string     

Device name (up to 30 characters).

NOTE   string     

Free-text note.

N_TYPE   string     

Device class / node type (e.g. LINUX, MIKROTIK, SWITCH, ONT, WIFI, CISCO, DOCSIS, …). Defines the parameter schema available for the device.

N_DEVICE_TYPE   string     

Specific device model or hardware type (e.g. 'MikroTik RB750', 'UBNT NanoStation', …).

F_TYPE   string     

Functional type. Possible values: AP, BRIDGE, IP, OLT, ONU, ROUTER, SIP, SWITCH.

N_CUSTOMER   integer     

Customer device flag. 1 = end-user device (CPE), 0 = infrastructure device.

CUSTOMER_PARENT   integer     

Flag indicating this infrastructure device can host customer (end-user) devices. 1 = open for customer connections.

CUSTOMER_TYPE   string     

Customer device sub-type (only relevant when N_CUSTOMER=1). E.g. LINUX, NIC, WIFI, DECODER, DS_MODEM, SIP_DEVICE, CIBSROUTER, etc.

MANAGED   integer     

Flag indicating the device is managed (configured) by the Mango system. 1 = managed.

MANAG_IP   string     

Management IP address of the device.

UPDATE_FLAG   integer     

Flag indicating the device configuration needs to be pushed/updated. 1 = update pending.

MAC   string     

MAC address of the device.

N_LAST_RESPONSE   string     

Datetime of the last successful SNMP monitoring response.

PARENT_NODE   integer     

ID of the parent device in the network topology. See GET /v3/devices/{id}.

USER_SERVICE_ID   integer     

ID of the associated customer service. See GET /v3/customer-services/{id}.

N_CT   integer     

Location / installation CT ID (for customer devices when N_CUSTOMER=1).

STREET   string     

Street name of the device location.

HOUSE_ID   string     

House number (číslo popisné) of the device location.

N_ZIP   string     

ZIP / postal code (up to 5 characters).

N_CITY   string     

City of the device location.

SOCKET   string     

Socket / apartment identifier at the device location.

N_GPS_LATITUDE   number     

GPS latitude of the device.

N_GPS_LONGITUDE   number     

GPS longitude of the device.

N_UCP_ID   integer     

UIR registry city part ID.

N_US_ID   integer     

UIR registry street ID.

N_UA_ID   integer     

UIR registry address ID.

N_PRODUCER   string     

Device manufacturer / producer.

N_SERIAL_NUM   string     

Serial number of the device.

N_CREATED   string     

Datetime when the device record was created.

N_L_ID   integer     

ID of the operator (login session) who last modified this device.

N_CACHE_NAME   string     

Cached display name combining class, type and device name for quick lookups.

N_CACHE_LAST_WS_ID   integer     

Cached ID of the last work session that touched this device.

CUSTOMER_LOCATION   integer     

Deprecated. Former customer location reference (now handled via nodes_cust_locations).

AGR_GROUP   integer     

Deprecated. Former aggregation group reference.

N_COUNTER_ID   integer     

Deprecated. Former counter ID (now stored as a device parameter).

params   object[]     

Device parameters — collection of key-value pairs from the node_info table.
ID   integer     

Unique device parameter identifier (primary key, zero-filled bigint).

NODE_ID   integer     

ID of the parent device. See GET /v3/devices/{id}.

NI_NPI_ID   integer     

Parameter definition index ID. 0 = device-level parameter.

PAR_NAME   string     

Parameter name / key (e.g. IP_ADDRESS, DATA_COUNTER, SERVICE_STATE, VIRTUAL_IP).

PAR_INDEX   integer     

Index for multi-valued parameters. 0 = single/first value; higher values represent additional entries of the same parameter.

VALUE   string     

Parameter value as a string (up to 255 characters). Interpretation depends on PAR_NAME and the parameter type.

CONTENT   string     

Binary content (longblob) for file-type parameters (e.g. uploaded configuration files). Base64-encoded when serialized.

TEXT_CONTENT   string     

Large text content for parameters that exceed the 255-character VALUE limit (longtext).

customer_service_devices   object[]     

Services bound to this device — collection of customer-service-device bindings from the nodes_services table.
NS_ID   integer     

Unique customer-service-device binding ID (primary key).

NS_N_ID   integer     

Device ID this service is bound to. See GET /v3/devices/{id}.

NS_U_ID   integer     

Customer ID who owns the service on this device. See GET /v3/customers/{id}.

NS_SA_ID   integer     

Active service (CustomerService) ID. Null when the binding exists without a specific active service. See GET /v3/customer-services/{id}.

NS_TIME   string     

Datetime when the service was bound to the device (YYYY-MM-DD HH:MM:SS).

NS_L_ID   integer     

Operator (login session) ID who created or last modified this binding.

NS_NEEDS_UPDATE   integer     

Flag indicating the device needs to schedule a configuration update because the service is activated in the future. 0 = no update needed, 1 = update pending.

interfaces   object[]     

Physical network interfaces — collection of interface records from the nodes_physical_interfaces table.
NPI_ID   integer     

Unique interface identifier (primary key).

NPI_N_ID   integer     

ID of the parent device (references nodes.ID).

NPI_TYPE   integer     

Interface type code (references code_list NODES_INT_TYPES). Common values: 1=Ethernet, 2=Wireless, 3=Optical.

NPI_NAME   string     

Interface name (e.g. eth0, wlan1, pon0).

NPI_L_ID   integer     

Operator (login session) ID who last modified this interface.

NPI_CREATED   string     

Datetime when the interface record was created.

NPI_CHANGED   string     

Datetime when the interface record was last modified.

NPI_NOTE   string     

Free-text note for the interface.

Delete Device

requires authentication

Delete a device (soft-delete).

Example request:
curl --request DELETE \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/devices/48" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/devices/48"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

Example response (204):

Empty response

Request      

DELETE api/v3/devices/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the device. Example: 48

List Device Children

requires authentication

Retrieve child devices of the specified device. Returns the same structure as the main device list endpoint.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/devices/48/children?ids=1%2C2%2C3&cts=1%2C2%2C3&kind=AP&parent_id=100&child_id=200&groups=5%2C10&service_ids=1%2C2&user_id=100" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/devices/48/children"
);

const params = {
    "ids": "1,2,3",
    "cts": "1,2,3",
    "kind": "AP",
    "parent_id": "100",
    "child_id": "200",
    "groups": "5,10",
    "service_ids": "1,2",
    "user_id": "100",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "ID": 1792674,
            "NAME": "DEV-cpscql",
            "NOTE": null,
            "MANAGED": 1,
            "MANAG_IP": "20.76.47.75",
            "PARENT_NODE": null,
            "F_TYPE": "ONU",
            "N_TYPE": "UBNT",
            "N_DEVICE_TYPE": "ap",
            "N_CUSTOMER": 1,
            "USER_SERVICE_ID": 0,
            "CUSTOMER_PARENT": 0,
            "CUSTOMER_TYPE": null,
            "CUSTOMER_LOCATION": 0,
            "MAC": null,
            "UPDATE_FLAG": 0,
            "AGR_GROUP": null,
            "STREET": null,
            "HOUSE_ID": null,
            "N_ZIP": null,
            "N_CITY": null,
            "SOCKET": null,
            "N_COUNTER_ID": "000000",
            "N_PRODUCER": null,
            "N_SERIAL_NUM": null,
            "N_LAST_RESPONSE": null,
            "N_CT": "076",
            "N_CREATED": null,
            "N_L_ID": "000258",
            "N_GPS_LATITUDE": null,
            "N_GPS_LONGITUDE": null,
            "N_UCP_ID": null,
            "N_US_ID": null,
            "N_UA_ID": null,
            "N_CACHE_NAME": "adipisci",
            "N_CACHE_LAST_WS_ID": null,
            "N_DELETED": null,
            "params": [
                {
                    "ID": 301268716,
                    "NODE_ID": 1792674,
                    "NI_NPI_ID": 0,
                    "PAR_NAME": "infra_loc",
                    "PAR_INDEX": 0,
                    "VALUE": null,
                    "CONTENT": null,
                    "TEXT_CONTENT": null
                }
            ],
            "customer_service_devices": [
                {
                    "NS_ID": 2148174,
                    "NS_N_ID": 1792674,
                    "NS_U_ID": 1038,
                    "NS_SA_ID": null,
                    "NS_TIME": "2026-02-26 18:15:32",
                    "NS_L_ID": 1,
                    "NS_NEEDS_UPDATE": 0
                }
            ],
            "interfaces": [
                {
                    "NPI_ID": 3312962,
                    "NPI_N_ID": 1792674,
                    "NPI_TYPE": 3,
                    "NPI_NAME": "ethp",
                    "NPI_L_ID": 535,
                    "NPI_CREATED": "2026-03-30 10:08:42",
                    "NPI_CHANGED": null,
                    "NPI_NOTE": ""
                }
            ]
        },
        {
            "ID": 1792675,
            "NAME": "DEV-qbewtn",
            "NOTE": "Odit quia officia est dignissimos neque blanditiis odio.",
            "MANAGED": 1,
            "MANAG_IP": null,
            "PARENT_NODE": null,
            "F_TYPE": "ONU",
            "N_TYPE": "LINUX",
            "N_DEVICE_TYPE": "switch",
            "N_CUSTOMER": 0,
            "USER_SERVICE_ID": 0,
            "CUSTOMER_PARENT": 0,
            "CUSTOMER_TYPE": null,
            "CUSTOMER_LOCATION": 0,
            "MAC": null,
            "UPDATE_FLAG": 0,
            "AGR_GROUP": null,
            "STREET": null,
            "HOUSE_ID": null,
            "N_ZIP": null,
            "N_CITY": null,
            "SOCKET": null,
            "N_COUNTER_ID": "000000",
            "N_PRODUCER": null,
            "N_SERIAL_NUM": null,
            "N_LAST_RESPONSE": null,
            "N_CT": "006",
            "N_CREATED": null,
            "N_L_ID": "000760",
            "N_GPS_LATITUDE": null,
            "N_GPS_LONGITUDE": null,
            "N_UCP_ID": null,
            "N_US_ID": null,
            "N_UA_ID": null,
            "N_CACHE_NAME": "est",
            "N_CACHE_LAST_WS_ID": null,
            "N_DELETED": null,
            "params": [
                {
                    "ID": 301268717,
                    "NODE_ID": 1792675,
                    "NI_NPI_ID": 0,
                    "PAR_NAME": "VIRTUAL_IP",
                    "PAR_INDEX": 0,
                    "VALUE": null,
                    "CONTENT": null,
                    "TEXT_CONTENT": null
                }
            ],
            "customer_service_devices": [
                {
                    "NS_ID": 2148175,
                    "NS_N_ID": 1792675,
                    "NS_U_ID": 1038,
                    "NS_SA_ID": null,
                    "NS_TIME": "2026-02-12 16:26:51",
                    "NS_L_ID": 1,
                    "NS_NEEDS_UPDATE": 0
                }
            ],
            "interfaces": [
                {
                    "NPI_ID": 3312963,
                    "NPI_N_ID": 1792675,
                    "NPI_TYPE": 9,
                    "NPI_NAME": "ethg",
                    "NPI_L_ID": 301,
                    "NPI_CREATED": "2026-03-03 05:13:39",
                    "NPI_CHANGED": null,
                    "NPI_NOTE": ""
                }
            ]
        }
    ]
}

Request      

GET api/v3/devices/{device}/children

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

device   integer     

The device. Example: 48

Query Parameters

ids   string  optional    

Filter by comma-separated device IDs Example: 1,2,3

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Uses complex device CT logic. Example: 1,2,3

kind   string  optional    

Filter by device type (N_TYPE) Example: AP

parent_id   integer  optional    

Filter by parent device ID (devices connected under this parent) Example: 100

child_id   integer  optional    

Filter by child device ID (returns the parent device above this child) Example: 200

groups   string  optional    

Filter by device group ID(s), comma-separated Example: 5,10

service_ids   string  optional    

Filter by service IDs (comma-separated), devices linked to these services Example: 1,2

user_id   integer  optional    

Filter by customer ID, devices linked to this customer via nodes_services Example: 100

Response

Response Fields

data   object     
ID   integer     

Unique device identifier (primary key, zero-filled to 6 digits).

NAME   string     

Device name (up to 30 characters).

NOTE   string     

Free-text note.

N_TYPE   string     

Device class / node type (e.g. LINUX, MIKROTIK, SWITCH, ONT, WIFI, CISCO, DOCSIS, …). Defines the parameter schema available for the device.

N_DEVICE_TYPE   string     

Specific device model or hardware type (e.g. 'MikroTik RB750', 'UBNT NanoStation', …).

F_TYPE   string     

Functional type. Possible values: AP, BRIDGE, IP, OLT, ONU, ROUTER, SIP, SWITCH.

N_CUSTOMER   integer     

Customer device flag. 1 = end-user device (CPE), 0 = infrastructure device.

CUSTOMER_PARENT   integer     

Flag indicating this infrastructure device can host customer (end-user) devices. 1 = open for customer connections.

CUSTOMER_TYPE   string     

Customer device sub-type (only relevant when N_CUSTOMER=1). E.g. LINUX, NIC, WIFI, DECODER, DS_MODEM, SIP_DEVICE, CIBSROUTER, etc.

MANAGED   integer     

Flag indicating the device is managed (configured) by the Mango system. 1 = managed.

MANAG_IP   string     

Management IP address of the device.

UPDATE_FLAG   integer     

Flag indicating the device configuration needs to be pushed/updated. 1 = update pending.

MAC   string     

MAC address of the device.

N_LAST_RESPONSE   string     

Datetime of the last successful SNMP monitoring response.

PARENT_NODE   integer     

ID of the parent device in the network topology. See GET /v3/devices/{id}.

USER_SERVICE_ID   integer     

ID of the associated customer service. See GET /v3/customer-services/{id}.

N_CT   integer     

Location / installation CT ID (for customer devices when N_CUSTOMER=1).

STREET   string     

Street name of the device location.

HOUSE_ID   string     

House number (číslo popisné) of the device location.

N_ZIP   string     

ZIP / postal code (up to 5 characters).

N_CITY   string     

City of the device location.

SOCKET   string     

Socket / apartment identifier at the device location.

N_GPS_LATITUDE   number     

GPS latitude of the device.

N_GPS_LONGITUDE   number     

GPS longitude of the device.

N_UCP_ID   integer     

UIR registry city part ID.

N_US_ID   integer     

UIR registry street ID.

N_UA_ID   integer     

UIR registry address ID.

N_PRODUCER   string     

Device manufacturer / producer.

N_SERIAL_NUM   string     

Serial number of the device.

N_CREATED   string     

Datetime when the device record was created.

N_L_ID   integer     

ID of the operator (login session) who last modified this device.

N_CACHE_NAME   string     

Cached display name combining class, type and device name for quick lookups.

N_CACHE_LAST_WS_ID   integer     

Cached ID of the last work session that touched this device.

CUSTOMER_LOCATION   integer     

Deprecated. Former customer location reference (now handled via nodes_cust_locations).

AGR_GROUP   integer     

Deprecated. Former aggregation group reference.

N_COUNTER_ID   integer     

Deprecated. Former counter ID (now stored as a device parameter).

params   object[]     

Device parameters — collection of key-value pairs from the node_info table.
ID   integer     

Unique device parameter identifier (primary key, zero-filled bigint).

NODE_ID   integer     

ID of the parent device. See GET /v3/devices/{id}.

NI_NPI_ID   integer     

Parameter definition index ID. 0 = device-level parameter.

PAR_NAME   string     

Parameter name / key (e.g. IP_ADDRESS, DATA_COUNTER, SERVICE_STATE, VIRTUAL_IP).

PAR_INDEX   integer     

Index for multi-valued parameters. 0 = single/first value; higher values represent additional entries of the same parameter.

VALUE   string     

Parameter value as a string (up to 255 characters). Interpretation depends on PAR_NAME and the parameter type.

CONTENT   string     

Binary content (longblob) for file-type parameters (e.g. uploaded configuration files). Base64-encoded when serialized.

TEXT_CONTENT   string     

Large text content for parameters that exceed the 255-character VALUE limit (longtext).

customer_service_devices   object[]     

Services bound to this device — collection of customer-service-device bindings from the nodes_services table.
NS_ID   integer     

Unique customer-service-device binding ID (primary key).

NS_N_ID   integer     

Device ID this service is bound to. See GET /v3/devices/{id}.

NS_U_ID   integer     

Customer ID who owns the service on this device. See GET /v3/customers/{id}.

NS_SA_ID   integer     

Active service (CustomerService) ID. Null when the binding exists without a specific active service. See GET /v3/customer-services/{id}.

NS_TIME   string     

Datetime when the service was bound to the device (YYYY-MM-DD HH:MM:SS).

NS_L_ID   integer     

Operator (login session) ID who created or last modified this binding.

NS_NEEDS_UPDATE   integer     

Flag indicating the device needs to schedule a configuration update because the service is activated in the future. 0 = no update needed, 1 = update pending.

interfaces   object[]     

Physical network interfaces — collection of interface records from the nodes_physical_interfaces table.
NPI_ID   integer     

Unique interface identifier (primary key).

NPI_N_ID   integer     

ID of the parent device (references nodes.ID).

NPI_TYPE   integer     

Interface type code (references code_list NODES_INT_TYPES). Common values: 1=Ethernet, 2=Wireless, 3=Optical.

NPI_NAME   string     

Interface name (e.g. eth0, wlan1, pon0).

NPI_L_ID   integer     

Operator (login session) ID who last modified this interface.

NPI_CREATED   string     

Datetime when the interface record was created.

NPI_CHANGED   string     

Datetime when the interface record was last modified.

NPI_NOTE   string     

Free-text note for the interface.

Discount Definitions

List Discount Definitions

requires authentication

Returns a paginated list of discount campaign definitions. Filterable by type, service class, service, area, active status, and more.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/discount-definitions?per_page=15&page=1&ids=1%2C2%2C3&cts=1%2C2%2C3&active_only=1&type=percentage&service_class=1&service=10&service_group=5&area=3&applies_to_groups=&search=internet" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/discount-definitions"
);

const params = {
    "per_page": "15",
    "page": "1",
    "ids": "1,2,3",
    "cts": "1,2,3",
    "active_only": "1",
    "type": "percentage",
    "service_class": "1",
    "service": "10",
    "service_group": "5",
    "area": "3",
    "applies_to_groups": "0",
    "search": "internet",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "SD_ID": 1722,
            "SD_NAME": "aut adipisci quidem",
            "SD_GROUPS": "none",
            "SD_TYPE": "info",
            "SD_SC_ID": null,
            "SD_SN_ID": null,
            "SD_SNB_ID": null,
            "SD_SND_IDS": null,
            "SD_SGD_ID": null,
            "SD_GA_ID": null,
            "SD_VALUE": "42.5404",
            "SD_VARIABILITY": "none",
            "SD_CONDITION": null,
            "SD_CONDITION_PERIOD": null,
            "SD_TIME_LIMITED": null,
            "SD_TRADING_LIMIT": null,
            "SD_VALID_TO": null,
            "SD_GROUP": null,
            "SD_NOTE": null,
            "SD_CREATED": "2026-02-08 13:41:06",
            "SD_L_ID": 709,
            "SD_CT": 3,
            "SD_START_DELAY": null,
            "SD_CONDITION_END": "pay_duly",
            "SD_END_PENALTY": null,
            "SD_CASH": null,
            "SD_INVOICE": null,
            "SD_PROFORMA": null,
            "SD_START_RECREATE": 1,
            "SD_BULK_TRANSFER": 0,
            "SD_END_NOTIFY": null,
            "SD_FORCED": null,
            "SD_FLOATING": null,
            "available_for_classes": [
                15
            ],
            "available_for_services": [
                28
            ]
        },
        {
            "SD_ID": 1723,
            "SD_NAME": "ipsum nostrum omnis",
            "SD_GROUPS": "none",
            "SD_TYPE": "definite",
            "SD_SC_ID": null,
            "SD_SN_ID": null,
            "SD_SNB_ID": null,
            "SD_SND_IDS": null,
            "SD_SGD_ID": null,
            "SD_GA_ID": null,
            "SD_VALUE": "76.5282",
            "SD_VARIABILITY": "none",
            "SD_CONDITION": null,
            "SD_CONDITION_PERIOD": null,
            "SD_TIME_LIMITED": null,
            "SD_TRADING_LIMIT": null,
            "SD_VALID_TO": null,
            "SD_GROUP": null,
            "SD_NOTE": null,
            "SD_CREATED": "2026-01-08 14:18:49",
            "SD_L_ID": 94,
            "SD_CT": 6,
            "SD_START_DELAY": null,
            "SD_CONDITION_END": "pay_duly",
            "SD_END_PENALTY": null,
            "SD_CASH": null,
            "SD_INVOICE": null,
            "SD_PROFORMA": null,
            "SD_START_RECREATE": 1,
            "SD_BULK_TRANSFER": 0,
            "SD_END_NOTIFY": null,
            "SD_FORCED": null,
            "SD_FLOATING": null,
            "available_for_classes": [
                2
            ],
            "available_for_services": [
                25
            ]
        }
    ]
}

Request      

GET api/v3/discount-definitions

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of results per page. Example: 15

page   integer  optional    

Page number. Example: 1

ids   string  optional    

Filter by comma-separated discount definition IDs. Example: 1,2,3

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Example: 1,2,3

active_only   boolean  optional    

When true, return only definitions whose validity has not expired (SD_VALID_TO is null or >= today). Example: true

type   string  optional    

Filter by discount type. Example: percentage

service_class   integer  optional    

Filter by service class ID (checks M:N pivot table). Example: 1

service   integer  optional    

Filter by service name ID (checks M:N pivot table). Example: 10

service_group   integer  optional    

Filter by service group definition ID (SD_SGD_ID). Example: 5

area   integer  optional    

Filter by address group / area ID (SD_GA_ID). Example: 3

applies_to_groups   boolean  optional    

Filter by campaign mode. true = group campaigns only, false = standard campaigns only. Example: false

search   string  optional    

Search in discount name and note (partial match). Example: internet

Response

Response Fields

data   object     
SD_ID   integer     

Unique discount definition identifier (primary key).

SD_NAME   string     

Campaign name.

SD_GROUPS   string     

Campaign mode. 'none' = standard, 'groups' = group campaign.

Must be one of:
  • none
  • groups
SD_TYPE   string     

Discount type.

Must be one of:
  • percentage
  • definite
  • info
  • credit
  • points
SD_SC_ID   integer     

Legacy service class FK (prefer available_for_classes relation).

SD_SN_ID   integer     

Legacy service name FK (prefer available_for_services relation).

SD_SNB_ID   integer     

Base service ID for condition-based discounts (depending type).

SD_SND_IDS   string     

Comma-separated dependent service IDs.

SD_SGD_ID   integer     

Service group definition ID.

SD_GA_ID   integer     

Address group (area) ID.

SD_VALUE   string     

Discount value (percentage or fixed amount depending on SD_TYPE). Decimal(12,4).

SD_VARIABILITY   string     

Price variability.

Must be one of:
  • none
  • maximum
  • minimum
SD_CONDITION   string     

Condition for granting the discount.

Must be one of:
  • trading_limit
  • motivation1
  • pay_duly
  • depending
  • period
SD_CONDITION_PERIOD   string     

Condition period identifier.

SD_CONDITION_END   string     

Condition for ending the discount.

Must be one of:
  • pay_duly
SD_END_PENALTY   string     

Penalty on early termination.

Must be one of:
  • none
  • service
SD_TIME_LIMITED   integer     

Duration limit in months.

SD_TRADING_LIMIT   integer     

Minimum contract commitment in months.

SD_VALID_TO   string     

Campaign expiry date (YYYY-MM-DD). Null = no expiry.

SD_START_DELAY   integer     

Start delay in months.

SD_FORCED   integer     

Forced discount flag (1 = yes).

SD_FLOATING   integer     

Floating discount flag (1 = yes, end date follows contract period).

SD_START_RECREATE   integer     

Auto-adjust start/end when service "Pay from" changes (1 = yes).

SD_BULK_TRANSFER   integer     

Allow bulk auto-activation on service changes (1 = yes).

SD_INVOICE   integer     

Show on invoices (1 = yes).

SD_PROFORMA   integer     

Show on proforma invoices (1 = yes).

SD_CASH   integer     

Payment account ID.

SD_GROUP   integer     

Exclusivity group — discounts in the same group cannot be combined.

SD_END_NOTIFY   integer     

Days before expiry to send notification.

SD_NOTE   string     

Free-text note.

SD_CREATED   string     

Creation timestamp (datetime).

SD_L_ID   integer     

Creator operator (login) ID.

SD_CT   integer     

Location (CT) ID. 0 = global (visible to all locations).

available_for_classes   integer[]     

Service class IDs this campaign applies to (from M:N pivot).

available_for_services   integer[]     

Service name IDs this campaign applies to (from M:N pivot).

applied_to_services   integer[]     

Active service IDs where this discount is currently applied. Only included in detail (show) response.

Get Discount Definition

requires authentication

Returns a single discount campaign definition by ID. Includes applied_to_services — active service IDs where this discount is currently assigned.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/discount-definitions/48" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/discount-definitions/48"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "SD_ID": 1724,
        "SD_NAME": "aut adipisci quidem",
        "SD_GROUPS": "none",
        "SD_TYPE": "info",
        "SD_SC_ID": null,
        "SD_SN_ID": null,
        "SD_SNB_ID": null,
        "SD_SND_IDS": null,
        "SD_SGD_ID": null,
        "SD_GA_ID": null,
        "SD_VALUE": "42.5404",
        "SD_VARIABILITY": "none",
        "SD_CONDITION": null,
        "SD_CONDITION_PERIOD": null,
        "SD_TIME_LIMITED": null,
        "SD_TRADING_LIMIT": null,
        "SD_VALID_TO": null,
        "SD_GROUP": null,
        "SD_NOTE": null,
        "SD_CREATED": "2026-02-08 13:34:45",
        "SD_L_ID": 709,
        "SD_CT": 3,
        "SD_START_DELAY": null,
        "SD_CONDITION_END": "pay_duly",
        "SD_END_PENALTY": null,
        "SD_CASH": null,
        "SD_INVOICE": null,
        "SD_PROFORMA": null,
        "SD_START_RECREATE": 1,
        "SD_BULK_TRANSFER": 0,
        "SD_END_NOTIFY": null,
        "SD_FORCED": null,
        "SD_FLOATING": null,
        "available_for_classes": [
            15
        ],
        "available_for_services": [
            28
        ],
        "applied_to_services": [
            6877
        ]
    }
}

Request      

GET api/v3/discount-definitions/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the discount definition. Example: 48

Response

Response Fields

data   object     
SD_ID   integer     

Unique discount definition identifier (primary key).

SD_NAME   string     

Campaign name.

SD_GROUPS   string     

Campaign mode. 'none' = standard, 'groups' = group campaign.

Must be one of:
  • none
  • groups
SD_TYPE   string     

Discount type.

Must be one of:
  • percentage
  • definite
  • info
  • credit
  • points
SD_SC_ID   integer     

Legacy service class FK (prefer available_for_classes relation).

SD_SN_ID   integer     

Legacy service name FK (prefer available_for_services relation).

SD_SNB_ID   integer     

Base service ID for condition-based discounts (depending type).

SD_SND_IDS   string     

Comma-separated dependent service IDs.

SD_SGD_ID   integer     

Service group definition ID.

SD_GA_ID   integer     

Address group (area) ID.

SD_VALUE   string     

Discount value (percentage or fixed amount depending on SD_TYPE). Decimal(12,4).

SD_VARIABILITY   string     

Price variability.

Must be one of:
  • none
  • maximum
  • minimum
SD_CONDITION   string     

Condition for granting the discount.

Must be one of:
  • trading_limit
  • motivation1
  • pay_duly
  • depending
  • period
SD_CONDITION_PERIOD   string     

Condition period identifier.

SD_CONDITION_END   string     

Condition for ending the discount.

Must be one of:
  • pay_duly
SD_END_PENALTY   string     

Penalty on early termination.

Must be one of:
  • none
  • service
SD_TIME_LIMITED   integer     

Duration limit in months.

SD_TRADING_LIMIT   integer     

Minimum contract commitment in months.

SD_VALID_TO   string     

Campaign expiry date (YYYY-MM-DD). Null = no expiry.

SD_START_DELAY   integer     

Start delay in months.

SD_FORCED   integer     

Forced discount flag (1 = yes).

SD_FLOATING   integer     

Floating discount flag (1 = yes, end date follows contract period).

SD_START_RECREATE   integer     

Auto-adjust start/end when service "Pay from" changes (1 = yes).

SD_BULK_TRANSFER   integer     

Allow bulk auto-activation on service changes (1 = yes).

SD_INVOICE   integer     

Show on invoices (1 = yes).

SD_PROFORMA   integer     

Show on proforma invoices (1 = yes).

SD_CASH   integer     

Payment account ID.

SD_GROUP   integer     

Exclusivity group — discounts in the same group cannot be combined.

SD_END_NOTIFY   integer     

Days before expiry to send notification.

SD_NOTE   string     

Free-text note.

SD_CREATED   string     

Creation timestamp (datetime).

SD_L_ID   integer     

Creator operator (login) ID.

SD_CT   integer     

Location (CT) ID. 0 = global (visible to all locations).

available_for_classes   integer[]     

Service class IDs this campaign applies to (from M:N pivot).

available_for_services   integer[]     

Service name IDs this campaign applies to (from M:N pivot).

applied_to_services   integer[]     

Active service IDs where this discount is currently applied. Only included in detail (show) response.

Endpoints

GET api/s-cloud/tickets

requires authentication

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/s-cloud/tickets?myScloudUserId=123&zombieDays=30&iAmReferee=1&iAmSupervisor=&per_page=10&page=1&typeId=448%2C463%2C479&types=type1%2Ctype2&machineIds=1%2C2%2C3&lastActivityFrom=2023-01-01&order=name%3Aasc%2Ccreated_at%3Adesc" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"myScloudUserId\": 16,
    \"zombieDays\": 39,
    \"iAmReferee\": true,
    \"iAmSupervisor\": true
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/s-cloud/tickets"
);

const params = {
    "myScloudUserId": "123",
    "zombieDays": "30",
    "iAmReferee": "1",
    "iAmSupervisor": "0",
    "per_page": "10",
    "page": "1",
    "typeId": "448,463,479",
    "types": "type1,type2",
    "machineIds": "1,2,3",
    "lastActivityFrom": "2023-01-01",
    "order": "name:asc,created_at:desc",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "myScloudUserId": 16,
    "zombieDays": 39,
    "iAmReferee": true,
    "iAmSupervisor": true
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "message": "Unauthenticated."
}

Request      

GET api/s-cloud/tickets

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

myScloudUserId   integer     

ID of the SCloud user Example: 123

zombieDays   integer     

Number of days to consider a maintenance as zombie Example: 30

iAmReferee   boolean     

Indicates if the user is a referee Example: true

iAmSupervisor   boolean     

Indicates if the user is a supervisor Example: false

per_page   integer  optional    

Number of users to return per page (optional) Example: 10

page   integer  optional    

Page number to return (optional) Example: 1

typeId   string  optional    

Filter by type ID of the maintenance list Example: 448,463,479

types   string  optional    

Filter by types of the maintenance list Example: type1,type2

machineIds   string  optional    

Filter by machine IDs of the maintenance list Example: 1,2,3

lastActivityFrom   string  optional    

Filter by last activity date from (optional) Example: 2023-01-01

order   string  optional    

Order by column and direction Example: name:asc,created_at:desc

Body Parameters

myScloudUserId   integer     

Example: 16

zombieDays   integer     

Must be at least 0. Example: 39

iAmReferee   boolean     

Example: true

iAmSupervisor   boolean     

Example: true

Esbe

Orders

requires authentication

This endpoint create an empty order. The next step is to add products to the order.

Example request:
curl --request POST \
    "https://apiv3-test.devel.ogsoftdev.com/api/esbe/orders?user_id=16&transport_service_id=16&billing_plan_id=16&transport_premise_id=16&order_date=architecto&note=architecto&delivery_date=architecto" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"user_id\": 16,
    \"transport_service_id\": 16,
    \"billing_plan_id\": 16,
    \"transport_premise_id\": 16,
    \"order_date\": \"2026-04-15T14:55:08\",
    \"note\": \"architecto\",
    \"delivery_date\": \"2026-04-15T14:55:08\"
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/esbe/orders"
);

const params = {
    "user_id": "16",
    "transport_service_id": "16",
    "billing_plan_id": "16",
    "transport_premise_id": "16",
    "order_date": "architecto",
    "note": "architecto",
    "delivery_date": "architecto",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "user_id": 16,
    "transport_service_id": 16,
    "billing_plan_id": 16,
    "transport_premise_id": 16,
    "order_date": "2026-04-15T14:55:08",
    "note": "architecto",
    "delivery_date": "2026-04-15T14:55:08"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "order_id": "int Example: 12345"
}

Request      

POST api/esbe/orders

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

user_id   integer     

ID of the user placing the order Example: 16

transport_service_id   integer  optional    

ID of the transport service Example: 16

billing_plan_id   integer  optional    

ID of the billing plan Example: 16

transport_premise_id   integer  optional    

ID of the transport premise Example: 16

order_date   date  optional    

Date of the order Example: architecto

note   string  optional    

Optional note for the order Example: architecto

delivery_date   date  optional    

Date of the delivery Example: architecto

Body Parameters

user_id   integer  optional    

Example: 16

transport_service_id   integer  optional    

Example: 16

billing_plan_id   integer  optional    

Example: 16

transport_premise_id   integer  optional    

Example: 16

order_date   string  optional    

Must be a valid date. Example: 2026-04-15T14:55:08

note   string  optional    

Example: architecto

delivery_date   string  optional    

Must be a valid date. Example: 2026-04-15T14:55:08

Add Single Item

requires authentication

This endpoint adds a single item to an existing order.

Example request:
curl --request POST \
    "https://apiv3-test.devel.ogsoftdev.com/api/esbe/orders/architecto/item" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"user_id\": 41994,
    \"product_id\": 101,
    \"quantity\": 2,
    \"price\": 150.5,
    \"price_wo_vat\": 124.38,
    \"parent_product_id\": 9876
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/esbe/orders/architecto/item"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "user_id": 41994,
    "product_id": 101,
    "quantity": 2,
    "price": 150.5,
    "price_wo_vat": 124.38,
    "parent_product_id": 9876
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "order_item_id": "int Example: 67890",
    "personalized_product_id": "int Example: 54321"
}

Request      

POST api/esbe/orders/{order}/item

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

order   string     

The order. Example: architecto

Body Parameters

user_id   integer     

ID of the user who owns the order. Example: 41994

product_id   integer     

The ID of the product (SN_ID). Example: 101

quantity   integer     

The quantity of the product. Example: 2

price   numeric     

The total price for the given quantity of this item. Example: 150.5

price_wo_vat   numeric     

The total price without VAT. Example: 124.38

parent_product_id   integer  optional    

The ID of the parent personalized product, if this is a secondary item. Example: 9876

Update Single Item

requires authentication

This endpoint update a single item in an existing order.

Example request:
curl --request PUT \
    "https://apiv3-test.devel.ogsoftdev.com/api/esbe/orders/architecto/item" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"user_id\": 41994,
    \"product_id\": 101,
    \"quantity\": 2,
    \"price\": 150.5,
    \"price_wo_vat\": 124.38
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/esbe/orders/architecto/item"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "user_id": 41994,
    "product_id": 101,
    "quantity": 2,
    "price": 150.5,
    "price_wo_vat": 124.38
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "personalized_product_id": "int Example: 54321"
}

Request      

PUT api/esbe/orders/{order}/item

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

order   string     

The order. Example: architecto

Body Parameters

user_id   integer     

ID of the user who owns the order. Example: 41994

product_id   integer     

The ID of the product (SN_ID). Example: 101

quantity   integer     

The quantity of the product. Example: 2

price   numeric     

The total price for the given quantity of this item. Example: 150.5

price_wo_vat   numeric     

The total price without VAT. Example: 124.38

Finalize Order

requires authentication

This endpoint finalizes or "realizes" an order that has all its items. This is the final step to make an order active.

Example request:
curl --request POST \
    "https://apiv3-test.devel.ogsoftdev.com/api/esbe/orders/architecto/realize" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"delivery_date\": \"2025-09-10 00:00:00\",
    \"note\": \"architecto\",
    \"recipient_person\": \"architecto\",
    \"recipient_phone\": \"architecto\",
    \"reference_number\": \"architecto\",
    \"recipient_city\": \"architecto\",
    \"recipient_zip\": \"architecto\",
    \"recipient_street\": \"architecto\",
    \"recipient_house_id\": \"architecto\",
    \"transport_premise_id\": 16,
    \"transport_service_id\": 16,
    \"billing_plan_id\": 16
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/esbe/orders/architecto/realize"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "delivery_date": "2025-09-10 00:00:00",
    "note": "architecto",
    "recipient_person": "architecto",
    "recipient_phone": "architecto",
    "reference_number": "architecto",
    "recipient_city": "architecto",
    "recipient_zip": "architecto",
    "recipient_street": "architecto",
    "recipient_house_id": "architecto",
    "transport_premise_id": 16,
    "transport_service_id": 16,
    "billing_plan_id": 16
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "message": "Order finalized successfully."
}

Request      

POST api/esbe/orders/{order}/realize

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

order   string     

The order. Example: architecto

Body Parameters

delivery_date   string     

The planned delivery date for the order. Example: 2025-09-10 00:00:00

note   string  optional    

An optional note for the realization. Example: architecto

recipient_person   string  optional    

The name of the recipient. Example: architecto

recipient_phone   string  optional    

The phone number of the recipient. Example: architecto

reference_number   string  optional    

The reference number of the order. Example: architecto

recipient_city   string  optional    

The city of the recipient. Example: architecto

recipient_zip   string  optional    

The zip code of the recipient. Example: architecto

recipient_street   string  optional    

The street of the recipient. Example: architecto

recipient_house_id   string  optional    

The house ID of the recipient. Example: architecto

transport_premise_id   integer  optional    

The ID of the transport premise. Example: 16

transport_service_id   integer  optional    

The ID of the transport service. Example: 16

billing_plan_id   integer  optional    

The ID of the billing plan. Example: 16

Generate Order Number

requires authentication

This endpoint generates a unique order number for an existing order. If the order already has a number, it returns the existing one.

Example request:
curl --request POST \
    "https://apiv3-test.devel.ogsoftdev.com/api/esbe/orders/architecto/generate-number" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/esbe/orders/architecto/generate-number"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": "boolean Example: true",
    "order_number": "int Example: 202409240001",
    "updated": "boolean Example: true"
}

Request      

POST api/esbe/orders/{order}/generate-number

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

order   string     

The order. Example: architecto

Update Order User

requires authentication

This endpoint updates the user assigned to an order and all its items. It also updates associated personalized products and service data.

Example request:
curl --request PATCH \
    "https://apiv3-test.devel.ogsoftdev.com/api/esbe/orders/architecto/user" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"user_id\": 12345
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/esbe/orders/architecto/user"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "user_id": 12345
};

fetch(url, {
    method: "PATCH",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "success": "boolean Example: true",
    "user_id": "int Example: 12345"
}

Request      

PATCH api/esbe/orders/{order}/user

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

order   string     

The order. Example: architecto

Body Parameters

user_id   integer     

The ID of the user to assign to the order. Example: 12345

Delete Order

requires authentication

This endpoint deletes an order. This should be used for cleanup if the ordering process fails.

Example request:
curl --request DELETE \
    "https://apiv3-test.devel.ogsoftdev.com/api/esbe/orders/architecto" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/esbe/orders/architecto"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

Example response (204):

Empty response

Request      

DELETE api/esbe/orders/{order}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

order   string     

The order. Example: architecto

Remove Single Item

requires authentication

This endpoint removes a single item from an existing order.

Example request:
curl --request DELETE \
    "https://apiv3-test.devel.ogsoftdev.com/api/esbe/orders/architecto/item" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"product_id\": 12345
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/esbe/orders/architecto/item"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "product_id": 12345
};

fetch(url, {
    method: "DELETE",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "success": "boolean Example: true"
}

Request      

DELETE api/esbe/orders/{order}/item

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

order   string     

The order. Example: architecto

Body Parameters

product_id   integer     

The ID of the product/item to remove from the order. Example: 12345

Send Email Using Template

requires authentication

This endpoint sends an email using a predefined template. It processes the template with provided parameters and sends the email to the specified recipient.

Example request:
curl --request POST \
    "https://apiv3-test.devel.ogsoftdev.com/api/esbe/send-email-using-template" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"from\": \"[email protected]\",
    \"to\": \"[email protected]\",
    \"ctype\": \"architecto\",
    \"sched\": \"architecto\",
    \"ct\": \"architecto\",
    \"tt_name\": \"order_confirmation\",
    \"params\": \"architecto\",
    \"parsep\": \"architecto\",
    \"valsep\": \"architecto\"
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/esbe/send-email-using-template"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "from": "[email protected]",
    "to": "[email protected]",
    "ctype": "architecto",
    "sched": "architecto",
    "ct": "architecto",
    "tt_name": "order_confirmation",
    "params": "architecto",
    "parsep": "architecto",
    "valsep": "architecto"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "result": "string Example: success",
    "eo_ids": "string Example: 123,456"
}

Request      

POST api/esbe/send-email-using-template

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Body Parameters

from   string  optional    

Email sender address Example: [email protected]

to   string     

Email recipient address Example: [email protected]

ctype   string  optional    

Content type Example: architecto

sched   string  optional    

Schedule parameter Example: architecto

ct   string  optional    

CT parameter Example: architecto

tt_name   string     

Template name Example: order_confirmation

params   string  optional    

Template parameters Example: architecto

parsep   string  optional    

Parameter separator Example: architecto

valsep   string  optional    

Value separator Example: architecto

Internal Tax Documents

List Internal Tax Documents

requires authentication

Returns a paginated list of internal tax documents (billing prescriptions). At least one of the following filters must be provided: customer, type, date_from, service, search. Without a narrowing filter the endpoint returns HTTP 422.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/internal-tax-documents?per_page=10&page=1&ids=100%2C200%2C300&cts=1%2C2%2C3&customer=345&type=SERVICE%2CCREDIT_NOTE&date_from=2024-01-01&date_to=2024-12-31&service=19&service_class=1&billing_plan=5&search=100000" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/internal-tax-documents"
);

const params = {
    "per_page": "10",
    "page": "1",
    "ids": "100,200,300",
    "cts": "1,2,3",
    "customer": "345",
    "type": "SERVICE,CREDIT_NOTE",
    "date_from": "2024-01-01",
    "date_to": "2024-12-31",
    "service": "19",
    "service_class": "1",
    "billing_plan": "5",
    "search": "100000",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "ID": 0,
            "ITD_ADVANCE_ID": 110,
            "ITD_TYPE": "NON_ATTACH",
            "USER_ID": 4524,
            "SRV_ID": 2617,
            "Y": 2025,
            "MON": 4,
            "ITD_DAY": null,
            "ITD_Y_END": 2023,
            "MON_END": null,
            "ITD_DAY_END": null,
            "PERIOD": "month",
            "PER": 0,
            "TAX_DATE": null,
            "ITD_MATURITY": null,
            "PRICE": null,
            "ITD_PRICE_VAT": null,
            "ITD_PRICE_WO_VAT": null,
            "ITD_PRICE_ROUND": null,
            "ITD_FIX_PRICE": null,
            "ITD_FIX_PRICE_VAT": null,
            "ITD_FIX_PRICE_WO_VAT": null,
            "ITD_VAR_PRICE": null,
            "ITD_VAR_PRICE_VAT": null,
            "ITD_VAR_PRICE_WO_VAT": null,
            "ITD_TL_VALUE_PERCENT": null,
            "ITD_SAB_ID": null,
            "CT": 76,
            "ITD_TAX_PRICE": null,
            "ITD_TAX_PRICE_VAT": null,
            "ITD_TAX_PRICE_WO_VAT": null,
            "ITD_TAX_PRICE_ROUND": null,
            "ITD_PRICE_PRIM": null,
            "ITD_PRICE_PRIM_VAT": null,
            "ITD_PRICE_PRIM_WO_VAT": null,
            "ITD_SN_ID": 12,
            "ITD_VAR_SYMBOL": null,
            "ITD_INVOICING": null,
            "ITD_VAS": null,
            "ITD_REVERSE_CHARGE": null,
            "detail": null,
            "payment": null,
            "note": null
        },
        {
            "ID": 0,
            "ITD_ADVANCE_ID": 41,
            "ITD_TYPE": "NON_ATTACH",
            "USER_ID": 1769,
            "SRV_ID": 967,
            "Y": 2023,
            "MON": 7,
            "ITD_DAY": null,
            "ITD_Y_END": 2022,
            "MON_END": null,
            "ITD_DAY_END": null,
            "PERIOD": "month",
            "PER": 0,
            "TAX_DATE": null,
            "ITD_MATURITY": null,
            "PRICE": null,
            "ITD_PRICE_VAT": null,
            "ITD_PRICE_WO_VAT": null,
            "ITD_PRICE_ROUND": null,
            "ITD_FIX_PRICE": null,
            "ITD_FIX_PRICE_VAT": null,
            "ITD_FIX_PRICE_WO_VAT": null,
            "ITD_VAR_PRICE": null,
            "ITD_VAR_PRICE_VAT": null,
            "ITD_VAR_PRICE_WO_VAT": null,
            "ITD_TL_VALUE_PERCENT": null,
            "ITD_SAB_ID": null,
            "CT": 38,
            "ITD_TAX_PRICE": null,
            "ITD_TAX_PRICE_VAT": null,
            "ITD_TAX_PRICE_WO_VAT": null,
            "ITD_TAX_PRICE_ROUND": null,
            "ITD_PRICE_PRIM": null,
            "ITD_PRICE_PRIM_VAT": null,
            "ITD_PRICE_PRIM_WO_VAT": null,
            "ITD_SN_ID": 383,
            "ITD_VAR_SYMBOL": null,
            "ITD_INVOICING": null,
            "ITD_VAS": null,
            "ITD_REVERSE_CHARGE": null,
            "detail": null,
            "payment": null,
            "note": null
        }
    ]
}

Request      

GET api/v3/internal-tax-documents

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of items per page. Example: 10

page   integer  optional    

Page number. Example: 1

ids   string  optional    

Filter by comma-separated document IDs. Example: 100,200,300

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Example: 1,2,3

customer   integer  optional    

Filter by customer (user) ID. Example: 345

type   string  optional    

Filter by document type. Accepts comma-separated values. Example: SERVICE,CREDIT_NOTE

date_from   string  optional    

Filter documents issued on or after this date (YYYY-MM-DD). Applies to TAX_DATE (DUZP). Example: 2024-01-01

date_to   string  optional    

Filter documents issued on or before this date (YYYY-MM-DD). Applies to TAX_DATE (DUZP). Example: 2024-12-31

service   integer  optional    

Filter by service definition ID (ITD_SN_ID → services_name). Example: 19

service_class   integer  optional    

Filter by service class ID (requires JOIN to services_name → services_class). Example: 1

billing_plan   integer  optional    

Filter by billing plan ID (via ITD_SAB_ID → services_active_billing.SAB_BP_ID). Example: 5

search   string  optional    

Search by document number (ID). Example: 100000

Response

Response Fields

data   object     
ID   integer     

Document number (primary key, part of composite PK with ITD_ADVANCE_ID).

ITD_ADVANCE_ID   integer     

Advance sequence number. 0 for base document (SERVICE), >0 for ADVANCE/CREDIT_NOTE sub-documents.

ITD_TYPE   string     

Document type.

Must be one of:
  • SERVICE
  • CREDIT_NOTE
  • MANUAL
  • ADVANCE
  • NON_ATTACH
CT   integer     

Location (installation) ID — multi-tenant discriminator.

USER_ID   integer     

Customer ID. See GET /v3/customers/{id}.

customer_name   string     

Computed customer display name (via get_user_name). NULL when USER_ID is absent or zero.

SRV_ID   integer     

Active service instance ID (services_active).

ITD_SN_ID   integer     

Service definition ID (services_name).

ITD_SAB_ID   integer     

Service billing configuration ID (services_active_billing).

Y   integer     

Billing year.

MON   integer     

Billing month (1-12).

PERIOD   string     

Billing period type.

Must be one of:
  • all
  • chalfyear
  • cquarter
  • cyear
  • month
  • none
  • vhalfyear
  • vmonth
  • vquarter
  • vyear
  • cyears2
  • cyears3
  • cmonths18
  • vyears2
  • vyears3
  • vmonths18
PER   integer     

Period sequence number.

TAX_DATE   string     

Tax date / DUZP (YYYY-MM-DD).

ITD_MATURITY   string     

Maturity date (YYYY-MM-DD).

PRICE   string     

Total price including VAT (decimal, 4 places).

ITD_PRICE_VAT   string     

VAT amount.

ITD_PRICE_WO_VAT   string     

Price without VAT.

ITD_PRICE_ROUND   string     

Rounding adjustment.

ITD_FIX_PRICE   string     

Fixed price component including VAT.

ITD_FIX_PRICE_VAT   string     

VAT of fixed component.

ITD_FIX_PRICE_WO_VAT   string     

Fixed component without VAT.

ITD_VAR_PRICE   string     

Variable price component including VAT (usage-based charges).

ITD_VAR_PRICE_VAT   string     

VAT of variable component.

ITD_VAR_PRICE_WO_VAT   string     

Variable component without VAT.

ITD_TAX_PRICE   string     

Actual tax levy amount including VAT.

ITD_TAX_PRICE_VAT   string     

VAT of actual tax levy.

ITD_TAX_PRICE_WO_VAT   string     

Actual tax levy without VAT.

ITD_TAX_PRICE_ROUND   string     

Rounding adjustment of actual tax levy.

ITD_PRICE_PRIM   string     

Original (primary) price including VAT.

ITD_PRICE_PRIM_VAT   string     

Original price VAT.

ITD_PRICE_PRIM_WO_VAT   string     

Original price without VAT.

ITD_TL_VALUE_PERCENT   integer     

VAT rate in percent.

ITD_VAR_SYMBOL   integer     

Variable symbol of the tax document (invoice) this document was invoiced into.

ITD_INVOICING   string     

Invoicing amount (decimal, 4 places).

ITD_REVERSE_CHARGE   integer     

Reverse charge flag. 0 = not applied, 1 = applied.

detail   object     

Document detail — blocked amount and price breakdowns. NULL if no detail record exists.
TTDD_PRICE   string     

Blocked amount (original price before blocking).

TTDD_PRICE_VAT   string     

Detail VAT.

TTDD_PRICE_WO_VAT   string     

Detail price without VAT.

TTDD_PRICE_ROUND   string     

Detail rounding.

TTDD_FIX_PRICE   string     

Detail fixed price.

TTDD_FIX_PRICE_VAT   string     

Detail fixed price VAT.

TTDD_FIX_PRICE_WO_VAT   string     

Detail fixed price without VAT.

TTDD_REVERSE_CHARGE   integer     

Detail reverse charge flag.

payment   object     

Payment information. NULL if no payment record exists.
AMOUNT   string     

Paid amount (decimal, 4 places).

note   object     

Credit note (ODD) information. NULL if no note record exists.
TTDN_ITD_NOTE   string     

Note text.

TTDN_CREATED   string     

Creation datetime of the credit note.

TTDN_DATE_CONFIRM   string     

Date the credit note was confirmed by the customer.

TTDN_CONFIRMED   integer     

Confirmation operator ID.

TTDN_CREATOR   integer     

Creator operator ID.

Get Internal Tax Document

requires authentication

Returns a single internal tax document by ID. Use advance_id query parameter to specify which advance record to return (defaults to 0 — the base document).

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/internal-tax-documents/1000000010510504?advance_id=0" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/internal-tax-documents/1000000010510504"
);

const params = {
    "advance_id": "0",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "ID": 0,
        "ITD_ADVANCE_ID": 10,
        "ITD_TYPE": "NON_ATTACH",
        "USER_ID": 2617,
        "SRV_ID": 8015,
        "Y": 2026,
        "MON": 7,
        "ITD_DAY": null,
        "ITD_Y_END": 2021,
        "MON_END": null,
        "ITD_DAY_END": null,
        "PERIOD": "month",
        "PER": 0,
        "TAX_DATE": null,
        "ITD_MATURITY": null,
        "PRICE": null,
        "ITD_PRICE_VAT": null,
        "ITD_PRICE_WO_VAT": null,
        "ITD_PRICE_ROUND": null,
        "ITD_FIX_PRICE": null,
        "ITD_FIX_PRICE_VAT": null,
        "ITD_FIX_PRICE_WO_VAT": null,
        "ITD_VAR_PRICE": null,
        "ITD_VAR_PRICE_VAT": null,
        "ITD_VAR_PRICE_WO_VAT": null,
        "ITD_TL_VALUE_PERCENT": null,
        "ITD_SAB_ID": null,
        "CT": 39,
        "ITD_TAX_PRICE": null,
        "ITD_TAX_PRICE_VAT": null,
        "ITD_TAX_PRICE_WO_VAT": null,
        "ITD_TAX_PRICE_ROUND": null,
        "ITD_PRICE_PRIM": null,
        "ITD_PRICE_PRIM_VAT": null,
        "ITD_PRICE_PRIM_WO_VAT": null,
        "ITD_SN_ID": 765,
        "ITD_VAR_SYMBOL": null,
        "ITD_INVOICING": null,
        "ITD_VAS": null,
        "ITD_REVERSE_CHARGE": null,
        "detail": null,
        "payment": null,
        "note": null
    }
}

Request      

GET api/v3/internal-tax-documents/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the internal tax document. Example: 1000000010510504

Query Parameters

advance_id   integer  optional    

Advance ID within the document. Defaults to 0 (base document). Example: 0

Response

Response Fields

data   object     
ID   integer     

Document number (primary key, part of composite PK with ITD_ADVANCE_ID).

ITD_ADVANCE_ID   integer     

Advance sequence number. 0 for base document (SERVICE), >0 for ADVANCE/CREDIT_NOTE sub-documents.

ITD_TYPE   string     

Document type.

Must be one of:
  • SERVICE
  • CREDIT_NOTE
  • MANUAL
  • ADVANCE
  • NON_ATTACH
CT   integer     

Location (installation) ID — multi-tenant discriminator.

USER_ID   integer     

Customer ID. See GET /v3/customers/{id}.

customer_name   string     

Computed customer display name (via get_user_name). NULL when USER_ID is absent or zero.

SRV_ID   integer     

Active service instance ID (services_active).

ITD_SN_ID   integer     

Service definition ID (services_name).

ITD_SAB_ID   integer     

Service billing configuration ID (services_active_billing).

Y   integer     

Billing year.

MON   integer     

Billing month (1-12).

PERIOD   string     

Billing period type.

Must be one of:
  • all
  • chalfyear
  • cquarter
  • cyear
  • month
  • none
  • vhalfyear
  • vmonth
  • vquarter
  • vyear
  • cyears2
  • cyears3
  • cmonths18
  • vyears2
  • vyears3
  • vmonths18
PER   integer     

Period sequence number.

TAX_DATE   string     

Tax date / DUZP (YYYY-MM-DD).

ITD_MATURITY   string     

Maturity date (YYYY-MM-DD).

PRICE   string     

Total price including VAT (decimal, 4 places).

ITD_PRICE_VAT   string     

VAT amount.

ITD_PRICE_WO_VAT   string     

Price without VAT.

ITD_PRICE_ROUND   string     

Rounding adjustment.

ITD_FIX_PRICE   string     

Fixed price component including VAT.

ITD_FIX_PRICE_VAT   string     

VAT of fixed component.

ITD_FIX_PRICE_WO_VAT   string     

Fixed component without VAT.

ITD_VAR_PRICE   string     

Variable price component including VAT (usage-based charges).

ITD_VAR_PRICE_VAT   string     

VAT of variable component.

ITD_VAR_PRICE_WO_VAT   string     

Variable component without VAT.

ITD_TAX_PRICE   string     

Actual tax levy amount including VAT.

ITD_TAX_PRICE_VAT   string     

VAT of actual tax levy.

ITD_TAX_PRICE_WO_VAT   string     

Actual tax levy without VAT.

ITD_TAX_PRICE_ROUND   string     

Rounding adjustment of actual tax levy.

ITD_PRICE_PRIM   string     

Original (primary) price including VAT.

ITD_PRICE_PRIM_VAT   string     

Original price VAT.

ITD_PRICE_PRIM_WO_VAT   string     

Original price without VAT.

ITD_TL_VALUE_PERCENT   integer     

VAT rate in percent.

ITD_VAR_SYMBOL   integer     

Variable symbol of the tax document (invoice) this document was invoiced into.

ITD_INVOICING   string     

Invoicing amount (decimal, 4 places).

ITD_REVERSE_CHARGE   integer     

Reverse charge flag. 0 = not applied, 1 = applied.

detail   object     

Document detail — blocked amount and price breakdowns. NULL if no detail record exists.
TTDD_PRICE   string     

Blocked amount (original price before blocking).

TTDD_PRICE_VAT   string     

Detail VAT.

TTDD_PRICE_WO_VAT   string     

Detail price without VAT.

TTDD_PRICE_ROUND   string     

Detail rounding.

TTDD_FIX_PRICE   string     

Detail fixed price.

TTDD_FIX_PRICE_VAT   string     

Detail fixed price VAT.

TTDD_FIX_PRICE_WO_VAT   string     

Detail fixed price without VAT.

TTDD_REVERSE_CHARGE   integer     

Detail reverse charge flag.

payment   object     

Payment information. NULL if no payment record exists.
AMOUNT   string     

Paid amount (decimal, 4 places).

note   object     

Credit note (ODD) information. NULL if no note record exists.
TTDN_ITD_NOTE   string     

Note text.

TTDN_CREATED   string     

Creation datetime of the credit note.

TTDN_DATE_CONFIRM   string     

Date the credit note was confirmed by the customer.

TTDN_CONFIRMED   integer     

Confirmation operator ID.

TTDN_CREATOR   integer     

Creator operator ID.

Invoices

List Invoices

requires authentication

Returns a paginated list of invoices. At least one of the following filters must be provided: customer, year, type, date_from, search. Without a narrowing filter the endpoint returns HTTP 422. By default, only active invoices (IH_STAT_FLAG = 'A') are returned. Use status=S for cancelled, or status=all for both.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/invoices?per_page=10&page=1&ids=100%2C200%2C300&cts=1%2C2%2C3&customer=345&type=INVOICE%2CADVANCE&year=2024&status=A&date_from=2024-01-01&date_to=2024-12-31&search=102" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/invoices"
);

const params = {
    "per_page": "10",
    "page": "1",
    "ids": "100,200,300",
    "cts": "1,2,3",
    "customer": "345",
    "type": "INVOICE,ADVANCE",
    "year": "2024",
    "status": "A",
    "date_from": "2024-01-01",
    "date_to": "2024-12-31",
    "search": "102",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "ID": 33143616,
            "USER_ID": 2878,
            "NUMBER_RECORD": "26824",
            "ACCORD": "",
            "INVOICE_ORDER": "",
            "DATE_S": "2006-09-25",
            "DATE_U": null,
            "DATE_V": "2015-01-19",
            "TERM": "",
            "CON_SYM": "",
            "VAR_SYM": 2031881,
            "NUMBER_DLIST": 1,
            "CT": 40,
            "NUM": 709,
            "IH_DOC_ID": 8862,
            "IH_AUTHOR": 12,
            "IH_CREATED": null,
            "NOTE": null,
            "IH_STAT_FLAG": "A",
            "IH_TYPE": "CREDIT_NOTE",
            "IH_TAX": false,
            "IH_TICKET": null,
            "IH_PL_ID": null,
            "IH_DATE_CONFIRM": null,
            "IH_CANCELLED": null,
            "IH_CANCEL_L_ID": null,
            "IH_CANCEL_NOTE": null,
            "IH_PROVIDER_USER_ID": null,
            "IH_PA_ID": null,
            "IH_NO_AUTO_DISPATCH": null,
            "IH_HIDE_PRICE_DETAIL": null,
            "items": [
                {
                    "ID": 37211350,
                    "ID_INVOICE": 33143616,
                    "NOTE": "Ipsum nostrum omnis autem et consequatur aut dolores enim.",
                    "COUNT": null,
                    "AMOUNT": "7786.7381",
                    "IB_ITD_PRICE_VAT": null,
                    "IB_ITD_PRICE_WO_VAT": null,
                    "IB_ITD_PRICE_ROUND": null,
                    "MONTH": "08",
                    "YEAR": "2024",
                    "USER_SERVICE_ID": 5468,
                    "IB_PER": 3,
                    "IB_NOTE2": null,
                    "IB_ATTACHMENT": null,
                    "IB_ITD_ID": null,
                    "IB_ITD_ADVANCE_ID": 0,
                    "IB_PRICE_TYPE": "ALL",
                    "IB_DISCOUNT": 0,
                    "IB_SAD_ID": null,
                    "IB_ACCOUNT_ADVANCE": 0,
                    "IB_REVERSE_CHARGE": null,
                    "IB_SA_ID": null,
                    "IB_SA_BASE_ID": null,
                    "IB_TL_VALUE_PERCENT": null,
                    "IB_NO_PAY": null
                }
            ]
        },
        {
            "ID": 33143617,
            "USER_ID": 1462,
            "NUMBER_RECORD": "48309",
            "ACCORD": "",
            "INVOICE_ORDER": "",
            "DATE_S": "1975-05-01",
            "DATE_U": null,
            "DATE_V": "2024-01-23",
            "TERM": "",
            "CON_SYM": "",
            "VAR_SYM": 8327339,
            "NUMBER_DLIST": 1,
            "CT": 51,
            "NUM": 177,
            "IH_DOC_ID": 782,
            "IH_AUTHOR": 614,
            "IH_CREATED": null,
            "NOTE": null,
            "IH_STAT_FLAG": "A",
            "IH_TYPE": "CREDIT_NOTE_ADVANCE",
            "IH_TAX": false,
            "IH_TICKET": null,
            "IH_PL_ID": null,
            "IH_DATE_CONFIRM": null,
            "IH_CANCELLED": null,
            "IH_CANCEL_L_ID": null,
            "IH_CANCEL_NOTE": null,
            "IH_PROVIDER_USER_ID": null,
            "IH_PA_ID": null,
            "IH_NO_AUTO_DISPATCH": null,
            "IH_HIDE_PRICE_DETAIL": null,
            "items": [
                {
                    "ID": 37211351,
                    "ID_INVOICE": 33143617,
                    "NOTE": "Aliquam veniam corporis dolorem mollitia deleniti nemo.",
                    "COUNT": null,
                    "AMOUNT": "4091.1341",
                    "IB_ITD_PRICE_VAT": null,
                    "IB_ITD_PRICE_WO_VAT": null,
                    "IB_ITD_PRICE_ROUND": null,
                    "MONTH": "05",
                    "YEAR": "2020",
                    "USER_SERVICE_ID": 7643,
                    "IB_PER": 6,
                    "IB_NOTE2": null,
                    "IB_ATTACHMENT": null,
                    "IB_ITD_ID": null,
                    "IB_ITD_ADVANCE_ID": 0,
                    "IB_PRICE_TYPE": "FIX",
                    "IB_DISCOUNT": 0,
                    "IB_SAD_ID": null,
                    "IB_ACCOUNT_ADVANCE": 0,
                    "IB_REVERSE_CHARGE": null,
                    "IB_SA_ID": null,
                    "IB_SA_BASE_ID": null,
                    "IB_TL_VALUE_PERCENT": null,
                    "IB_NO_PAY": null
                }
            ]
        }
    ]
}

Request      

GET api/v3/invoices

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of items per page. Example: 10

page   integer  optional    

Page number. Example: 1

ids   string  optional    

Filter by comma-separated invoice IDs. Example: 100,200,300

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Example: 1,2,3

customer   integer  optional    

Filter by customer (user) ID. Example: 345

type   string  optional    

Filter by invoice type. Accepts comma-separated values. Example: INVOICE,ADVANCE

year   integer  optional    

Filter by year of issue date (DATE_V). Example: 2024

status   string  optional    

Filter by status flag. A = active, S = cancelled, all = both. Default: only active (A). Example: A

date_from   string  optional    

Filter invoices issued on or after this date (YYYY-MM-DD). Example: 2024-01-01

date_to   string  optional    

Filter invoices issued on or before this date (YYYY-MM-DD). Example: 2024-12-31

search   string  optional    

Search by invoice record number (NUMBER_RECORD) or variable symbol (VAR_SYM). Example: 102

Response

Response Fields

data   object     
ID   integer     

Unique invoice identifier (primary key).

USER_ID   integer     

Customer ID. See GET /v3/customers/{id}.

CT   integer     

Location (installation) ID — multi-tenant discriminator.

NUMBER_RECORD   string     

Invoice record number.

IH_DOC_ID   integer     

Internal document number.

VAR_SYM   integer     

Variable symbol — unique payment identifier for bank transfers.

CON_SYM   string     

Constant symbol.

NUM   integer     

Sequential invoice number within the delivery list.

NUMBER_DLIST   integer     

Delivery list number.

ACCORD   string     

Accord number (related agreement reference).

INVOICE_ORDER   string     

Invoice order reference.

DATE_V   string     

Issue date (YYYY-MM-DD).

DATE_U   string     

Taxable supply date / DUZP (YYYY-MM-DD).

DATE_S   string     

Due date / maturity date (YYYY-MM-DD).

TERM   string     

Payment term description.

IH_TYPE   string     

Invoice type.

Must be one of:
  • INVOICE
  • ADVANCE
  • CREDIT_NOTE
  • CREDIT_NOTE_ADVANCE
IH_STAT_FLAG   string     

Status flag. A = active, S = cancelled.

Must be one of:
  • A
  • S
IH_TAX   boolean     

Tax document flag.

IH_AUTHOR   integer     

Operator ID who created the invoice.

IH_CREATED   string     

Creation timestamp (YYYY-MM-DD HH:MM:SS).

IH_CANCELLED   string     

Cancellation timestamp.

IH_CANCEL_L_ID   integer     

Operator ID who cancelled the invoice.

IH_CANCEL_NOTE   string     

Cancellation reason/note.

IH_NO_AUTO_DISPATCH   integer     

Dispatch control. 0 = dispatch, 1 = do not dispatch.

IH_HIDE_PRICE_DETAIL   integer     

Hide price detail flag. 1 = hide prices in printouts.

IH_TICKET   integer     

Generation ticket/sequence number.

IH_PL_ID   integer     

Linked payment list ID.

IH_PA_ID   integer     

Payment account ID.

IH_PROVIDER_USER_ID   integer     

Provider customer ID.

IH_DATE_CONFIRM   string     

Confirmation date (YYYY-MM-DD).

NOTE   string     

Invoice note/memo.

customer_name   string     

Computed customer display name (derived from USER_ID via get_user_name). NULL when USER_ID is absent or zero.

items   object[]     

Invoice line items (from invoice_body table).
ID   integer     

Unique line item ID.

ID_INVOICE   integer     

Parent invoice ID.

NOTE   string     

Line item description.

COUNT   integer     

Quantity.

AMOUNT   string     

Total amount including VAT (decimal, 4 places).

IB_ITD_PRICE_VAT   string     

Price with VAT from tax document.

IB_ITD_PRICE_WO_VAT   string     

Price without VAT from tax document.

IB_ITD_PRICE_ROUND   string     

Rounding adjustment.

MONTH   string     

Billing month (01-12).

YEAR   string     

Billing year (4-digit).

USER_SERVICE_ID   integer     

Customer service ID.

IB_PER   integer     

Billing period.

IB_PRICE_TYPE   string     

Price type.

Must be one of:
  • ALL
  • FIX
  • VAR
IB_DISCOUNT   integer     

Discount percentage.

IB_REVERSE_CHARGE   integer     

Reverse charge flag.

Get Invoice

requires authentication

Returns a single invoice by ID, including line items.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/invoices/5352" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/invoices/5352"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "ID": 33143618,
        "USER_ID": 2878,
        "NUMBER_RECORD": "89349",
        "ACCORD": "",
        "INVOICE_ORDER": "",
        "DATE_S": "2015-01-19",
        "DATE_U": null,
        "DATE_V": "2010-09-17",
        "TERM": "",
        "CON_SYM": "",
        "VAR_SYM": 1310719,
        "NUMBER_DLIST": 1,
        "CT": 79,
        "NUM": 274,
        "IH_DOC_ID": 9279,
        "IH_AUTHOR": 765,
        "IH_CREATED": null,
        "NOTE": null,
        "IH_STAT_FLAG": "A",
        "IH_TYPE": "INVOICE",
        "IH_TAX": false,
        "IH_TICKET": null,
        "IH_PL_ID": null,
        "IH_DATE_CONFIRM": null,
        "IH_CANCELLED": null,
        "IH_CANCEL_L_ID": null,
        "IH_CANCEL_NOTE": null,
        "IH_PROVIDER_USER_ID": null,
        "IH_PA_ID": null,
        "IH_NO_AUTO_DISPATCH": null,
        "IH_HIDE_PRICE_DETAIL": null,
        "items": [
            {
                "ID": 37211352,
                "ID_INVOICE": 33143618,
                "NOTE": "Nostrum omnis autem et consequatur aut.",
                "COUNT": null,
                "AMOUNT": "4770.9696",
                "IB_ITD_PRICE_VAT": null,
                "IB_ITD_PRICE_WO_VAT": null,
                "IB_ITD_PRICE_ROUND": null,
                "MONTH": "05",
                "YEAR": "2023",
                "USER_SERVICE_ID": 2327,
                "IB_PER": 9,
                "IB_NOTE2": null,
                "IB_ATTACHMENT": null,
                "IB_ITD_ID": null,
                "IB_ITD_ADVANCE_ID": 0,
                "IB_PRICE_TYPE": "FIX",
                "IB_DISCOUNT": 0,
                "IB_SAD_ID": null,
                "IB_ACCOUNT_ADVANCE": 0,
                "IB_REVERSE_CHARGE": null,
                "IB_SA_ID": null,
                "IB_SA_BASE_ID": null,
                "IB_TL_VALUE_PERCENT": null,
                "IB_NO_PAY": null
            }
        ]
    }
}

Request      

GET api/v3/invoices/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the invoice. Example: 5352

Response

Response Fields

data   object     
ID   integer     

Unique invoice identifier (primary key).

USER_ID   integer     

Customer ID. See GET /v3/customers/{id}.

CT   integer     

Location (installation) ID — multi-tenant discriminator.

NUMBER_RECORD   string     

Invoice record number.

IH_DOC_ID   integer     

Internal document number.

VAR_SYM   integer     

Variable symbol — unique payment identifier for bank transfers.

CON_SYM   string     

Constant symbol.

NUM   integer     

Sequential invoice number within the delivery list.

NUMBER_DLIST   integer     

Delivery list number.

ACCORD   string     

Accord number (related agreement reference).

INVOICE_ORDER   string     

Invoice order reference.

DATE_V   string     

Issue date (YYYY-MM-DD).

DATE_U   string     

Taxable supply date / DUZP (YYYY-MM-DD).

DATE_S   string     

Due date / maturity date (YYYY-MM-DD).

TERM   string     

Payment term description.

IH_TYPE   string     

Invoice type.

Must be one of:
  • INVOICE
  • ADVANCE
  • CREDIT_NOTE
  • CREDIT_NOTE_ADVANCE
IH_STAT_FLAG   string     

Status flag. A = active, S = cancelled.

Must be one of:
  • A
  • S
IH_TAX   boolean     

Tax document flag.

IH_AUTHOR   integer     

Operator ID who created the invoice.

IH_CREATED   string     

Creation timestamp (YYYY-MM-DD HH:MM:SS).

IH_CANCELLED   string     

Cancellation timestamp.

IH_CANCEL_L_ID   integer     

Operator ID who cancelled the invoice.

IH_CANCEL_NOTE   string     

Cancellation reason/note.

IH_NO_AUTO_DISPATCH   integer     

Dispatch control. 0 = dispatch, 1 = do not dispatch.

IH_HIDE_PRICE_DETAIL   integer     

Hide price detail flag. 1 = hide prices in printouts.

IH_TICKET   integer     

Generation ticket/sequence number.

IH_PL_ID   integer     

Linked payment list ID.

IH_PA_ID   integer     

Payment account ID.

IH_PROVIDER_USER_ID   integer     

Provider customer ID.

IH_DATE_CONFIRM   string     

Confirmation date (YYYY-MM-DD).

NOTE   string     

Invoice note/memo.

customer_name   string     

Computed customer display name (derived from USER_ID via get_user_name). NULL when USER_ID is absent or zero.

items   object[]     

Invoice line items (from invoice_body table).
ID   integer     

Unique line item ID.

ID_INVOICE   integer     

Parent invoice ID.

NOTE   string     

Line item description.

COUNT   integer     

Quantity.

AMOUNT   string     

Total amount including VAT (decimal, 4 places).

IB_ITD_PRICE_VAT   string     

Price with VAT from tax document.

IB_ITD_PRICE_WO_VAT   string     

Price without VAT from tax document.

IB_ITD_PRICE_ROUND   string     

Rounding adjustment.

MONTH   string     

Billing month (01-12).

YEAR   string     

Billing year (4-digit).

USER_SERVICE_ID   integer     

Customer service ID.

IB_PER   integer     

Billing period.

IB_PRICE_TYPE   string     

Price type.

Must be one of:
  • ALL
  • FIX
  • VAR
IB_DISCOUNT   integer     

Discount percentage.

IB_REVERSE_CHARGE   integer     

Reverse charge flag.

Locations

List Locations

requires authentication

Returns a paginated list of non-hidden locations.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/locations?ids=1%2C2%2C3&cts=1%2C2%2C3" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/locations"
);

const params = {
    "ids": "1,2,3",
    "cts": "1,2,3",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "ID": "280",
            "NAME": "aut adipisci quidem",
            "DESCRIPTION": "Commodi incidunt iure odit et et modi.",
            "LOCATION": null,
            "START_DATE": "2026-02-24",
            "SIPO_KODOZ": "sc",
            "SIPO_CISORG": null,
            "INFO_EMAIL": "[email protected]",
            "HIDDEN": 0,
            "PATH": null,
            "I_COMPANY_ID": 48,
            "I_CP_ID": 1,
            "I_MAP_ID": null,
            "I_NOTE": "Praesentium quis adipisci molestias fugit. Distinctio eum doloremque id aut libero aliquam veniam corporis. Mollitia deleniti nemo odit quia officia. Dignissimos neque blanditiis odio.",
            "I_MAP_CENTER_LAT": 28.134129,
            "I_MAP_CENTER_LON": 116.728477,
            "I_MAP_ZOOM": 20,
            "I_MAP_ID_NAME": "MAPNAME-mgos",
            "I_CL_ID": 1
        },
        {
            "ID": "281",
            "NAME": "eos esse pariatur",
            "DESCRIPTION": null,
            "LOCATION": "Tillmanville",
            "START_DATE": "2026-03-26",
            "SIPO_KODOZ": "hn",
            "SIPO_CISORG": null,
            "INFO_EMAIL": "[email protected]",
            "HIDDEN": 0,
            "PATH": "path-tzxzsenw",
            "I_COMPANY_ID": 43,
            "I_CP_ID": 1,
            "I_MAP_ID": null,
            "I_NOTE": "Perspiciatis atque sit impedit architecto non laborum. Voluptatem ex laboriosam et tempore dolorem nihil quasi. Quae sit harum ut. Rerum sint inventore eveniet optio. Suscipit atque officiis accusantium ut ab quisquam quo.",
            "I_MAP_CENTER_LAT": 63.148369,
            "I_MAP_CENTER_LON": -179.461746,
            "I_MAP_ZOOM": 14,
            "I_MAP_ID_NAME": "MAPNAME-gwfz",
            "I_CL_ID": 1
        }
    ]
}

Request      

GET api/v3/locations

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

ids   string  optional    

Filter by comma-separated location IDs Example: 1,2,3

cts   string  optional    

Filter by comma-separated location IDs (overrides X-CT header) Example: 1,2,3

Response

Response Fields

data   object     
ID   integer     

Installation (location) ID.

NAME   string     

Installation name.

Operator Roles

List Operator Roles

requires authentication 

Returns a paginated list of operator roles.
Partner-bound users see roles of their CIBS partner + global roles (LR_CP_ID IS NULL).
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/operator-roles?per_page=15&page=1&ids=9%2C12&cibs_partners=3%2C69&search=admin" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/operator-roles"
);

const params = {
    "per_page": "15",
    "page": "1",
    "ids": "9,12",
    "cibs_partners": "3,69",
    "search": "admin",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "LR_ID": 677,
            "LR_CP_ID": null,
            "LR_NAME": "aut adipisci quidem",
            "LR_LEVEL": 7,
            "LR_NOTE": null,
            "LR_CREATED": "2026-03-08 11:34:47",
            "LR_L_ID": 1,
            "rights": [
                {
                    "ID": 650395,
                    "UR_TYPE": "ROLE",
                    "USER_ID": 1,
                    "UR_LR_ID": 677,
                    "NAME": "incidunt-iure-odit",
                    "OPTIONS": "",
                    "CIBS_VERSION": null,
                    "UR_CREATED": "2026-03-05 06:51:36",
                    "UR_CREATOR_L_ID": 1
                }
            ]
        },
        {
            "LR_ID": 678,
            "LR_CP_ID": null,
            "LR_NAME": "et modi ipsum",
            "LR_LEVEL": 1,
            "LR_NOTE": null,
            "LR_CREATED": "2026-01-22 06:19:47",
            "LR_L_ID": 1,
            "rights": [
                {
                    "ID": 650396,
                    "UR_TYPE": "ROLE",
                    "USER_ID": 1,
                    "UR_LR_ID": 678,
                    "NAME": "et-consequatur",
                    "OPTIONS": "",
                    "CIBS_VERSION": null,
                    "UR_CREATED": "2026-02-09 00:43:22",
                    "UR_CREATOR_L_ID": 1
                }
            ]
        }
    ]
}

Request      

GET api/v3/operator-roles

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of results per page. Example: 15

page   integer  optional    

Page number. Example: 1

ids   string  optional    

Filter by comma-separated role IDs. Example: 9,12

cibs_partners   string  optional    

Filter by comma-separated CIBS partner IDs. Use "null" to get global (partnerless) roles only. Example: 3,69

search   string  optional    

Search in role name. Example: admin

Response

Response Fields

data   object     
LR_ID   integer     

Unique role identifier (primary key).

LR_CP_ID   integer     

CIBS partner ID. NULL for global roles available to all partners.

LR_NAME   string     

Role name.

LR_LEVEL   integer     

Role level (0–255). Users can only manage roles with lower level.

LR_NOTE   string     

Free-text note.

LR_CREATED   string     

Role creation datetime.

LR_L_ID   integer     

ID of the operator who created this role.

rights   object[]     

Rights assigned to this role. Always loaded.
ID   integer     

Unique right assignment record ID.

UR_TYPE   string     

Assignment type. Always "ROLE" for role-level rights.

Must be one of:
  • LOGIN
  • ROLE
USER_ID   integer     

Operator ID (null for role-level assignments).

UR_LR_ID   integer     

Role ID this right belongs to. See GET /v3/operator-roles/{id}.

NAME   string     

Right name/key. See GET /v3/rights-definitions for the catalogue of available rights.

OPTIONS   string     

Right value or options string.

CIBS_VERSION   string     

CIBS version restriction. NULL means the right applies to all versions.

UR_CREATED   string     

Right assignment creation datetime.

UR_CREATOR_L_ID   integer     

ID of the operator who created this right assignment.

operators   object[]     

Operators who have this role assigned. Loaded on show (detail) only.
ID   integer     

Unique operator identifier. See GET /v3/operators/{id}.

FIRST_NAME   string     

First name of the operator.

SURNAME   string     

Surname of the operator.

LOGIN   string     

Login username.

L_LEVEL   integer     

Permission level (0–255).

MAIL   string     

Email address(es).

PHONE   integer     

Phone number.

NOTE   string     

Free-text note.

SALESMAN   integer     

Flag: sales representative (0/1).

L_SMS_ENABLE   integer     

Flag: can send SMS requests (0/1).

L_ACTIVE   integer     

Flag: active (1) or inactive (0).

L_TYPE   string     

Operator type.

Must be one of:
  • PERSON
  • MACHINE
  • COOPERATION
L_CP_ID   integer     

CIBS partner ID. NULL for internal operators.

L_SELFCARE   integer     

Flag: selfcare operator (0/1).

L_CREATED   string     

Account creation datetime.

LOG_LEVEL   string     

Logging level.

Must be one of:
  • EMERG
  • ALERT
  • CRIT
  • ERR
  • WARNING
  • NOTICE
  • INFO
  • DEBUG

Get Operator Role

requires authentication 

Returns a single operator role by ID, including its rights and assigned operators.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/operator-roles/9" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/operator-roles/9"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "LR_ID": 679,
        "LR_CP_ID": null,
        "LR_NAME": "aut adipisci quidem",
        "LR_LEVEL": 7,
        "LR_NOTE": null,
        "LR_CREATED": "2026-03-08 11:34:47",
        "LR_L_ID": 1,
        "rights": [
            {
                "ID": 650397,
                "UR_TYPE": "ROLE",
                "USER_ID": 1,
                "UR_LR_ID": 679,
                "NAME": "et-modi-ipsum",
                "OPTIONS": "",
                "CIBS_VERSION": null,
                "UR_CREATED": "2026-02-24 13:30:35",
                "UR_CREATOR_L_ID": 1
            }
        ],
        "operators": [
            {
                "ID": 5563,
                "FIRST_NAME": "Isidro",
                "SURNAME": "McLaughlin",
                "LOGIN": "ztromp",
                "L_LEVEL": 3,
                "MAIL": "[email protected]",
                "PHONE": null,
                "NOTE": null,
                "SALESMAN": 0,
                "L_SMS_ENABLE": 0,
                "LOG_LEVEL": "NOTICE",
                "L_CP_ID": null,
                "L_CREATED": "2026-03-03 02:01:33",
                "L_L_ID": 1,
                "L_ACTIVE": 1,
                "L_PASS_EXPIRE": null,
                "L_PASS_CHANGE": null,
                "L_TYPE": "MACHINE",
                "L_SIGNATURE": null,
                "L_SELFCARE": 0,
                "L_CACHE_INITIALS": "",
                "L_INITIALS": null,
                "L_STATISTICS_ENABLE": 0,
                "pivot": {
                    "LRC_LR_ID": 679,
                    "LRC_L_ID": 5563
                }
            }
        ]
    }
}

Request      

GET api/v3/operator-roles/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the operator role. Example: 9

Response

Response Fields

data   object     
LR_ID   integer     

Unique role identifier (primary key).

LR_CP_ID   integer     

CIBS partner ID. NULL for global roles available to all partners.

LR_NAME   string     

Role name.

LR_LEVEL   integer     

Role level (0–255). Users can only manage roles with lower level.

LR_NOTE   string     

Free-text note.

LR_CREATED   string     

Role creation datetime.

LR_L_ID   integer     

ID of the operator who created this role.

rights   object[]     

Rights assigned to this role. Always loaded.
ID   integer     

Unique right assignment record ID.

UR_TYPE   string     

Assignment type. Always "ROLE" for role-level rights.

Must be one of:
  • LOGIN
  • ROLE
USER_ID   integer     

Operator ID (null for role-level assignments).

UR_LR_ID   integer     

Role ID this right belongs to. See GET /v3/operator-roles/{id}.

NAME   string     

Right name/key. See GET /v3/rights-definitions for the catalogue of available rights.

OPTIONS   string     

Right value or options string.

CIBS_VERSION   string     

CIBS version restriction. NULL means the right applies to all versions.

UR_CREATED   string     

Right assignment creation datetime.

UR_CREATOR_L_ID   integer     

ID of the operator who created this right assignment.

operators   object[]     

Operators who have this role assigned. Loaded on show (detail) only.
ID   integer     

Unique operator identifier. See GET /v3/operators/{id}.

FIRST_NAME   string     

First name of the operator.

SURNAME   string     

Surname of the operator.

LOGIN   string     

Login username.

L_LEVEL   integer     

Permission level (0–255).

MAIL   string     

Email address(es).

PHONE   integer     

Phone number.

NOTE   string     

Free-text note.

SALESMAN   integer     

Flag: sales representative (0/1).

L_SMS_ENABLE   integer     

Flag: can send SMS requests (0/1).

L_ACTIVE   integer     

Flag: active (1) or inactive (0).

L_TYPE   string     

Operator type.

Must be one of:
  • PERSON
  • MACHINE
  • COOPERATION
L_CP_ID   integer     

CIBS partner ID. NULL for internal operators.

L_SELFCARE   integer     

Flag: selfcare operator (0/1).

L_CREATED   string     

Account creation datetime.

LOG_LEVEL   string     

Logging level.

Must be one of:
  • EMERG
  • ALERT
  • CRIT
  • ERR
  • WARNING
  • NOTICE
  • INFO
  • DEBUG

Operators

List Operators

requires authentication 

Returns a paginated list of system operators (admin users).
By default only active operators are returned (L_ACTIVE=1).
Use the `active` filter to include/filter inactive operators.
Partner-bound users only see operators of their CIBS partner.
Use `include_internal=true` to also see internal operators (with limited fields).
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/operators?per_page=15&page=1&ids=294%2C705&active=true&role=12&type=PERSON&search=jan&include_internal=true" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/operators"
);

const params = {
    "per_page": "15",
    "page": "1",
    "ids": "294,705",
    "active": "true",
    "role": "12",
    "type": "PERSON",
    "search": "jan",
    "include_internal": "true",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "ID": 5560,
            "FIRST_NAME": "Morgan",
            "SURNAME": "Hirthe",
            "LOGIN": "alayna44",
            "L_LEVEL": 1,
            "MAIL": "[email protected]",
            "PHONE": null,
            "NOTE": null,
            "SALESMAN": 0,
            "L_SMS_ENABLE": 0,
            "LOG_LEVEL": "NOTICE",
            "L_CP_ID": null,
            "L_CREATED": "2026-03-18 04:07:19",
            "L_L_ID": 1,
            "L_ACTIVE": 1,
            "L_PASS_EXPIRE": null,
            "L_PASS_CHANGE": null,
            "L_TYPE": "MACHINE",
            "L_SIGNATURE": null,
            "L_SELFCARE": 0,
            "L_CACHE_INITIALS": "",
            "L_INITIALS": null,
            "L_STATISTICS_ENABLE": 0,
            "roles": [
                {
                    "LR_ID": 674,
                    "LR_CP_ID": null,
                    "LR_NAME": "deleniti distinctio eum",
                    "LR_LEVEL": 2,
                    "LR_NOTE": null,
                    "LR_CREATED": "2026-04-08 02:32:10",
                    "LR_L_ID": 1,
                    "pivot": {
                        "LRC_L_ID": 5560,
                        "LRC_LR_ID": 674
                    }
                }
            ],
            "effective_rights": [
                {
                    "ID": 316410656,
                    "USER_ID": 5560,
                    "NAME": "aliquam-veniam-corporis",
                    "OPTIONS": ""
                }
            ],
            "own_rights": []
        },
        {
            "ID": 5561,
            "FIRST_NAME": "Amari",
            "SURNAME": "Torp",
            "LOGIN": "kirsten.ward",
            "L_LEVEL": 9,
            "MAIL": "[email protected]",
            "PHONE": null,
            "NOTE": null,
            "SALESMAN": 0,
            "L_SMS_ENABLE": 0,
            "LOG_LEVEL": "NOTICE",
            "L_CP_ID": null,
            "L_CREATED": "2026-03-03 05:12:59",
            "L_L_ID": 1,
            "L_ACTIVE": 1,
            "L_PASS_EXPIRE": null,
            "L_PASS_CHANGE": null,
            "L_TYPE": "MACHINE",
            "L_SIGNATURE": null,
            "L_SELFCARE": 0,
            "L_CACHE_INITIALS": "",
            "L_INITIALS": null,
            "L_STATISTICS_ENABLE": 0,
            "roles": [
                {
                    "LR_ID": 675,
                    "LR_CP_ID": null,
                    "LR_NAME": "modi rerum ex",
                    "LR_LEVEL": 4,
                    "LR_NOTE": null,
                    "LR_CREATED": "2026-04-13 15:46:31",
                    "LR_L_ID": 1,
                    "pivot": {
                        "LRC_L_ID": 5561,
                        "LRC_LR_ID": 675
                    }
                }
            ],
            "effective_rights": [
                {
                    "ID": 316410657,
                    "USER_ID": 5561,
                    "NAME": "ab-reiciendis-quia",
                    "OPTIONS": ""
                }
            ],
            "own_rights": []
        }
    ]
}

Request      

GET api/v3/operators

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of results per page. Example: 15

page   integer  optional    

Page number. Example: 1

ids   string  optional    

Filter by comma-separated operator IDs. Example: 294,705

active   string  optional    

Filter by active status. When omitted, only active operators are returned. Example: true

role   integer  optional    

Filter operators by assigned role ID. Example: 12

type   string  optional    

Filter by operator type (PERSON, MACHINE, COOPERATION). Example: PERSON

search   string  optional    

Search in name, surname, login, and email. Example: jan

include_internal   string  optional    

Include internal operators (L_CP_ID IS NULL) with limited fields. Only relevant for partner-bound users. Example: true

Response

Response Fields

data   object     
ID   integer     

Unique operator identifier (primary key).

FIRST_NAME   string     

First name of the operator.

SURNAME   string     

Surname of the operator.

full_name   string     

Computed full name (Surname Firstname).

LOGIN   string     

Login username (unique).

L_INITIALS   string     

Operator initials (manually set).

L_CACHE_INITIALS   string     

Computed operator initials cache.

L_SIGNATURE   string     

Scanned signature for document templates.

L_TYPE   string     

Operator type. "PERSON" = human operator, "MACHINE" = automated agent, "COOPERATION" = external cooperation partner.

Must be one of:
  • PERSON
  • MACHINE
  • COOPERATION
L_ACTIVE   integer     

Flag: active (1) or inactive (0).

L_LEVEL   integer     

Permission level (0–255). Higher level can manage lower-level operators.

L_CP_ID   integer     

CIBS partner ID. NULL for internal (global) operators.

MAIL   string     

Email address(es), comma-separated.

PHONE   integer     

Phone number (raw bigint).

NOTE   string     

Free-text note.

SALESMAN   integer     

Flag: operator is a sales representative (0/1).

L_SMS_ENABLE   integer     

Flag: can send SMS requests (0/1).

L_SELFCARE   integer     

Flag: selfcare operator (0/1).

L_STATISTICS_ENABLE   integer     

Flag: login statistics recording enabled (0/1).

L_PASS_EXPIRE   integer     

Password expiration (days). Positive: N days from last change. Negative: immediate then -N-1 days. 0/NULL: never.

L_PASS_CHANGE   string     

Datetime of last password change.

LOG_LEVEL   string     

Logging level.

Must be one of:
  • EMERG
  • ALERT
  • CRIT
  • ERR
  • WARNING
  • NOTICE
  • INFO
  • DEBUG
L_CREATED   string     

Account creation datetime.

L_L_ID   integer     

ID of the operator who created this account.

effective_rights   object[]     

All effective rights (own + role-inherited), computed by the system. Loaded on index and show.
ID   integer     

Unique effective right record ID.

USER_ID   integer     

Operator ID this right belongs to.

NAME   string     

Right name/key. See GET /v3/rights-definitions for the catalogue of available rights.

OPTIONS   string     

Right value or options string.

own_rights   object[]     

Rights directly assigned to this operator (not inherited from roles). Loaded on index and show.
ID   integer     

Unique right assignment record ID.

UR_TYPE   string     

Assignment type. Always "LOGIN" for own rights.

Must be one of:
  • LOGIN
  • ROLE
USER_ID   integer     

Operator ID this right is assigned to.

UR_LR_ID   integer     

Role ID (null for directly assigned rights).

NAME   string     

Right name/key. See GET /v3/rights-definitions for the catalogue of available rights.

OPTIONS   string     

Right value or options string.

CIBS_VERSION   string     

CIBS version restriction. NULL means the right applies to all versions.

UR_CREATED   string     

Right assignment creation datetime.

UR_CREATOR_L_ID   integer     

ID of the operator who created this right assignment.

roles   object[]     

Roles assigned to this operator. On show, each role includes its rights.
LR_ID   integer     

Unique role identifier. See GET /v3/operator-roles/{id}.

LR_CP_ID   integer     

CIBS partner ID. NULL for global roles.

LR_NAME   string     

Role name.

LR_LEVEL   integer     

Role level (0–255).

LR_NOTE   string     

Free-text note.

LR_CREATED   string     

Role creation datetime.

LR_L_ID   integer     

ID of the operator who created this role.

rights   object[]     

Rights assigned to this role (loaded on show only).
ID   integer     

Unique right assignment record ID.

UR_TYPE   string     

Assignment type. Always "ROLE" for role-inherited rights.

Must be one of:
  • LOGIN
  • ROLE
USER_ID   integer     

Operator ID (null for role-level assignments).

UR_LR_ID   integer     

Role ID this right belongs to.

NAME   string     

Right name/key. See GET /v3/rights-definitions.

OPTIONS   string     

Right value or options string.

CIBS_VERSION   string     

CIBS version restriction. NULL means all versions.

UR_CREATED   string     

Right assignment creation datetime.

UR_CREATOR_L_ID   integer     

ID of the operator who created this assignment.

Get Operator

requires authentication 

Returns a single operator by ID, including roles (with their rights),
effective rights, and own rights.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/operators/0" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/operators/0"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "ID": 5562,
        "FIRST_NAME": "Morgan",
        "SURNAME": "Hirthe",
        "LOGIN": "pfritsch",
        "L_LEVEL": 4,
        "MAIL": "[email protected]",
        "PHONE": null,
        "NOTE": null,
        "SALESMAN": 0,
        "L_SMS_ENABLE": 0,
        "LOG_LEVEL": "NOTICE",
        "L_CP_ID": null,
        "L_CREATED": "2026-03-18 04:07:19",
        "L_L_ID": 1,
        "L_ACTIVE": 1,
        "L_PASS_EXPIRE": null,
        "L_PASS_CHANGE": null,
        "L_TYPE": "MACHINE",
        "L_SIGNATURE": null,
        "L_SELFCARE": 0,
        "L_CACHE_INITIALS": "",
        "L_INITIALS": null,
        "L_STATISTICS_ENABLE": 0,
        "roles": [
            {
                "LR_ID": 676,
                "LR_CP_ID": null,
                "LR_NAME": "deleniti distinctio eum",
                "LR_LEVEL": 2,
                "LR_NOTE": null,
                "LR_CREATED": "2026-04-08 02:32:10",
                "LR_L_ID": 1,
                "pivot": {
                    "LRC_L_ID": 5562,
                    "LRC_LR_ID": 676
                },
                "rights": [
                    {
                        "ID": 650393,
                        "UR_TYPE": "ROLE",
                        "USER_ID": 1,
                        "UR_LR_ID": 676,
                        "NAME": "libero-aliquam-veniam",
                        "OPTIONS": "",
                        "CIBS_VERSION": null,
                        "UR_CREATED": "2026-02-26 03:42:08",
                        "UR_CREATOR_L_ID": 1
                    }
                ]
            }
        ],
        "effective_rights": [
            {
                "ID": 316410658,
                "USER_ID": 5562,
                "NAME": "deleniti-nemo",
                "OPTIONS": ""
            }
        ],
        "own_rights": []
    }
}

Request      

GET api/v3/operators/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the operator. Example: 0

Response

Response Fields

data   object     
ID   integer     

Unique operator identifier (primary key).

FIRST_NAME   string     

First name of the operator.

SURNAME   string     

Surname of the operator.

full_name   string     

Computed full name (Surname Firstname).

LOGIN   string     

Login username (unique).

L_INITIALS   string     

Operator initials (manually set).

L_CACHE_INITIALS   string     

Computed operator initials cache.

L_SIGNATURE   string     

Scanned signature for document templates.

L_TYPE   string     

Operator type. "PERSON" = human operator, "MACHINE" = automated agent, "COOPERATION" = external cooperation partner.

Must be one of:
  • PERSON
  • MACHINE
  • COOPERATION
L_ACTIVE   integer     

Flag: active (1) or inactive (0).

L_LEVEL   integer     

Permission level (0–255). Higher level can manage lower-level operators.

L_CP_ID   integer     

CIBS partner ID. NULL for internal (global) operators.

MAIL   string     

Email address(es), comma-separated.

PHONE   integer     

Phone number (raw bigint).

NOTE   string     

Free-text note.

SALESMAN   integer     

Flag: operator is a sales representative (0/1).

L_SMS_ENABLE   integer     

Flag: can send SMS requests (0/1).

L_SELFCARE   integer     

Flag: selfcare operator (0/1).

L_STATISTICS_ENABLE   integer     

Flag: login statistics recording enabled (0/1).

L_PASS_EXPIRE   integer     

Password expiration (days). Positive: N days from last change. Negative: immediate then -N-1 days. 0/NULL: never.

L_PASS_CHANGE   string     

Datetime of last password change.

LOG_LEVEL   string     

Logging level.

Must be one of:
  • EMERG
  • ALERT
  • CRIT
  • ERR
  • WARNING
  • NOTICE
  • INFO
  • DEBUG
L_CREATED   string     

Account creation datetime.

L_L_ID   integer     

ID of the operator who created this account.

effective_rights   object[]     

All effective rights (own + role-inherited), computed by the system. Loaded on index and show.
ID   integer     

Unique effective right record ID.

USER_ID   integer     

Operator ID this right belongs to.

NAME   string     

Right name/key. See GET /v3/rights-definitions for the catalogue of available rights.

OPTIONS   string     

Right value or options string.

own_rights   object[]     

Rights directly assigned to this operator (not inherited from roles). Loaded on index and show.
ID   integer     

Unique right assignment record ID.

UR_TYPE   string     

Assignment type. Always "LOGIN" for own rights.

Must be one of:
  • LOGIN
  • ROLE
USER_ID   integer     

Operator ID this right is assigned to.

UR_LR_ID   integer     

Role ID (null for directly assigned rights).

NAME   string     

Right name/key. See GET /v3/rights-definitions for the catalogue of available rights.

OPTIONS   string     

Right value or options string.

CIBS_VERSION   string     

CIBS version restriction. NULL means the right applies to all versions.

UR_CREATED   string     

Right assignment creation datetime.

UR_CREATOR_L_ID   integer     

ID of the operator who created this right assignment.

roles   object[]     

Roles assigned to this operator. On show, each role includes its rights.
LR_ID   integer     

Unique role identifier. See GET /v3/operator-roles/{id}.

LR_CP_ID   integer     

CIBS partner ID. NULL for global roles.

LR_NAME   string     

Role name.

LR_LEVEL   integer     

Role level (0–255).

LR_NOTE   string     

Free-text note.

LR_CREATED   string     

Role creation datetime.

LR_L_ID   integer     

ID of the operator who created this role.

rights   object[]     

Rights assigned to this role (loaded on show only).
ID   integer     

Unique right assignment record ID.

UR_TYPE   string     

Assignment type. Always "ROLE" for role-inherited rights.

Must be one of:
  • LOGIN
  • ROLE
USER_ID   integer     

Operator ID (null for role-level assignments).

UR_LR_ID   integer     

Role ID this right belongs to.

NAME   string     

Right name/key. See GET /v3/rights-definitions.

OPTIONS   string     

Right value or options string.

CIBS_VERSION   string     

CIBS version restriction. NULL means all versions.

UR_CREATED   string     

Right assignment creation datetime.

UR_CREATOR_L_ID   integer     

ID of the operator who created this assignment.

Payment Accounts

List Payment Accounts

requires authentication

Returns a paginated list of payment accounts (cash registers and bank accounts). By default only active accounts are returned; use active=false for inactive. CT scoping is indirect — only accounts linked to at least one of the user's authorized locations (via pay_account_loc) are visible.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/payment-accounts?per_page=15&page=1&ids=2%2C11%2C12&cts=11%2C12&type=cash&active=false&search=Pokladna" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/payment-accounts"
);

const params = {
    "per_page": "15",
    "page": "1",
    "ids": "2,11,12",
    "cts": "11,12",
    "type": "cash",
    "active": "false",
    "search": "Pokladna",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "PA_ID": 1530,
            "PA_TYPE": "cash",
            "PA_CC_ID": 1,
            "PA_NAME": "adipisci quidem nostrum",
            "PA_ACCOUNT_PREFIX": null,
            "PA_ACCOUNT_NUMBER": null,
            "PA_ACCOUNT_BANK": null,
            "PA_IBAN": null,
            "PA_IMPORT_TYPE": "gpc",
            "PA_COLLECTION_TYPE": "kpc",
            "PA_CP_ID": 1,
            "PA_ACTUAL": 1,
            "PA_IMPORT_CHECK": "STATEMENT_NO",
            "PA_IMPORT_DATE": null,
            "PA_COMMISSION": "none",
            "PA_CORRELATION": null,
            "PA_CORRELATION_CARD": null,
            "PA_CORRELATION_SIPO": null,
            "PA_NO_CHARGED": null,
            "PA_WRITE_OFF": null,
            "PA_EET": null,
            "PA_EET_DEFAULT": null,
            "PA_EET_SHOP_SIGN": null,
            "PA_EET_CASH_SIGN": null,
            "PA_EET_NOTIFICATION": null,
            "PA_AUTOCONFIRM": 0,
            "PA_AUTOCONFIRM_DAY": null,
            "PA_AUTOCONFIRM_TYPE": null,
            "PA_AUTOCONFIRM_MAKE_PAYMENT": null,
            "PA_AUTOCONFIRM_NOTIFICATION": null,
            "PA_AUTOCONFIRM_SEND_ALWAYS": null,
            "PA_AUTOGENERATE": 0,
            "PA_AUTOGENERATE_DAY": null,
            "PA_AUTOGENERATE_TYPE": null,
            "PA_AUTOGENERATE_NOTIFICATION": null,
            "PA_AUTOGENERATE_SEND_ALWAYS": null,
            "PA_ROUNDING": null,
            "PA_ROUNDING_VALUE": null,
            "PA_ROUNDING_REVENUES_ACCOUNT": null,
            "PA_ROUNDING_COST_ACCOUNT": null,
            "PA_CREATE_L_ID": 1,
            "PA_CREATED": "2026-03-08 11:29:09",
            "locations": [
                {
                    "PAL_ID": 1556,
                    "PAL_PA_ID": 1530,
                    "PAL_CT": 10,
                    "PAL_PROVIDER_USER_ID": null,
                    "PAL_DEFAULT": 0
                }
            ]
        },
        {
            "PA_ID": 1531,
            "PA_TYPE": "cash",
            "PA_CC_ID": 1,
            "PA_NAME": "iure odit et",
            "PA_ACCOUNT_PREFIX": null,
            "PA_ACCOUNT_NUMBER": null,
            "PA_ACCOUNT_BANK": null,
            "PA_IBAN": null,
            "PA_IMPORT_TYPE": "gpc",
            "PA_COLLECTION_TYPE": "kpc",
            "PA_CP_ID": 1,
            "PA_ACTUAL": 1,
            "PA_IMPORT_CHECK": "STATEMENT_NO",
            "PA_IMPORT_DATE": null,
            "PA_COMMISSION": "none",
            "PA_CORRELATION": null,
            "PA_CORRELATION_CARD": null,
            "PA_CORRELATION_SIPO": null,
            "PA_NO_CHARGED": null,
            "PA_WRITE_OFF": null,
            "PA_EET": null,
            "PA_EET_DEFAULT": null,
            "PA_EET_SHOP_SIGN": null,
            "PA_EET_CASH_SIGN": null,
            "PA_EET_NOTIFICATION": null,
            "PA_AUTOCONFIRM": 0,
            "PA_AUTOCONFIRM_DAY": null,
            "PA_AUTOCONFIRM_TYPE": null,
            "PA_AUTOCONFIRM_MAKE_PAYMENT": null,
            "PA_AUTOCONFIRM_NOTIFICATION": null,
            "PA_AUTOCONFIRM_SEND_ALWAYS": null,
            "PA_AUTOGENERATE": 0,
            "PA_AUTOGENERATE_DAY": null,
            "PA_AUTOGENERATE_TYPE": null,
            "PA_AUTOGENERATE_NOTIFICATION": null,
            "PA_AUTOGENERATE_SEND_ALWAYS": null,
            "PA_ROUNDING": null,
            "PA_ROUNDING_VALUE": null,
            "PA_ROUNDING_REVENUES_ACCOUNT": null,
            "PA_ROUNDING_COST_ACCOUNT": null,
            "PA_CREATE_L_ID": 1,
            "PA_CREATED": "2026-01-04 19:34:58",
            "locations": [
                {
                    "PAL_ID": 1557,
                    "PAL_PA_ID": 1531,
                    "PAL_CT": 8,
                    "PAL_PROVIDER_USER_ID": null,
                    "PAL_DEFAULT": 0
                }
            ]
        }
    ]
}

Request      

GET api/v3/payment-accounts

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of items per page (max 100). Example: 15

page   integer  optional    

Page number. Example: 1

ids   string  optional    

Filter by comma-separated payment account IDs. Example: 2,11,12

cts   string  optional    

Filter by comma-separated location (installation) IDs. Returns accounts linked to any of the given locations. Overrides X-CT header default. Example: 11,12

type   string  optional    

Filter by account type. Example: cash

active   string  optional    

Filter by active status. When omitted, only active accounts (PA_ACTUAL = 1) are returned. Example: false

search   string  optional    

Search by account name (PA_NAME). Example: Pokladna

Response

Response Fields

data   object     
PA_ID   integer     

Unique payment account identifier (primary key).

PA_TYPE   string     

Account type: 'cash' = cash register, 'bank' = bank account.

Must be one of:
  • cash
  • bank
PA_NAME   string     

Display name of the account (max 40 chars).

PA_CC_ID   integer     

Currency code FK (→ currency_codes.CC_ID).

PA_CP_ID   integer     

CIBS partner FK — the partner this account belongs to.

PA_ACCOUNT_PREFIX   string     

Bank account prefix (Czech format, up to 6 digits).

PA_ACCOUNT_NUMBER   string     

Bank account number (up to 17 digits).

PA_ACCOUNT_BANK   string     

Bank code (4-digit Czech bank code).

PA_IBAN   string     

International Bank Account Number (IBAN).

PA_IMPORT_TYPE   string     

Bank statement import format.

Must be one of:
  • gpc
  • csv
  • txt
  • ace
  • uni
  • acr
  • MT940
  • gpp
  • citi
  • rbsv
  • csas
  • SAP
PA_COLLECTION_TYPE   string     

Collection file format.

Must be one of:
  • kpc
  • gemini
PA_IMPORT_CHECK   string     

Duplicate detection method during import.

Must be one of:
  • NONE
  • STATEMENT_NO
  • RECORD_NO
  • DATA
PA_IMPORT_DATE   string     

Date source for import: 'head' = statement header, 'item' = transaction item.

Must be one of:
  • head
  • item
PA_COMMISSION   string     

Card payment commission import mode: 'none' or 'txt'.

Must be one of:
  • none
  • txt
PA_ACTUAL   integer     

Active flag. 1 = current/active, 0 = inactive.

PA_CORRELATION   integer     

Ledger account number for accounting correlation.

PA_CORRELATION_CARD   integer     

Ledger account for card payment correlation.

PA_CORRELATION_SIPO   integer     

Ledger account for SIPO payment correlation.

PA_NO_CHARGED   integer     

Non-accounting register flag (cash registers only).

PA_WRITE_OFF   integer     

Write-off register flag (cash registers only).

PA_EET   integer     

EET enabled flag.

PA_EET_DEFAULT   integer     

Default EET register flag.

PA_EET_SHOP_SIGN   integer     

EET shop identification number.

PA_EET_CASH_SIGN   string     

EET cash register identifier.

PA_EET_NOTIFICATION   string     

EET notification template (longtext).

PA_AUTOCONFIRM   integer     

Auto-confirmation of payments enabled flag.

PA_AUTOCONFIRM_DAY   integer     

Day of month for auto-confirmation.

PA_AUTOCONFIRM_TYPE   string     

Auto-confirmation scope: 'ALL', 'CIBS', or 'OTHER'.

Must be one of:
  • ALL
  • CIBS
  • OTHER
PA_AUTOCONFIRM_MAKE_PAYMENT   integer     

Also create payment during auto-confirmation.

PA_AUTOCONFIRM_NOTIFICATION   string     

Auto-confirmation notification template.

PA_AUTOCONFIRM_SEND_ALWAYS   integer     

Always send auto-confirmation notification.

PA_AUTOGENERATE   integer     

Auto-generation of payment orders enabled flag.

PA_AUTOGENERATE_DAY   integer     

Day of month for auto-generation.

PA_AUTOGENERATE_TYPE   string     

Auto-generation scope: 'ALL', 'CIBS', or 'OTHER'.

Must be one of:
  • ALL
  • CIBS
  • OTHER
PA_AUTOGENERATE_NOTIFICATION   string     

Auto-generation notification template.

PA_AUTOGENERATE_SEND_ALWAYS   integer     

Always send auto-generation notification.

PA_ROUNDING   integer     

Payment rounding enabled flag (cash registers only).

PA_ROUNDING_VALUE   string     

Maximum rounding value (decimal).

PA_ROUNDING_REVENUES_ACCOUNT   integer     

Ledger account for rounding revenues.

PA_ROUNDING_COST_ACCOUNT   integer     

Ledger account for rounding costs.

PA_CREATE_L_ID   integer     

Operator ID who created this record.

PA_CREATED   string     

Creation timestamp (YYYY-MM-DD HH:MM:SS).

locations   object[]     

Business locations (CTs) where this payment account operates.
PAL_ID   integer     

Unique location assignment ID.

PAL_PA_ID   integer     

Payment account ID.

PAL_CT   integer     

Business location (installation) ID.

PAL_PROVIDER_USER_ID   integer     

Provider user ID for this account at this location.

PAL_DEFAULT   integer     

Default account flag within location/provider. 1 = default.

Get Payment Account

requires authentication

Returns a single payment account by ID, including its business location assignments.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/payment-accounts/2" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/payment-accounts/2"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "PA_ID": 1532,
        "PA_TYPE": "cash",
        "PA_CC_ID": 1,
        "PA_NAME": "adipisci quidem nostrum",
        "PA_ACCOUNT_PREFIX": null,
        "PA_ACCOUNT_NUMBER": null,
        "PA_ACCOUNT_BANK": null,
        "PA_IBAN": null,
        "PA_IMPORT_TYPE": "gpc",
        "PA_COLLECTION_TYPE": "kpc",
        "PA_CP_ID": 1,
        "PA_ACTUAL": 1,
        "PA_IMPORT_CHECK": "STATEMENT_NO",
        "PA_IMPORT_DATE": null,
        "PA_COMMISSION": "none",
        "PA_CORRELATION": null,
        "PA_CORRELATION_CARD": null,
        "PA_CORRELATION_SIPO": null,
        "PA_NO_CHARGED": null,
        "PA_WRITE_OFF": null,
        "PA_EET": null,
        "PA_EET_DEFAULT": null,
        "PA_EET_SHOP_SIGN": null,
        "PA_EET_CASH_SIGN": null,
        "PA_EET_NOTIFICATION": null,
        "PA_AUTOCONFIRM": 0,
        "PA_AUTOCONFIRM_DAY": null,
        "PA_AUTOCONFIRM_TYPE": null,
        "PA_AUTOCONFIRM_MAKE_PAYMENT": null,
        "PA_AUTOCONFIRM_NOTIFICATION": null,
        "PA_AUTOCONFIRM_SEND_ALWAYS": null,
        "PA_AUTOGENERATE": 0,
        "PA_AUTOGENERATE_DAY": null,
        "PA_AUTOGENERATE_TYPE": null,
        "PA_AUTOGENERATE_NOTIFICATION": null,
        "PA_AUTOGENERATE_SEND_ALWAYS": null,
        "PA_ROUNDING": null,
        "PA_ROUNDING_VALUE": null,
        "PA_ROUNDING_REVENUES_ACCOUNT": null,
        "PA_ROUNDING_COST_ACCOUNT": null,
        "PA_CREATE_L_ID": 1,
        "PA_CREATED": "2026-03-08 11:29:09",
        "locations": [
            {
                "PAL_ID": 1558,
                "PAL_PA_ID": 1532,
                "PAL_CT": 10,
                "PAL_PROVIDER_USER_ID": null,
                "PAL_DEFAULT": 0
            }
        ]
    }
}

Request      

GET api/v3/payment-accounts/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the payment account. Example: 2

Response

Response Fields

data   object     
PA_ID   integer     

Unique payment account identifier (primary key).

PA_TYPE   string     

Account type: 'cash' = cash register, 'bank' = bank account.

Must be one of:
  • cash
  • bank
PA_NAME   string     

Display name of the account (max 40 chars).

PA_CC_ID   integer     

Currency code FK (→ currency_codes.CC_ID).

PA_CP_ID   integer     

CIBS partner FK — the partner this account belongs to.

PA_ACCOUNT_PREFIX   string     

Bank account prefix (Czech format, up to 6 digits).

PA_ACCOUNT_NUMBER   string     

Bank account number (up to 17 digits).

PA_ACCOUNT_BANK   string     

Bank code (4-digit Czech bank code).

PA_IBAN   string     

International Bank Account Number (IBAN).

PA_IMPORT_TYPE   string     

Bank statement import format.

Must be one of:
  • gpc
  • csv
  • txt
  • ace
  • uni
  • acr
  • MT940
  • gpp
  • citi
  • rbsv
  • csas
  • SAP
PA_COLLECTION_TYPE   string     

Collection file format.

Must be one of:
  • kpc
  • gemini
PA_IMPORT_CHECK   string     

Duplicate detection method during import.

Must be one of:
  • NONE
  • STATEMENT_NO
  • RECORD_NO
  • DATA
PA_IMPORT_DATE   string     

Date source for import: 'head' = statement header, 'item' = transaction item.

Must be one of:
  • head
  • item
PA_COMMISSION   string     

Card payment commission import mode: 'none' or 'txt'.

Must be one of:
  • none
  • txt
PA_ACTUAL   integer     

Active flag. 1 = current/active, 0 = inactive.

PA_CORRELATION   integer     

Ledger account number for accounting correlation.

PA_CORRELATION_CARD   integer     

Ledger account for card payment correlation.

PA_CORRELATION_SIPO   integer     

Ledger account for SIPO payment correlation.

PA_NO_CHARGED   integer     

Non-accounting register flag (cash registers only).

PA_WRITE_OFF   integer     

Write-off register flag (cash registers only).

PA_EET   integer     

EET enabled flag.

PA_EET_DEFAULT   integer     

Default EET register flag.

PA_EET_SHOP_SIGN   integer     

EET shop identification number.

PA_EET_CASH_SIGN   string     

EET cash register identifier.

PA_EET_NOTIFICATION   string     

EET notification template (longtext).

PA_AUTOCONFIRM   integer     

Auto-confirmation of payments enabled flag.

PA_AUTOCONFIRM_DAY   integer     

Day of month for auto-confirmation.

PA_AUTOCONFIRM_TYPE   string     

Auto-confirmation scope: 'ALL', 'CIBS', or 'OTHER'.

Must be one of:
  • ALL
  • CIBS
  • OTHER
PA_AUTOCONFIRM_MAKE_PAYMENT   integer     

Also create payment during auto-confirmation.

PA_AUTOCONFIRM_NOTIFICATION   string     

Auto-confirmation notification template.

PA_AUTOCONFIRM_SEND_ALWAYS   integer     

Always send auto-confirmation notification.

PA_AUTOGENERATE   integer     

Auto-generation of payment orders enabled flag.

PA_AUTOGENERATE_DAY   integer     

Day of month for auto-generation.

PA_AUTOGENERATE_TYPE   string     

Auto-generation scope: 'ALL', 'CIBS', or 'OTHER'.

Must be one of:
  • ALL
  • CIBS
  • OTHER
PA_AUTOGENERATE_NOTIFICATION   string     

Auto-generation notification template.

PA_AUTOGENERATE_SEND_ALWAYS   integer     

Always send auto-generation notification.

PA_ROUNDING   integer     

Payment rounding enabled flag (cash registers only).

PA_ROUNDING_VALUE   string     

Maximum rounding value (decimal).

PA_ROUNDING_REVENUES_ACCOUNT   integer     

Ledger account for rounding revenues.

PA_ROUNDING_COST_ACCOUNT   integer     

Ledger account for rounding costs.

PA_CREATE_L_ID   integer     

Operator ID who created this record.

PA_CREATED   string     

Creation timestamp (YYYY-MM-DD HH:MM:SS).

locations   object[]     

Business locations (CTs) where this payment account operates.
PAL_ID   integer     

Unique location assignment ID.

PAL_PA_ID   integer     

Payment account ID.

PAL_CT   integer     

Business location (installation) ID.

PAL_PROVIDER_USER_ID   integer     

Provider user ID for this account at this location.

PAL_DEFAULT   integer     

Default account flag within location/provider. 1 = default.

Payments

List Payments

requires authentication

Returns a paginated list of payments. At least one of the following filters must be provided: customer, account, date_from, var_symbol. Without a narrowing filter the endpoint returns HTTP 422.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/payments?per_page=10&page=1&ids=100%2C200%2C300&cts=1%2C2%2C3&customer=1009&account=1&type=P&join_type=U&date_from=2024-01-01&date_to=2024-12-31&var_symbol=1234567890" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/payments"
);

const params = {
    "per_page": "10",
    "page": "1",
    "ids": "100,200,300",
    "cts": "1,2,3",
    "customer": "1009",
    "account": "1",
    "type": "P",
    "join_type": "U",
    "date_from": "2024-01-01",
    "date_to": "2024-12-31",
    "var_symbol": "1234567890",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "ID": 24869000,
            "PL_PA_ID": null,
            "PAYMENT_DATE": "1981-11-24",
            "PL_DATE_ACCOUNT_BANK": null,
            "AMOUNT": "9473.3378",
            "TYPE": "H",
            "VAR_SYMBOL": 7214902,
            "PL_SPEC_SYMBOL": null,
            "PL_KONS_SYMBOL": null,
            "USER_ID": 5485,
            "CT": 95,
            "NOTE": null,
            "SYS_TIME": "2026-04-15 16:55:13",
            "PL_DOC_ID": null,
            "PL_JOIN_TYPE": "S",
            "PL_BANK_DOC_ID": null,
            "PL_BANK_ACC_PREFIX": null,
            "PL_BANK_ACC_NUMBER": null,
            "PL_BANK_ACC_BANK": null,
            "PL_IBAN": null,
            "PL_SIPO_ID": null,
            "PL_FLAG": "O",
            "PL_MATCHING_STRATEGY": 0,
            "PL_INTERNAL_ID": null,
            "PL_DATE_DEATTACH": null,
            "PL_AUTHOR_DEATTACH": null,
            "PL_UDF_TYPE": null,
            "PL_DEATTACH": null,
            "PL_DEATTACH_ATTACH": null,
            "PL_CREATE_L_ID": null,
            "PL_CREATED": null,
            "PL_CHANGE_L_ID": null,
            "PL_CHANGED": null,
            "PL_PF_ID": null,
            "PL_PROVIDER_USER_ID": null,
            "PL_CREDIT_NOTE_ADVANCE": null,
            "PL_CACHE_ATTACHED": null,
            "PL_CACHE_ADVANCE": null
        },
        {
            "ID": 24869001,
            "PL_PA_ID": null,
            "PAYMENT_DATE": "1990-02-03",
            "PL_DATE_ACCOUNT_BANK": null,
            "AMOUNT": "-7760.2620",
            "TYPE": "P",
            "VAR_SYMBOL": 8265058,
            "PL_SPEC_SYMBOL": null,
            "PL_KONS_SYMBOL": null,
            "USER_ID": 6877,
            "CT": 76,
            "NOTE": "Consequatur aut dolores enim non facere tempora.",
            "SYS_TIME": "2026-04-15 16:55:13",
            "PL_DOC_ID": null,
            "PL_JOIN_TYPE": "S",
            "PL_BANK_DOC_ID": null,
            "PL_BANK_ACC_PREFIX": null,
            "PL_BANK_ACC_NUMBER": null,
            "PL_BANK_ACC_BANK": null,
            "PL_IBAN": null,
            "PL_SIPO_ID": null,
            "PL_FLAG": "O",
            "PL_MATCHING_STRATEGY": 0,
            "PL_INTERNAL_ID": null,
            "PL_DATE_DEATTACH": null,
            "PL_AUTHOR_DEATTACH": null,
            "PL_UDF_TYPE": null,
            "PL_DEATTACH": null,
            "PL_DEATTACH_ATTACH": null,
            "PL_CREATE_L_ID": null,
            "PL_CREATED": null,
            "PL_CHANGE_L_ID": null,
            "PL_CHANGED": null,
            "PL_PF_ID": null,
            "PL_PROVIDER_USER_ID": null,
            "PL_CREDIT_NOTE_ADVANCE": null,
            "PL_CACHE_ATTACHED": null,
            "PL_CACHE_ADVANCE": null
        }
    ]
}

Request      

GET api/v3/payments

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of items per page. Example: 10

page   integer  optional    

Page number. Example: 1

ids   string  optional    

Filter by comma-separated payment IDs. Example: 100,200,300

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Example: 1,2,3

customer   integer  optional    

Filter by customer (user) ID. Example: 1009

account   integer  optional    

Filter by payment account ID. Example: 1

type   string  optional    

Filter by payment method (TYPE column). Example: P

join_type   string  optional    

Filter by matching status. U = Mango, O = Other, S = SIPO, N = Unmatched, C = Card. Example: U

date_from   string  optional    

Filter payments on or after this date (YYYY-MM-DD). Example: 2024-01-01

date_to   string  optional    

Filter payments on or before this date (YYYY-MM-DD). Example: 2024-12-31

var_symbol   integer  optional    

Filter by variable symbol. Example: 1234567890

Response

Response Fields

data   object     
ID   integer     

Unique payment identifier (primary key).

PL_PA_ID   integer     

Payment account (cash register / bank account) ID. See GET /v3/payment-accounts/{id}.

USER_ID   integer     

Customer ID this payment belongs to. See GET /v3/customers/{id}.

CT   integer     

Location (installation) ID — multi-tenant discriminator.

PAYMENT_DATE   string     

Payment date (YYYY-MM-DD).

AMOUNT   string     

Payment amount (decimal, 4 decimal places).

TYPE   string     

Payment method code (e.g. P = bank transfer, H = cash).

PL_JOIN_TYPE   string     

Matching status. U = Mango (matched automatically), O = Other, S = SIPO, N = Unmatched, C = Card.

Must be one of:
  • U
  • O
  • S
  • N
  • C
PL_FLAG   string     

Payment flag. O = ordinary, B = balance sheet.

Must be one of:
  • O
  • B
VAR_SYMBOL   integer     

Variable symbol — used for payment identification and matching.

PL_SPEC_SYMBOL   integer     

Specific symbol.

PL_KONS_SYMBOL   integer     

Constant symbol.

PL_BANK_ACC_PREFIX   integer     

Counter-party bank account prefix.

PL_BANK_ACC_NUMBER   integer     

Counter-party bank account number.

PL_BANK_ACC_BANK   integer     

Counter-party bank code.

PL_IBAN   string     

Counter-party IBAN.

PL_SIPO_ID   string     

SIPO identification code.

PL_DOC_ID   integer     

Receipt / document ID.

PL_BANK_DOC_ID   integer     

Bank statement document ID.

PL_DATE_ACCOUNT_BANK   string     

Bank settlement date (YYYY-MM-DD).

PL_MATCHING_STRATEGY   integer     

Matching strategy identifier.

PL_INTERNAL_ID   integer     

Internal reference ID (for linked/split payments).

PL_UDF_TYPE   integer     

User-defined field type.

PL_PF_ID   integer     

Payment file ID (import batch reference).

PL_PROVIDER_USER_ID   integer     

Provider customer ID (for provider-level payments).

PL_CREDIT_NOTE_ADVANCE   integer     

Credit note advance flag.

PL_CACHE_ATTACHED   string     

Cached total of matched (attached) amount.

PL_CACHE_ADVANCE   string     

Cached advance (overpayment) amount.

PL_DEATTACH   integer     

Detachment flag.

PL_DEATTACH_ATTACH   integer     

Detach-and-reattach flag.

PL_DATE_DEATTACH   string     

Detachment datetime.

PL_AUTHOR_DEATTACH   integer     

Operator ID who performed the detachment.

NOTE   string     

Payment note / description.

SYS_TIME   string     

Last modification timestamp (auto-updated).

PL_CREATED   string     

Creation datetime.

PL_CREATE_L_ID   integer     

Operator login ID who created the record.

PL_CHANGED   string     

Last change datetime.

PL_CHANGE_L_ID   integer     

Operator login ID who last modified the record.

customer_name   string     

Computed customer display name (derived from USER_ID via get_user_name). NULL when USER_ID is absent or zero.

Get Payment

requires authentication

Returns a single payment by ID.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/payments/259" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/payments/259"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "ID": 24869002,
        "PL_PA_ID": null,
        "PAYMENT_DATE": "1981-11-24",
        "PL_DATE_ACCOUNT_BANK": null,
        "AMOUNT": "9473.3378",
        "TYPE": "H",
        "VAR_SYMBOL": 8988862,
        "PL_SPEC_SYMBOL": null,
        "PL_KONS_SYMBOL": null,
        "USER_ID": 5485,
        "CT": 95,
        "NOTE": null,
        "SYS_TIME": "2026-04-15 16:55:13",
        "PL_DOC_ID": null,
        "PL_JOIN_TYPE": "S",
        "PL_BANK_DOC_ID": null,
        "PL_BANK_ACC_PREFIX": null,
        "PL_BANK_ACC_NUMBER": null,
        "PL_BANK_ACC_BANK": null,
        "PL_IBAN": null,
        "PL_SIPO_ID": null,
        "PL_FLAG": "O",
        "PL_MATCHING_STRATEGY": 0,
        "PL_INTERNAL_ID": null,
        "PL_DATE_DEATTACH": null,
        "PL_AUTHOR_DEATTACH": null,
        "PL_UDF_TYPE": null,
        "PL_DEATTACH": null,
        "PL_DEATTACH_ATTACH": null,
        "PL_CREATE_L_ID": null,
        "PL_CREATED": null,
        "PL_CHANGE_L_ID": null,
        "PL_CHANGED": null,
        "PL_PF_ID": null,
        "PL_PROVIDER_USER_ID": null,
        "PL_CREDIT_NOTE_ADVANCE": null,
        "PL_CACHE_ATTACHED": null,
        "PL_CACHE_ADVANCE": null
    }
}

Request      

GET api/v3/payments/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the payment. Example: 259

Response

Response Fields

data   object     
ID   integer     

Unique payment identifier (primary key).

PL_PA_ID   integer     

Payment account (cash register / bank account) ID. See GET /v3/payment-accounts/{id}.

USER_ID   integer     

Customer ID this payment belongs to. See GET /v3/customers/{id}.

CT   integer     

Location (installation) ID — multi-tenant discriminator.

PAYMENT_DATE   string     

Payment date (YYYY-MM-DD).

AMOUNT   string     

Payment amount (decimal, 4 decimal places).

TYPE   string     

Payment method code (e.g. P = bank transfer, H = cash).

PL_JOIN_TYPE   string     

Matching status. U = Mango (matched automatically), O = Other, S = SIPO, N = Unmatched, C = Card.

Must be one of:
  • U
  • O
  • S
  • N
  • C
PL_FLAG   string     

Payment flag. O = ordinary, B = balance sheet.

Must be one of:
  • O
  • B
VAR_SYMBOL   integer     

Variable symbol — used for payment identification and matching.

PL_SPEC_SYMBOL   integer     

Specific symbol.

PL_KONS_SYMBOL   integer     

Constant symbol.

PL_BANK_ACC_PREFIX   integer     

Counter-party bank account prefix.

PL_BANK_ACC_NUMBER   integer     

Counter-party bank account number.

PL_BANK_ACC_BANK   integer     

Counter-party bank code.

PL_IBAN   string     

Counter-party IBAN.

PL_SIPO_ID   string     

SIPO identification code.

PL_DOC_ID   integer     

Receipt / document ID.

PL_BANK_DOC_ID   integer     

Bank statement document ID.

PL_DATE_ACCOUNT_BANK   string     

Bank settlement date (YYYY-MM-DD).

PL_MATCHING_STRATEGY   integer     

Matching strategy identifier.

PL_INTERNAL_ID   integer     

Internal reference ID (for linked/split payments).

PL_UDF_TYPE   integer     

User-defined field type.

PL_PF_ID   integer     

Payment file ID (import batch reference).

PL_PROVIDER_USER_ID   integer     

Provider customer ID (for provider-level payments).

PL_CREDIT_NOTE_ADVANCE   integer     

Credit note advance flag.

PL_CACHE_ATTACHED   string     

Cached total of matched (attached) amount.

PL_CACHE_ADVANCE   string     

Cached advance (overpayment) amount.

PL_DEATTACH   integer     

Detachment flag.

PL_DEATTACH_ATTACH   integer     

Detach-and-reattach flag.

PL_DATE_DEATTACH   string     

Detachment datetime.

PL_AUTHOR_DEATTACH   integer     

Operator ID who performed the detachment.

NOTE   string     

Payment note / description.

SYS_TIME   string     

Last modification timestamp (auto-updated).

PL_CREATED   string     

Creation datetime.

PL_CREATE_L_ID   integer     

Operator login ID who created the record.

PL_CHANGED   string     

Last change datetime.

PL_CHANGE_L_ID   integer     

Operator login ID who last modified the record.

customer_name   string     

Computed customer display name (derived from USER_ID via get_user_name). NULL when USER_ID is absent or zero.

Process Jobs

List Process Jobs

requires authentication 

Returns a paginated list of jobs for a given process.
Jobs are always scoped to the parent process.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/processes/3/jobs?ids=1%2C2%2C3&state=PLANNED" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/processes/3/jobs"
);

const params = {
    "ids": "1,2,3",
    "state": "PLANNED",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "MJ_ID": 3424700,
            "MJ_ML_ID": 1460747,
            "MJ_ML_ORDER": null,
            "MJ_PLANNING_POLICY": "NONE",
            "MJ_MJT_ID": "050",
            "MJ_MJK_ID": null,
            "MJ_START": "2026-03-08 11:40:25",
            "MJ_STOP": null,
            "MJ_DURATION": 169,
            "MJ_RECURRENCE": null,
            "MJ_CACHE_RECURRENCE_HR": null,
            "MJ_SERMAN_ID": null,
            "MJ_SG_ID": null,
            "MJ_STATE": "PLANNED",
            "MJ_DESCRIPTION": null,
            "MJ_NOTE": null,
            "MJ_PRIVATE": 0,
            "MJ_DONE_TIME": null,
            "MJ_L_ID": "005556",
            "MJ_CREATED": "2026-03-05 06:52:02",
            "MJ_EDITED": "2026-04-15 16:55:11",
            "MJ_REAL_FINISH_TIME": null,
            "MJ_POINTS": null,
            "MJ_TIME_BLOCK_ID": null,
            "MJ_DATE": null,
            "MJ_FROM_DATE": null,
            "MJ_FROM_MTB_ID": null,
            "MJ_TO_DATE": null,
            "MJ_TO_MTB_ID": null,
            "MJ_LINKED_MJ_ID": null,
            "MJ_REAL_START_TIME": null,
            "MJ_AUTO_DONE": 0,
            "MJ_AUTO_DONE_MOMENT": null,
            "MJ_AUTO_DONE_ACTION": null,
            "MJ_CUSTOMER_COOP": 0,
            "MJ_INSERT_PAYMENT": null,
            "MJ_LAST_ACTION": null,
            "MJ_GA_ID": null,
            "MJ_UCP_ID": null,
            "MJ_US_ID": null,
            "MJ_UA_ID": null,
            "MJ_STREET": null,
            "MJ_HOUSE_ID": null,
            "MJ_ZIP": null,
            "MJ_CITY": null,
            "MJ_WORK_TIME": null,
            "MJ_CACHE_START": null,
            "MJ_CACHE_STOP": null,
            "MJ_CACHE_MAX_STOP": null,
            "MJ_EXPEDICE": null,
            "MJ_EXPEDANT_ID": null,
            "MJ_MJ_PREV_STARTED": null,
            "MJ_MJ_PREV_FINISHED": null,
            "MJ_PLANNING": 0,
            "attendees": [
                {
                    "MJA_ID": 1668348,
                    "MJA_JOIN_TYPE": "JOB",
                    "MJA_OBJ_ID": 3424700,
                    "MJA_L_ID": null,
                    "MJA_EMAIL": "[email protected]",
                    "MJA_RESPONSE_STATUS": "accepted",
                    "MJA_RESPONSE_NOTE": "Reiciendis quia perspiciatis deserunt ducimus corrupti et."
                }
            ]
        },
        {
            "MJ_ID": 3424701,
            "MJ_ML_ID": 1460748,
            "MJ_ML_ORDER": null,
            "MJ_PLANNING_POLICY": "TIMEBLOCK_RANGE",
            "MJ_MJT_ID": "100",
            "MJ_MJK_ID": null,
            "MJ_START": null,
            "MJ_STOP": null,
            "MJ_DURATION": 273,
            "MJ_RECURRENCE": null,
            "MJ_CACHE_RECURRENCE_HR": null,
            "MJ_SERMAN_ID": null,
            "MJ_SG_ID": null,
            "MJ_STATE": "CANCELED",
            "MJ_DESCRIPTION": "Nesciunt ut ratione iure impedit molestiae ut rem.",
            "MJ_NOTE": null,
            "MJ_PRIVATE": 0,
            "MJ_DONE_TIME": null,
            "MJ_L_ID": "005557",
            "MJ_CREATED": "2026-04-12 20:56:23",
            "MJ_EDITED": "2026-04-15 16:55:11",
            "MJ_REAL_FINISH_TIME": null,
            "MJ_POINTS": null,
            "MJ_TIME_BLOCK_ID": null,
            "MJ_DATE": null,
            "MJ_FROM_DATE": null,
            "MJ_FROM_MTB_ID": null,
            "MJ_TO_DATE": null,
            "MJ_TO_MTB_ID": null,
            "MJ_LINKED_MJ_ID": null,
            "MJ_REAL_START_TIME": null,
            "MJ_AUTO_DONE": 0,
            "MJ_AUTO_DONE_MOMENT": null,
            "MJ_AUTO_DONE_ACTION": null,
            "MJ_CUSTOMER_COOP": 0,
            "MJ_INSERT_PAYMENT": null,
            "MJ_LAST_ACTION": null,
            "MJ_GA_ID": null,
            "MJ_UCP_ID": null,
            "MJ_US_ID": null,
            "MJ_UA_ID": null,
            "MJ_STREET": null,
            "MJ_HOUSE_ID": null,
            "MJ_ZIP": null,
            "MJ_CITY": null,
            "MJ_WORK_TIME": null,
            "MJ_CACHE_START": null,
            "MJ_CACHE_STOP": null,
            "MJ_CACHE_MAX_STOP": null,
            "MJ_EXPEDICE": null,
            "MJ_EXPEDANT_ID": null,
            "MJ_MJ_PREV_STARTED": null,
            "MJ_MJ_PREV_FINISHED": null,
            "MJ_PLANNING": 0,
            "attendees": [
                {
                    "MJA_ID": 1668349,
                    "MJA_JOIN_TYPE": "JOB",
                    "MJA_OBJ_ID": 3424701,
                    "MJA_L_ID": null,
                    "MJA_EMAIL": "[email protected]",
                    "MJA_RESPONSE_STATUS": "needsAction",
                    "MJA_RESPONSE_NOTE": null
                }
            ]
        }
    ]
}

Request      

GET api/v3/processes/{process}/jobs

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

process   integer     

The process. Example: 3

Query Parameters

ids   string  optional    

Filter by comma-separated job IDs Example: 1,2,3

state   string  optional    

Filter by job state: PLANNED, DONE, CANCELED Example: PLANNED

Response

Response Fields

data   object     
MJ_ID   integer     

Unique job ID.

MJ_ML_ID   integer     

Parent process (maintenance list) ID. References maintenance_list.

MJ_ML_ORDER   integer     

Order of the job within the process.

MJ_PLANNING_POLICY   string     

Scheduling policy for the job. Determines which date/time fields are relevant.

Must be one of:
  • LONGTIME
  • TIMEBLOCK
  • TIMEBLOCK_RANGE
  • SEQUENCE
  • NONE
MJ_MJT_ID   integer     

Job type ID. References maintenance_job_types.

MJ_MJK_ID   integer     

Job kind (category) ID. References maintenance_job_kinds.

MJ_STATE   string     

Current state of the job.

Must be one of:
  • PLANNED
  • DONE
  • CANCELED
MJ_START   string     

Planned start date and time.

MJ_STOP   string     

Planned end date and time.

MJ_DURATION   integer     

Expected duration of the job in minutes.

MJ_FROM_DATE   string     

Start date for time-block or range scheduling.

MJ_FROM_MTB_ID   integer     

Start time-block ID. References maintenance_time_block.

MJ_TO_DATE   string     

End date for time-block range scheduling.

MJ_TO_MTB_ID   integer     

End time-block ID. References maintenance_time_block.

MJ_DATE   string     

Scheduled date for the job.

MJ_TIME_BLOCK_ID   integer     

Assigned time-block ID. References maintenance_time_block.

MJ_POINTS   integer     

Number of capacity points consumed by this job.

MJ_RECURRENCE   string     

Recurrence rule definition string.

MJ_CACHE_RECURRENCE_HR   string     

Cached human-readable representation of the recurrence rule.

MJ_SERMAN_ID   integer     

Assigned resource (serviceman) login ID. References logins.

MJ_SG_ID   integer     

Service group ID. References serman_groups.

MJ_L_ID   integer     

Login ID of the user who created or owns this job. References logins.

MJ_DESCRIPTION   string     

Task description / name of the job.

MJ_NOTE   string     

Note or progress log for the job.

MJ_PRIVATE   integer     

Whether the job is visible only to its assigned resource in the calendar. 1 = private, 0 = public.

MJ_CUSTOMER_COOP   integer     

Whether customer presence is required while processing the job. 1 = yes, 0 = no.

MJ_PLANNING   integer     

Whether this job is used only for planning/scheduling other jobs. 1 = planning-only, 0 = regular job.

MJ_EXPEDICE   integer     

Whether expedition (dispatch) is enabled for this job. 1 = yes, 0 = no.

MJ_AUTO_DONE   integer     

Whether the job should be automatically marked as done. 1 = yes, 0 = no.

MJ_AUTO_DONE_MOMENT   string     

When to trigger auto-done.

Must be one of:
  • ON_CREATE
  • ON_START
MJ_AUTO_DONE_ACTION   string     

Action identifier to execute when auto-done is triggered.

MJ_CREATED   string     

Timestamp when the job was created.

MJ_EDITED   string     

Timestamp when the job was last edited.

MJ_DONE_TIME   string     

Timestamp when the job was marked as done.

MJ_REAL_START_TIME   string     

Actual start time recorded by the assignee.

MJ_REAL_FINISH_TIME   string     

Actual finish date recorded by the assignee.

MJ_WORK_TIME   integer     

Actual work time spent on the job in minutes.

MJ_LAST_ACTION   string     

Identifier of the last action performed on this job.

MJ_CACHE_START   string     

Cached computed start datetime (resolved from scheduling rules).

MJ_CACHE_STOP   string     

Cached computed end datetime (resolved from scheduling rules).

MJ_CACHE_MAX_STOP   string     

Cached maximum possible end datetime.

MJ_GA_ID   integer     

Group address ID. References groups_address.

MJ_UCP_ID   integer     

UIR city part ID. References uir_city_parts.

MJ_US_ID   integer     

UIR street ID. References uir_streets.

MJ_UA_ID   integer     

UIR address ID. References uir_addresses.

MJ_STREET   string     

Street name of the job location.

MJ_HOUSE_ID   string     

House number at the job location.

MJ_ZIP   string     

ZIP / postal code of the job location.

MJ_CITY   string     

City of the job location.

MJ_LINKED_MJ_ID   integer     

ID of a linked job (self-reference to maintenance_jobs).

MJ_MJ_PREV_STARTED   integer     

ID of a predecessor job that must be started before this job becomes available.

MJ_MJ_PREV_FINISHED   integer     

ID of a predecessor job that must be finished (DONE) before this job becomes available.

MJ_INSERT_PAYMENT   integer     

Payment flag or payment record ID associated with this job.

MJ_EXPEDANT_ID   integer     

ID of the dispatcher (expedient) who dispatched this job.

attendees   object[]     

List of attendees assigned to this job.
MJA_ID   integer     

Unique attendee record ID.

MJA_JOIN_TYPE   string     

How the attendee is linked. Possible values: "JOB", "RECURRENCE_EXCEPTION".

Must be one of:
  • JOB
  • RECURRENCE_EXCEPTION
MJA_OBJ_ID   integer     

Referenced object ID. Points to a job (MJ_ID) when MJA_JOIN_TYPE is JOB, or to a recurrence exception when RECURRENCE_EXCEPTION.

MJA_L_ID   integer     

Operator (login session) ID of the attendee. Null when the attendee is external (not a Mango user).

MJA_EMAIL   string     

E-mail address of the attendee. Always populated regardless of whether the attendee is a Mango user.

MJA_RESPONSE_STATUS   string     

Attendee response to the job invitation. Defaults to "needsAction" until the attendee responds. Possible values: "needsAction", "accepted", "declined", "tentative".

Must be one of:
  • needsAction
  • accepted
  • declined
  • tentative
MJA_RESPONSE_NOTE   string     

Free-text note provided by the attendee along with their response.

Create Process Job

requires authentication 

Creates a new job for a process via maintenance_jobs_job_create stored procedure.
Required fields depend on planning_policy.
Example request:
curl --request POST \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/processes/3/jobs" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"serman_id\": 1,
    \"sg_id\": 16,
    \"ml_order\": 16,
    \"mjt_id\": 16,
    \"mjk_id\": 16,
    \"planning_policy\": \"LONGTIME\",
    \"start_time\": \"2026-03-20 08:00:00\",
    \"stop_time\": \"2026-03-20 10:00:00\",
    \"from_date\": \"2026-03-20\",
    \"from_mtb_id\": 16,
    \"to_date\": \"2026-03-25\",
    \"to_mtb_id\": 16,
    \"points\": 5,
    \"duration\": 60,
    \"recurrence\": \"architecto\",
    \"recurrence_hr\": \"architecto\",
    \"recurrence_data\": \"architecto\",
    \"recurrence_exceptions\": \"architecto\",
    \"linked_mj_id\": 16,
    \"description\": \"Eius et animi quos velit et.\",
    \"note\": \"architecto\",
    \"attendees\": [
        \"architecto\"
    ],
    \"notifications\": [
        \"architecto\"
    ],
    \"private\": 0,
    \"service_active_ids\": \"architecto\",
    \"auto_done\": 1,
    \"auto_done_moment\": \"ON_CREATE\",
    \"auto_done_action\": \"architecto\",
    \"customer_coop\": 1,
    \"insert_payment\": 16,
    \"ga_id\": 16,
    \"ucp_id\": 16,
    \"us_id\": 16,
    \"ua_id\": 16,
    \"street\": \"n\",
    \"house_id\": \"gzmiyv\",
    \"zip\": \"d\",
    \"city\": \"l\",
    \"delay_accepted\": 16,
    \"expedice\": 0,
    \"prev_started\": 16,
    \"prev_finished\": 16,
    \"final_states\": \"architecto\",
    \"planning\": true
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/processes/3/jobs"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "serman_id": 1,
    "sg_id": 16,
    "ml_order": 16,
    "mjt_id": 16,
    "mjk_id": 16,
    "planning_policy": "LONGTIME",
    "start_time": "2026-03-20 08:00:00",
    "stop_time": "2026-03-20 10:00:00",
    "from_date": "2026-03-20",
    "from_mtb_id": 16,
    "to_date": "2026-03-25",
    "to_mtb_id": 16,
    "points": 5,
    "duration": 60,
    "recurrence": "architecto",
    "recurrence_hr": "architecto",
    "recurrence_data": "architecto",
    "recurrence_exceptions": "architecto",
    "linked_mj_id": 16,
    "description": "Eius et animi quos velit et.",
    "note": "architecto",
    "attendees": [
        "architecto"
    ],
    "notifications": [
        "architecto"
    ],
    "private": 0,
    "service_active_ids": "architecto",
    "auto_done": 1,
    "auto_done_moment": "ON_CREATE",
    "auto_done_action": "architecto",
    "customer_coop": 1,
    "insert_payment": 16,
    "ga_id": 16,
    "ucp_id": 16,
    "us_id": 16,
    "ua_id": 16,
    "street": "n",
    "house_id": "gzmiyv",
    "zip": "d",
    "city": "l",
    "delay_accepted": 16,
    "expedice": 0,
    "prev_started": 16,
    "prev_finished": 16,
    "final_states": "architecto",
    "planning": true
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (201):


{
    "data": {
        "MJ_ID": 3424702,
        "MJ_ML_ID": 1460749,
        "MJ_ML_ORDER": null,
        "MJ_PLANNING_POLICY": "TIMEBLOCK",
        "MJ_MJT_ID": "066",
        "MJ_MJK_ID": null,
        "MJ_START": "2026-03-29 23:08:04",
        "MJ_STOP": null,
        "MJ_DURATION": 152,
        "MJ_RECURRENCE": null,
        "MJ_CACHE_RECURRENCE_HR": null,
        "MJ_SERMAN_ID": null,
        "MJ_SG_ID": null,
        "MJ_STATE": "DONE",
        "MJ_DESCRIPTION": "Harum mollitia modi deserunt aut ab provident perspiciatis quo.",
        "MJ_NOTE": null,
        "MJ_PRIVATE": 0,
        "MJ_DONE_TIME": null,
        "MJ_L_ID": "005558",
        "MJ_CREATED": "2026-01-02 12:14:18",
        "MJ_EDITED": "2026-04-15 16:55:11",
        "MJ_REAL_FINISH_TIME": null,
        "MJ_POINTS": null,
        "MJ_TIME_BLOCK_ID": null,
        "MJ_DATE": null,
        "MJ_FROM_DATE": null,
        "MJ_FROM_MTB_ID": null,
        "MJ_TO_DATE": null,
        "MJ_TO_MTB_ID": null,
        "MJ_LINKED_MJ_ID": null,
        "MJ_REAL_START_TIME": null,
        "MJ_AUTO_DONE": 0,
        "MJ_AUTO_DONE_MOMENT": null,
        "MJ_AUTO_DONE_ACTION": null,
        "MJ_CUSTOMER_COOP": 0,
        "MJ_INSERT_PAYMENT": null,
        "MJ_LAST_ACTION": null,
        "MJ_GA_ID": null,
        "MJ_UCP_ID": null,
        "MJ_US_ID": null,
        "MJ_UA_ID": null,
        "MJ_STREET": null,
        "MJ_HOUSE_ID": null,
        "MJ_ZIP": null,
        "MJ_CITY": null,
        "MJ_WORK_TIME": null,
        "MJ_CACHE_START": null,
        "MJ_CACHE_STOP": null,
        "MJ_CACHE_MAX_STOP": null,
        "MJ_EXPEDICE": null,
        "MJ_EXPEDANT_ID": null,
        "MJ_MJ_PREV_STARTED": null,
        "MJ_MJ_PREV_FINISHED": null,
        "MJ_PLANNING": 0,
        "attendees": [
            {
                "MJA_ID": 1668350,
                "MJA_JOIN_TYPE": "JOB",
                "MJA_OBJ_ID": 3424702,
                "MJA_L_ID": null,
                "MJA_EMAIL": "[email protected]",
                "MJA_RESPONSE_STATUS": "declined",
                "MJA_RESPONSE_NOTE": null
            }
        ]
    }
}

Request      

POST api/v3/processes/{process}/jobs

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

process   integer     

The process. Example: 3

Body Parameters

serman_id   integer     

Assigned operator (serviceman) ID Example: 1

sg_id   integer  optional    

Service group ID Example: 16

ml_order   integer  optional    

Example: 16

mjt_id   integer  optional    

Job type ID Example: 16

mjk_id   integer  optional    

Example: 16

planning_policy   string     

Planning policy: LONGTIME, TIMEBLOCK, TIMEBLOCK_RANGE, SEQUENCE Example: LONGTIME

start_time   string  optional    

Start time (required for LONGTIME) Example: 2026-03-20 08:00:00

stop_time   string  optional    

Stop time (required for LONGTIME) Example: 2026-03-20 10:00:00

from_date   string  optional    

From date (required for TIMEBLOCK, TIMEBLOCK_RANGE) Example: 2026-03-20

from_mtb_id   integer  optional    

Example: 16

to_date   string  optional    

To date (required for TIMEBLOCK_RANGE) Example: 2026-03-25

to_mtb_id   integer  optional    

Example: 16

points   integer  optional    

Points (required for TIMEBLOCK) Example: 5

duration   integer  optional    

Duration in minutes (required for SEQUENCE) Example: 60

recurrence   string  optional    

Example: architecto

recurrence_hr   string  optional    

Example: architecto

recurrence_data   string  optional    

Example: architecto

recurrence_exceptions   string  optional    

Example: architecto

linked_mj_id   integer  optional    

Example: 16

description   string  optional    

Job description Example: Eius et animi quos velit et.

note   string  optional    

Job note Example: architecto

attendees   string[]  optional    

Attendee emails

notifications   string[]  optional    

Notification recipients

private   integer  optional    

Private flag (0 or 1) Example: 0

service_active_ids   string  optional    

Example: architecto

auto_done   integer  optional    

Example: 1

Must be one of:
  • 0
  • 1
auto_done_moment   string  optional    

Example: ON_CREATE

Must be one of:
  • ON_START
  • ON_CREATE
auto_done_action   string  optional    

Example: architecto

customer_coop   integer  optional    

Example: 1

Must be one of:
  • 0
  • 1
insert_payment   integer  optional    

Example: 16

ga_id   integer  optional    

Example: 16

ucp_id   integer  optional    

Example: 16

us_id   integer  optional    

Example: 16

ua_id   integer  optional    

Example: 16

street   string  optional    

Must not be greater than 255 characters. Example: n

house_id   string  optional    

Must not be greater than 10 characters. Example: gzmiyv

zip   string  optional    

Must not be greater than 5 characters. Example: d

city   string  optional    

Must not be greater than 255 characters. Example: l

delay_accepted   integer  optional    

Example: 16

expedice   integer  optional    

Example: 0

Must be one of:
  • 0
  • 1
prev_started   integer  optional    

Example: 16

prev_finished   integer  optional    

Example: 16

final_states   string  optional    

Example: architecto

planning   boolean  optional    

Example: true

Response

Response Fields

data   object     
MJ_ID   integer     

Unique job ID.

MJ_ML_ID   integer     

Parent process (maintenance list) ID. References maintenance_list.

MJ_ML_ORDER   integer     

Order of the job within the process.

MJ_PLANNING_POLICY   string     

Scheduling policy for the job. Determines which date/time fields are relevant.

Must be one of:
  • LONGTIME
  • TIMEBLOCK
  • TIMEBLOCK_RANGE
  • SEQUENCE
  • NONE
MJ_MJT_ID   integer     

Job type ID. References maintenance_job_types.

MJ_MJK_ID   integer     

Job kind (category) ID. References maintenance_job_kinds.

MJ_STATE   string     

Current state of the job.

Must be one of:
  • PLANNED
  • DONE
  • CANCELED
MJ_START   string     

Planned start date and time.

MJ_STOP   string     

Planned end date and time.

MJ_DURATION   integer     

Expected duration of the job in minutes.

MJ_FROM_DATE   string     

Start date for time-block or range scheduling.

MJ_FROM_MTB_ID   integer     

Start time-block ID. References maintenance_time_block.

MJ_TO_DATE   string     

End date for time-block range scheduling.

MJ_TO_MTB_ID   integer     

End time-block ID. References maintenance_time_block.

MJ_DATE   string     

Scheduled date for the job.

MJ_TIME_BLOCK_ID   integer     

Assigned time-block ID. References maintenance_time_block.

MJ_POINTS   integer     

Number of capacity points consumed by this job.

MJ_RECURRENCE   string     

Recurrence rule definition string.

MJ_CACHE_RECURRENCE_HR   string     

Cached human-readable representation of the recurrence rule.

MJ_SERMAN_ID   integer     

Assigned resource (serviceman) login ID. References logins.

MJ_SG_ID   integer     

Service group ID. References serman_groups.

MJ_L_ID   integer     

Login ID of the user who created or owns this job. References logins.

MJ_DESCRIPTION   string     

Task description / name of the job.

MJ_NOTE   string     

Note or progress log for the job.

MJ_PRIVATE   integer     

Whether the job is visible only to its assigned resource in the calendar. 1 = private, 0 = public.

MJ_CUSTOMER_COOP   integer     

Whether customer presence is required while processing the job. 1 = yes, 0 = no.

MJ_PLANNING   integer     

Whether this job is used only for planning/scheduling other jobs. 1 = planning-only, 0 = regular job.

MJ_EXPEDICE   integer     

Whether expedition (dispatch) is enabled for this job. 1 = yes, 0 = no.

MJ_AUTO_DONE   integer     

Whether the job should be automatically marked as done. 1 = yes, 0 = no.

MJ_AUTO_DONE_MOMENT   string     

When to trigger auto-done.

Must be one of:
  • ON_CREATE
  • ON_START
MJ_AUTO_DONE_ACTION   string     

Action identifier to execute when auto-done is triggered.

MJ_CREATED   string     

Timestamp when the job was created.

MJ_EDITED   string     

Timestamp when the job was last edited.

MJ_DONE_TIME   string     

Timestamp when the job was marked as done.

MJ_REAL_START_TIME   string     

Actual start time recorded by the assignee.

MJ_REAL_FINISH_TIME   string     

Actual finish date recorded by the assignee.

MJ_WORK_TIME   integer     

Actual work time spent on the job in minutes.

MJ_LAST_ACTION   string     

Identifier of the last action performed on this job.

MJ_CACHE_START   string     

Cached computed start datetime (resolved from scheduling rules).

MJ_CACHE_STOP   string     

Cached computed end datetime (resolved from scheduling rules).

MJ_CACHE_MAX_STOP   string     

Cached maximum possible end datetime.

MJ_GA_ID   integer     

Group address ID. References groups_address.

MJ_UCP_ID   integer     

UIR city part ID. References uir_city_parts.

MJ_US_ID   integer     

UIR street ID. References uir_streets.

MJ_UA_ID   integer     

UIR address ID. References uir_addresses.

MJ_STREET   string     

Street name of the job location.

MJ_HOUSE_ID   string     

House number at the job location.

MJ_ZIP   string     

ZIP / postal code of the job location.

MJ_CITY   string     

City of the job location.

MJ_LINKED_MJ_ID   integer     

ID of a linked job (self-reference to maintenance_jobs).

MJ_MJ_PREV_STARTED   integer     

ID of a predecessor job that must be started before this job becomes available.

MJ_MJ_PREV_FINISHED   integer     

ID of a predecessor job that must be finished (DONE) before this job becomes available.

MJ_INSERT_PAYMENT   integer     

Payment flag or payment record ID associated with this job.

MJ_EXPEDANT_ID   integer     

ID of the dispatcher (expedient) who dispatched this job.

attendees   object[]     

List of attendees assigned to this job.
MJA_ID   integer     

Unique attendee record ID.

MJA_JOIN_TYPE   string     

How the attendee is linked. Possible values: "JOB", "RECURRENCE_EXCEPTION".

Must be one of:
  • JOB
  • RECURRENCE_EXCEPTION
MJA_OBJ_ID   integer     

Referenced object ID. Points to a job (MJ_ID) when MJA_JOIN_TYPE is JOB, or to a recurrence exception when RECURRENCE_EXCEPTION.

MJA_L_ID   integer     

Operator (login session) ID of the attendee. Null when the attendee is external (not a Mango user).

MJA_EMAIL   string     

E-mail address of the attendee. Always populated regardless of whether the attendee is a Mango user.

MJA_RESPONSE_STATUS   string     

Attendee response to the job invitation. Defaults to "needsAction" until the attendee responds. Possible values: "needsAction", "accepted", "declined", "tentative".

Must be one of:
  • needsAction
  • accepted
  • declined
  • tentative
MJA_RESPONSE_NOTE   string     

Free-text note provided by the attendee along with their response.

Update Process Job

requires authentication 

Updates an existing job via maintenance_jobs_job_edit stored procedure.
State changes (DONE, CANCELLED) are performed via the state parameter.
Example request:
curl --request PUT \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/processes/3/jobs/architecto" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"l_id\": 16,
    \"sg_id\": 16,
    \"planning_policy\": \"architecto\",
    \"start_time\": \"2026-03-20 08:00:00\",
    \"stop_time\": \"2026-03-20 10:00:00\",
    \"from_date\": \"2026-03-20\",
    \"from_mtb_id\": 16,
    \"to_date\": \"2026-03-25\",
    \"to_mtb_id\": 16,
    \"points\": 16,
    \"recurrence\": \"architecto\",
    \"recurrence_hr\": \"architecto\",
    \"recurrence_data\": \"architecto\",
    \"recurrence_exceptions\": \"architecto\",
    \"description\": \"Eius et animi quos velit et.\",
    \"note\": \"architecto\",
    \"attendees\": [
        \"architecto\"
    ],
    \"notifications\": [
        \"architecto\"
    ],
    \"private\": 0,
    \"state\": \"DONE\",
    \"action\": \"architecto\",
    \"task_note\": \"architecto\",
    \"real_finish_time\": \"architecto\",
    \"ga_id\": 16,
    \"ucp_id\": 16,
    \"us_id\": 16,
    \"ua_id\": 16,
    \"street\": \"n\",
    \"house_id\": \"gzmiyv\",
    \"zip\": \"d\",
    \"city\": \"l\",
    \"work_time\": 16,
    \"ml_order\": 16,
    \"duration\": 16,
    \"expedice\": 0,
    \"prev_started\": 16,
    \"prev_finished\": 16,
    \"final_states\": \"architecto\"
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/processes/3/jobs/architecto"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "l_id": 16,
    "sg_id": 16,
    "planning_policy": "architecto",
    "start_time": "2026-03-20 08:00:00",
    "stop_time": "2026-03-20 10:00:00",
    "from_date": "2026-03-20",
    "from_mtb_id": 16,
    "to_date": "2026-03-25",
    "to_mtb_id": 16,
    "points": 16,
    "recurrence": "architecto",
    "recurrence_hr": "architecto",
    "recurrence_data": "architecto",
    "recurrence_exceptions": "architecto",
    "description": "Eius et animi quos velit et.",
    "note": "architecto",
    "attendees": [
        "architecto"
    ],
    "notifications": [
        "architecto"
    ],
    "private": 0,
    "state": "DONE",
    "action": "architecto",
    "task_note": "architecto",
    "real_finish_time": "architecto",
    "ga_id": 16,
    "ucp_id": 16,
    "us_id": 16,
    "ua_id": 16,
    "street": "n",
    "house_id": "gzmiyv",
    "zip": "d",
    "city": "l",
    "work_time": 16,
    "ml_order": 16,
    "duration": 16,
    "expedice": 0,
    "prev_started": 16,
    "prev_finished": 16,
    "final_states": "architecto"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "data": {
        "MJ_ID": 3424703,
        "MJ_ML_ID": 1460750,
        "MJ_ML_ORDER": null,
        "MJ_PLANNING_POLICY": "TIMEBLOCK",
        "MJ_MJT_ID": "066",
        "MJ_MJK_ID": null,
        "MJ_START": "2026-03-29 23:08:04",
        "MJ_STOP": null,
        "MJ_DURATION": 152,
        "MJ_RECURRENCE": null,
        "MJ_CACHE_RECURRENCE_HR": null,
        "MJ_SERMAN_ID": null,
        "MJ_SG_ID": null,
        "MJ_STATE": "DONE",
        "MJ_DESCRIPTION": "Harum mollitia modi deserunt aut ab provident perspiciatis quo.",
        "MJ_NOTE": null,
        "MJ_PRIVATE": 0,
        "MJ_DONE_TIME": null,
        "MJ_L_ID": "005559",
        "MJ_CREATED": "2026-01-02 12:14:18",
        "MJ_EDITED": "2026-04-15 16:55:11",
        "MJ_REAL_FINISH_TIME": null,
        "MJ_POINTS": null,
        "MJ_TIME_BLOCK_ID": null,
        "MJ_DATE": null,
        "MJ_FROM_DATE": null,
        "MJ_FROM_MTB_ID": null,
        "MJ_TO_DATE": null,
        "MJ_TO_MTB_ID": null,
        "MJ_LINKED_MJ_ID": null,
        "MJ_REAL_START_TIME": null,
        "MJ_AUTO_DONE": 0,
        "MJ_AUTO_DONE_MOMENT": null,
        "MJ_AUTO_DONE_ACTION": null,
        "MJ_CUSTOMER_COOP": 0,
        "MJ_INSERT_PAYMENT": null,
        "MJ_LAST_ACTION": null,
        "MJ_GA_ID": null,
        "MJ_UCP_ID": null,
        "MJ_US_ID": null,
        "MJ_UA_ID": null,
        "MJ_STREET": null,
        "MJ_HOUSE_ID": null,
        "MJ_ZIP": null,
        "MJ_CITY": null,
        "MJ_WORK_TIME": null,
        "MJ_CACHE_START": null,
        "MJ_CACHE_STOP": null,
        "MJ_CACHE_MAX_STOP": null,
        "MJ_EXPEDICE": null,
        "MJ_EXPEDANT_ID": null,
        "MJ_MJ_PREV_STARTED": null,
        "MJ_MJ_PREV_FINISHED": null,
        "MJ_PLANNING": 0,
        "attendees": [
            {
                "MJA_ID": 1668351,
                "MJA_JOIN_TYPE": "JOB",
                "MJA_OBJ_ID": 3424703,
                "MJA_L_ID": null,
                "MJA_EMAIL": "[email protected]",
                "MJA_RESPONSE_STATUS": "accepted",
                "MJA_RESPONSE_NOTE": "Tempora nulla in unde rerum voluptas ab maxime qui."
            }
        ]
    }
}

Request      

PUT api/v3/processes/{process}/jobs/{job}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

process   integer     

The process. Example: 3

job   string     

The job. Example: architecto

Body Parameters

l_id   integer  optional    

Example: 16

sg_id   integer  optional    

Example: 16

planning_policy   string  optional    

Planning policy: LONGTIME, TIMEBLOCK, TIMEBLOCK_RANGE, SEQUENCE Example: architecto

start_time   string  optional    

Start datetime Example: 2026-03-20 08:00:00

stop_time   string  optional    

Stop datetime Example: 2026-03-20 10:00:00

from_date   string  optional    

From date Example: 2026-03-20

from_mtb_id   integer  optional    

Example: 16

to_date   string  optional    

To date Example: 2026-03-25

to_mtb_id   integer  optional    

Example: 16

points   integer  optional    

Example: 16

recurrence   string  optional    

Example: architecto

recurrence_hr   string  optional    

Example: architecto

recurrence_data   string  optional    

Example: architecto

recurrence_exceptions   string  optional    

Example: architecto

description   string  optional    

Job description Example: Eius et animi quos velit et.

note   string  optional    

Job note Example: architecto

attendees   string[]  optional    
notifications   string[]  optional    
private   integer  optional    

Example: 0

Must be one of:
  • 0
  • 1
state   string  optional    

New job state: PLANNED, DONE, CANCELLED Example: DONE

action   string  optional    

Action to perform (edit, done, done_finish, cancel, transfer, reschedule) Example: architecto

task_note   string  optional    

Note appended to the process Example: architecto

real_finish_time   string  optional    

Actual finish time Example: architecto

ga_id   integer  optional    

Example: 16

ucp_id   integer  optional    

Example: 16

us_id   integer  optional    

Example: 16

ua_id   integer  optional    

Example: 16

street   string  optional    

Must not be greater than 255 characters. Example: n

house_id   string  optional    

Must not be greater than 10 characters. Example: gzmiyv

zip   string  optional    

Must not be greater than 5 characters. Example: d

city   string  optional    

Must not be greater than 255 characters. Example: l

work_time   integer  optional    

Work time in minutes Example: 16

ml_order   integer  optional    

Example: 16

duration   integer  optional    

Example: 16

expedice   integer  optional    

Example: 0

Must be one of:
  • 0
  • 1
prev_started   integer  optional    

Example: 16

prev_finished   integer  optional    

Example: 16

final_states   string  optional    

Example: architecto

Response

Response Fields

data   object     
MJ_ID   integer     

Unique job ID.

MJ_ML_ID   integer     

Parent process (maintenance list) ID. References maintenance_list.

MJ_ML_ORDER   integer     

Order of the job within the process.

MJ_PLANNING_POLICY   string     

Scheduling policy for the job. Determines which date/time fields are relevant.

Must be one of:
  • LONGTIME
  • TIMEBLOCK
  • TIMEBLOCK_RANGE
  • SEQUENCE
  • NONE
MJ_MJT_ID   integer     

Job type ID. References maintenance_job_types.

MJ_MJK_ID   integer     

Job kind (category) ID. References maintenance_job_kinds.

MJ_STATE   string     

Current state of the job.

Must be one of:
  • PLANNED
  • DONE
  • CANCELED
MJ_START   string     

Planned start date and time.

MJ_STOP   string     

Planned end date and time.

MJ_DURATION   integer     

Expected duration of the job in minutes.

MJ_FROM_DATE   string     

Start date for time-block or range scheduling.

MJ_FROM_MTB_ID   integer     

Start time-block ID. References maintenance_time_block.

MJ_TO_DATE   string     

End date for time-block range scheduling.

MJ_TO_MTB_ID   integer     

End time-block ID. References maintenance_time_block.

MJ_DATE   string     

Scheduled date for the job.

MJ_TIME_BLOCK_ID   integer     

Assigned time-block ID. References maintenance_time_block.

MJ_POINTS   integer     

Number of capacity points consumed by this job.

MJ_RECURRENCE   string     

Recurrence rule definition string.

MJ_CACHE_RECURRENCE_HR   string     

Cached human-readable representation of the recurrence rule.

MJ_SERMAN_ID   integer     

Assigned resource (serviceman) login ID. References logins.

MJ_SG_ID   integer     

Service group ID. References serman_groups.

MJ_L_ID   integer     

Login ID of the user who created or owns this job. References logins.

MJ_DESCRIPTION   string     

Task description / name of the job.

MJ_NOTE   string     

Note or progress log for the job.

MJ_PRIVATE   integer     

Whether the job is visible only to its assigned resource in the calendar. 1 = private, 0 = public.

MJ_CUSTOMER_COOP   integer     

Whether customer presence is required while processing the job. 1 = yes, 0 = no.

MJ_PLANNING   integer     

Whether this job is used only for planning/scheduling other jobs. 1 = planning-only, 0 = regular job.

MJ_EXPEDICE   integer     

Whether expedition (dispatch) is enabled for this job. 1 = yes, 0 = no.

MJ_AUTO_DONE   integer     

Whether the job should be automatically marked as done. 1 = yes, 0 = no.

MJ_AUTO_DONE_MOMENT   string     

When to trigger auto-done.

Must be one of:
  • ON_CREATE
  • ON_START
MJ_AUTO_DONE_ACTION   string     

Action identifier to execute when auto-done is triggered.

MJ_CREATED   string     

Timestamp when the job was created.

MJ_EDITED   string     

Timestamp when the job was last edited.

MJ_DONE_TIME   string     

Timestamp when the job was marked as done.

MJ_REAL_START_TIME   string     

Actual start time recorded by the assignee.

MJ_REAL_FINISH_TIME   string     

Actual finish date recorded by the assignee.

MJ_WORK_TIME   integer     

Actual work time spent on the job in minutes.

MJ_LAST_ACTION   string     

Identifier of the last action performed on this job.

MJ_CACHE_START   string     

Cached computed start datetime (resolved from scheduling rules).

MJ_CACHE_STOP   string     

Cached computed end datetime (resolved from scheduling rules).

MJ_CACHE_MAX_STOP   string     

Cached maximum possible end datetime.

MJ_GA_ID   integer     

Group address ID. References groups_address.

MJ_UCP_ID   integer     

UIR city part ID. References uir_city_parts.

MJ_US_ID   integer     

UIR street ID. References uir_streets.

MJ_UA_ID   integer     

UIR address ID. References uir_addresses.

MJ_STREET   string     

Street name of the job location.

MJ_HOUSE_ID   string     

House number at the job location.

MJ_ZIP   string     

ZIP / postal code of the job location.

MJ_CITY   string     

City of the job location.

MJ_LINKED_MJ_ID   integer     

ID of a linked job (self-reference to maintenance_jobs).

MJ_MJ_PREV_STARTED   integer     

ID of a predecessor job that must be started before this job becomes available.

MJ_MJ_PREV_FINISHED   integer     

ID of a predecessor job that must be finished (DONE) before this job becomes available.

MJ_INSERT_PAYMENT   integer     

Payment flag or payment record ID associated with this job.

MJ_EXPEDANT_ID   integer     

ID of the dispatcher (expedient) who dispatched this job.

attendees   object[]     

List of attendees assigned to this job.
MJA_ID   integer     

Unique attendee record ID.

MJA_JOIN_TYPE   string     

How the attendee is linked. Possible values: "JOB", "RECURRENCE_EXCEPTION".

Must be one of:
  • JOB
  • RECURRENCE_EXCEPTION
MJA_OBJ_ID   integer     

Referenced object ID. Points to a job (MJ_ID) when MJA_JOIN_TYPE is JOB, or to a recurrence exception when RECURRENCE_EXCEPTION.

MJA_L_ID   integer     

Operator (login session) ID of the attendee. Null when the attendee is external (not a Mango user).

MJA_EMAIL   string     

E-mail address of the attendee. Always populated regardless of whether the attendee is a Mango user.

MJA_RESPONSE_STATUS   string     

Attendee response to the job invitation. Defaults to "needsAction" until the attendee responds. Possible values: "needsAction", "accepted", "declined", "tentative".

Must be one of:
  • needsAction
  • accepted
  • declined
  • tentative
MJA_RESPONSE_NOTE   string     

Free-text note provided by the attendee along with their response.

Processes

List Processes

requires authentication 

Returns a paginated list of maintenance processes.
Rights are checked via SQL function (maintenance_right_check_full_data).
Add ?time_tracking=true to include time tracking computed attributes.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/processes?ids=1%2C2%2C3&cts=1%2C2%2C3&type=5&customer_id=100&in_progress=true&substate=10%2C20&created_from=2024-01-01&created_to=2024-12-31" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/processes"
);

const params = {
    "ids": "1,2,3",
    "cts": "1,2,3",
    "type": "5",
    "customer_id": "100",
    "in_progress": "true",
    "substate": "10,20",
    "created_from": "2024-01-01",
    "created_to": "2024-12-31",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "ID": 1460742,
            "ML_SG_ID": null,
            "USER_ID": null,
            "STATE_ID": "03",
            "ML_MSS_ID": null,
            "ML_FINISH_MSS_ID": null,
            "SERMAN_ID": null,
            "CREATE_ID": "977",
            "ML_MTT_ID": "0000000081",
            "ML_NODEAVAIL_SGD_ID": null,
            "ML_MTT_STARTING_CODE": null,
            "ML_MTT_CODE": null,
            "NAME": null,
            "ML_CACHE_FULLNAME": null,
            "CREATION_TIME": "2026-02-08 13:47:27",
            "FINISH_TIME": null,
            "SOLVING_TIME": null,
            "PRE_FINISH_DATE": null,
            "CT": "79",
            "ML_HPC_ID": null,
            "ML_PRIORITY": "HIGH",
            "ML_N_ID": null,
            "ML_SA_ID": null,
            "ML_O_ID": null,
            "ML_DOCUMENT_TYPE": null,
            "ML_EXTERN_SOLVED": 0,
            "ML_FINISH_MJ_ID": null,
            "ML_REQUIRE_DOC_SCAN": 0,
            "ML_INSERT_PAYMENT": null,
            "ML_FINISH_NOTE": null,
            "ML_GA_ID": null,
            "ML_UCP_ID": null,
            "ML_PREV_ML_ID": null,
            "ML_OI_ID": null,
            "ML_US_ID": null,
            "ML_UA_ID": null,
            "ML_STREET": null,
            "ML_HOUSE_ID": null,
            "ML_ZIP": null,
            "ML_CITY": null,
            "ML_USER_CONTACT": null,
            "ML_ML_ID": null,
            "ML_DR_ID": null,
            "ML_DESC": null,
            "ML_DELAY_ACCEPTED": null,
            "ML_PLANNING_STRATEGY": null,
            "ML_CACHE_ADDRESS": "544 Aglae Ridge Apt. 067, Lefflerhaven",
            "ML_CONFIG_DATE": "2026-02-23 07:51:37",
            "ML_BULK": 0,
            "ML_WAKE_TIME": null,
            "ML_SLA_ID": null,
            "ML_SLA_ACT": "",
            "ML_SLA_TIME": null,
            "ML_P_ID": null,
            "ML_UC_ID": null,
            "ML_CACHE_MTT_UNIQUE_ID": 25,
            "ML_CACHE_MSS_UNIQUE_ID": 50,
            "ML_CACHE_FULLNAME_SC": null,
            "params": [
                {
                    "MP_ID": 14753306,
                    "MP_ML_ID": 1460742,
                    "MP_NAME": "JOB_START_TIME",
                    "MP_VALUE": "Voluptatem laboriosam praesentium quis adipisci.",
                    "MP_INDEX": null,
                    "MP_VALUE_UTF8": null,
                    "MP_UPDATED": "2026-03-18 04:10:27",
                    "MP_L_ID": null
                }
            ],
            "attachments": [
                {
                    "FA_ID": 539222,
                    "FA_DOC_ID": 1460742,
                    "FA_DOC_TYPE": "maintenance",
                    "FA_NAME": "deleniti distinctio eum",
                    "FA_DESC": "Id aut libero aliquam veniam.",
                    "FA_FILE_TYPE": 2,
                    "FA_FILE_SIZE": null,
                    "FA_FILE_NAME": "noqitp.pdf",
                    "FA_DELETED": null,
                    "FA_CREATED": "2026-04-11 04:23:29",
                    "FA_CREATE_L_ID": null,
                    "FA_MODIFIED": null,
                    "FA_MODIFY_L_ID": null
                }
            ]
        },
        {
            "ID": 1460743,
            "ML_SG_ID": null,
            "USER_ID": null,
            "STATE_ID": "05",
            "ML_MSS_ID": null,
            "ML_FINISH_MSS_ID": null,
            "SERMAN_ID": null,
            "CREATE_ID": "785",
            "ML_MTT_ID": "0000000080",
            "ML_NODEAVAIL_SGD_ID": null,
            "ML_MTT_STARTING_CODE": null,
            "ML_MTT_CODE": null,
            "NAME": null,
            "ML_CACHE_FULLNAME": null,
            "CREATION_TIME": "2026-01-06 18:45:45",
            "FINISH_TIME": null,
            "SOLVING_TIME": null,
            "PRE_FINISH_DATE": null,
            "CT": "16",
            "ML_HPC_ID": null,
            "ML_PRIORITY": "MEDIUM",
            "ML_N_ID": null,
            "ML_SA_ID": null,
            "ML_O_ID": null,
            "ML_DOCUMENT_TYPE": null,
            "ML_EXTERN_SOLVED": 0,
            "ML_FINISH_MJ_ID": null,
            "ML_REQUIRE_DOC_SCAN": 0,
            "ML_INSERT_PAYMENT": null,
            "ML_FINISH_NOTE": null,
            "ML_GA_ID": null,
            "ML_UCP_ID": null,
            "ML_PREV_ML_ID": null,
            "ML_OI_ID": null,
            "ML_US_ID": null,
            "ML_UA_ID": null,
            "ML_STREET": null,
            "ML_HOUSE_ID": null,
            "ML_ZIP": null,
            "ML_CITY": null,
            "ML_USER_CONTACT": null,
            "ML_ML_ID": null,
            "ML_DR_ID": null,
            "ML_DESC": null,
            "ML_DELAY_ACCEPTED": null,
            "ML_PLANNING_STRATEGY": null,
            "ML_CACHE_ADDRESS": "752 Brennon Tunnel, Port Roxanneview",
            "ML_CONFIG_DATE": "2026-03-21 15:02:10",
            "ML_BULK": 0,
            "ML_WAKE_TIME": null,
            "ML_SLA_ID": null,
            "ML_SLA_ACT": "",
            "ML_SLA_TIME": null,
            "ML_P_ID": null,
            "ML_UC_ID": null,
            "ML_CACHE_MTT_UNIQUE_ID": 98,
            "ML_CACHE_MSS_UNIQUE_ID": 60,
            "ML_CACHE_FULLNAME_SC": null,
            "params": [
                {
                    "MP_ID": 14753307,
                    "MP_ML_ID": 1460743,
                    "MP_NAME": "TERM",
                    "MP_VALUE": "Assumenda et tenetur ab reiciendis quia.",
                    "MP_INDEX": null,
                    "MP_VALUE_UTF8": null,
                    "MP_UPDATED": "2026-04-05 15:41:57",
                    "MP_L_ID": null
                }
            ],
            "attachments": [
                {
                    "FA_ID": 539223,
                    "FA_DOC_ID": 1460743,
                    "FA_DOC_TYPE": "maintenance",
                    "FA_NAME": "ducimus corrupti et",
                    "FA_DESC": "Quia maiores assumenda odit.",
                    "FA_FILE_TYPE": null,
                    "FA_FILE_SIZE": 2227,
                    "FA_FILE_NAME": "tvnbob.pdf",
                    "FA_DELETED": null,
                    "FA_CREATED": "2026-02-08 19:46:26",
                    "FA_CREATE_L_ID": null,
                    "FA_MODIFIED": null,
                    "FA_MODIFY_L_ID": null
                }
            ]
        }
    ]
}

Request      

GET api/v3/processes

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

ids   string  optional    

Filter by comma-separated IDs Example: 1,2,3

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Example: 1,2,3

type   string  optional    

Filter by task type ID(s), comma-separated Example: 5

customer_id   integer  optional    

Filter by customer user ID Example: 100

in_progress   string  optional    

Filter by in-progress master state (true = STATE_ID=2) Example: true

substate   string  optional    

Filter by substate ID(s), comma-separated Example: 10,20

created_from   string  optional    

Filter processes created from this date (inclusive) Example: 2024-01-01

created_to   string  optional    

Filter processes created to this date (inclusive) Example: 2024-12-31

Response

Response Fields

data   object     
ID   integer     

Unique process identifier (primary key).

NAME   string     

Process name.

ML_DESC   string     

Detailed process description.

ML_CACHE_FULLNAME   string     

Cached display name resolved from process type configuration.

ML_CACHE_FULLNAME_SC   string     

Cached display name optimized for search (stripped/normalized).

ML_MTT_ID   integer     

Process type ID (references maintenance_task_types).

STATE_ID   integer     

Master state ID (references maintenance_states). 1 = reported, 2 = in progress, 3 = resolved, 4 = confirmed.

ML_MSS_ID   integer     

Current substate ID (references maintenance_substates).

ML_FINISH_MSS_ID   integer     

Substate before finish. Used in workflow to determine the substate prior to task completion.

ML_PRIORITY   string     

Process priority.

Must be one of:
  • LOW
  • MEDIUM
  • HIGH
  • CRITICAL
ML_PLANNING_STRATEGY   string     

Planning strategy code for auto-planned jobs. null = unknown (uses default), 'none' = selects all with MSC_STRATEGY_CODE IS NULL.

ML_CACHE_MTT_UNIQUE_ID   integer     

Cached resolved process type unique ID (from maintenance_task_types).

ML_CACHE_MSS_UNIQUE_ID   integer     

Cached resolved substate unique ID (from maintenance_substates).

USER_ID   integer     

Customer ID (references users).

CREATE_ID   integer     

Creator operator ID (references logins).

SERMAN_ID   integer     

Assigned resource/solver ID (references logins).

ML_SG_ID   integer     

Resource group ID (references serman_groups).

ML_UC_ID   integer     

Customer contact ID (references users_contacts).

ML_USER_CONTACT   string     

Customer contact detail (phone number, email, etc.).

CREATION_TIME   string     

Process creation datetime.

FINISH_TIME   string     

Process completion datetime.

ML_CONFIG_DATE   string     

Configuration snapshot datetime. Determines which process type configuration version applies.

ML_WAKE_TIME   string     

Suspended-to datetime. When set, the process is suspended until this time.

ML_SLA_ID   integer     

SLA definition ID (references code_list).

ML_SLA_ACT   string     

Active SLA flags. Set values: 'EXPIRE', 'WARNING'. Empty string when no SLA issues.

ML_SLA_TIME   string     

Datetime of the first expiring unhandled SLA point. Updated by the maintenance_task_sla_update procedure.

ML_CACHE_ADDRESS   string     

Cached address of the activity location.

ML_P_ID   integer     

Premise ID (references premises).

ML_ML_ID   integer     

Parent/bulk process ID (references maintenance_list). Used for process hierarchy.

ML_O_ID   integer     

Order ID.

ML_BULK   integer     

Bulk process flag. 1 = enables assigning other processes underneath this one.

ML_HPC_ID   integer     

Helpdesk phone call ID that initiated this process.

CT   integer     

Company/tenant identifier (multi-tenant discriminator).

ML_NODEAVAIL_SGD_ID   integer     

Deprecated. Process group (technology) ID.

ML_MTT_STARTING_CODE   string     

Deprecated. Initial code of the process type.

ML_MTT_CODE   string     

Deprecated. Finish code of the process type.

SOLVING_TIME   string     

Deprecated. Start-of-solving datetime.

PRE_FINISH_DATE   string     

Deprecated. Estimated end datetime.

ML_N_ID   integer     

Deprecated. Node/device ID.

ML_SA_ID   integer     

Deprecated. Service assignment ID.

ML_DOCUMENT_TYPE   integer     

Deprecated. Document type that initiated this process (references code_list).

ML_EXTERN_SOLVED   integer     

Deprecated. Externally solved flag.

ML_FINISH_MJ_ID   integer     

Deprecated. Finishing job ID.

ML_REQUIRE_DOC_SCAN   integer     

Deprecated. Flag requiring document scan on process completion.

ML_INSERT_PAYMENT   integer     

Deprecated. Allow payment insertion on done job. null = not allowed, 0 = allow without pre-fill, value = pre-fill amount.

ML_FINISH_NOTE   string     

Deprecated. Closing note.

ML_GA_ID   integer     

Deprecated. Geographic area ID.

ML_UCP_ID   integer     

Deprecated. UIR city part ID.

ML_PREV_ML_ID   integer     

Deprecated. Previous/past process ID.

ML_OI_ID   integer     

Deprecated. Order item ID.

ML_US_ID   integer     

Deprecated. UIR street ID.

ML_UA_ID   integer     

Deprecated. UIR address ID.

ML_STREET   string     

Deprecated. Street address text.

ML_HOUSE_ID   string     

Deprecated. House number.

ML_ZIP   string     

Deprecated. Postal code (PSČ).

ML_CITY   string     

Deprecated. City name.

ML_DR_ID   integer     

Deprecated. Debt recovery process ID.

ML_DELAY_ACCEPTED   integer     

Deprecated. Customer requested and accepted delayed resolution.

planned_minutes   number     

Total planned work time in minutes. Present only when ?time_tracking=true.

spent_minutes   number     

Total spent (logged) work time in minutes. Present only when ?time_tracking=true.

actual_minutes   number     

Actual real work volume in minutes. Present only when ?time_tracking=true.

discrepancy_percent   number     

Percentage discrepancy between actual/spent and planned time. 0 when no planned time. Present only when ?time_tracking=true.

params   object[]     

Process parameters — collection of key-value pairs associated with this process.
MP_ID   integer     

Unique process parameter ID (primary key).

MP_ML_ID   integer     

Parent process ID. See GET /v3/processes/{id}.

MP_NAME   string     

Parameter name. Identifies the parameter type, e.g. 'TYPE', 'PROCESS_DESCRIPTION', 'JOB_START_TIME', 'SERVICES', 'TERM', 'SALESMAN'. Defined in maintenance_params_def.

MP_VALUE   string     

Parameter value (legacy encoding).

MP_VALUE_UTF8   string     

Parameter value in UTF-8 encoding. Used when the value contains characters outside the legacy charset.

MP_INDEX   integer     

Index for multi-valued (table/indexed) parameters. Null for single-value parameters. Zero-based ordering within the same MP_NAME.

MP_UPDATED   string     

Timestamp of the last update to this parameter (YYYY-MM-DD HH:MM:SS).

MP_L_ID   integer     

Operator (login session) ID that last modified this parameter.

attachments   object[]     

File attachments associated with this process.
FA_ID   integer     

Unique attachment identifier (primary key).

FA_DOC_ID   integer     

Parent process ID. See GET /v3/processes/{id}.

FA_DOC_TYPE   string     

Document type discriminator. For process attachments, always 'maintenance'.

FA_NAME   string     

Attachment display name.

FA_DESC   string     

Attachment description.

FA_FILE_NAME   string     

Original file name used for download.

FA_FILE_TYPE   integer     

File type ID (references a code list entry). E.g. 0 = unknown, 1 = pdf, 2 = jpg.

FA_FILE_SIZE   integer     

File size in kilobytes.

FA_DELETED   integer     

Soft-delete flag. null/0 = active, 1 = deleted.

FA_CREATED   string     

Creation datetime (YYYY-MM-DD HH:MM:SS).

FA_CREATE_L_ID   integer     

Creator operator (login session) ID.

FA_MODIFIED   string     

Last modification datetime (YYYY-MM-DD HH:MM:SS).

FA_MODIFY_L_ID   integer     

Last modifier operator (login session) ID.

Create Process

requires authentication 

Creates a new maintenance process via maintenance_task_create stored procedure.
Example request:
curl --request POST \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/processes" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"type_id\": 5,
    \"name\": \"Network installation\",
    \"priority\": \"MEDIUM\",
    \"description\": \"Eius et animi quos velit et.\",
    \"customer_id\": 100,
    \"creation_time\": \"2024-01-15 10:00:00\",
    \"ml_desc\": \"architecto\",
    \"premise_id\": 16,
    \"uc_id\": 16,
    \"user_contact\": \"architecto\",
    \"bulk\": 16,
    \"sla_id\": 16,
    \"group_task\": 16,
    \"params\": [
        {
            \"name\": \"architecto\",
            \"value\": \"architecto\"
        }
    ]
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/processes"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "type_id": 5,
    "name": "Network installation",
    "priority": "MEDIUM",
    "description": "Eius et animi quos velit et.",
    "customer_id": 100,
    "creation_time": "2024-01-15 10:00:00",
    "ml_desc": "architecto",
    "premise_id": 16,
    "uc_id": 16,
    "user_contact": "architecto",
    "bulk": 16,
    "sla_id": 16,
    "group_task": 16,
    "params": [
        {
            "name": "architecto",
            "value": "architecto"
        }
    ]
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (201):


{
    "data": {
        "ID": 1460744,
        "ML_SG_ID": null,
        "USER_ID": null,
        "STATE_ID": "01",
        "ML_MSS_ID": null,
        "ML_FINISH_MSS_ID": null,
        "SERMAN_ID": null,
        "CREATE_ID": "225",
        "ML_MTT_ID": "0000000076",
        "ML_NODEAVAIL_SGD_ID": null,
        "ML_MTT_STARTING_CODE": null,
        "ML_MTT_CODE": null,
        "NAME": null,
        "ML_CACHE_FULLNAME": null,
        "CREATION_TIME": "2026-03-29 23:08:04",
        "FINISH_TIME": null,
        "SOLVING_TIME": null,
        "PRE_FINISH_DATE": null,
        "CT": "43",
        "ML_HPC_ID": null,
        "ML_PRIORITY": "MEDIUM",
        "ML_N_ID": null,
        "ML_SA_ID": null,
        "ML_O_ID": null,
        "ML_DOCUMENT_TYPE": null,
        "ML_EXTERN_SOLVED": 0,
        "ML_FINISH_MJ_ID": null,
        "ML_REQUIRE_DOC_SCAN": 0,
        "ML_INSERT_PAYMENT": null,
        "ML_FINISH_NOTE": null,
        "ML_GA_ID": null,
        "ML_UCP_ID": null,
        "ML_PREV_ML_ID": null,
        "ML_OI_ID": null,
        "ML_US_ID": null,
        "ML_UA_ID": null,
        "ML_STREET": null,
        "ML_HOUSE_ID": null,
        "ML_ZIP": null,
        "ML_CITY": null,
        "ML_USER_CONTACT": null,
        "ML_ML_ID": null,
        "ML_DR_ID": null,
        "ML_DESC": null,
        "ML_DELAY_ACCEPTED": null,
        "ML_PLANNING_STRATEGY": null,
        "ML_CACHE_ADDRESS": "26343 Cecil Expressway Apt. 748, Gilbertstad",
        "ML_CONFIG_DATE": "2026-01-05 15:30:24",
        "ML_BULK": 0,
        "ML_WAKE_TIME": null,
        "ML_SLA_ID": null,
        "ML_SLA_ACT": "",
        "ML_SLA_TIME": null,
        "ML_P_ID": null,
        "ML_UC_ID": null,
        "ML_CACHE_MTT_UNIQUE_ID": 72,
        "ML_CACHE_MSS_UNIQUE_ID": 7,
        "ML_CACHE_FULLNAME_SC": null,
        "params": [
            {
                "MP_ID": 14753308,
                "MP_ML_ID": 1460744,
                "MP_NAME": "SALESMAN",
                "MP_VALUE": "Qui commodi incidunt iure odit.",
                "MP_INDEX": null,
                "MP_VALUE_UTF8": null,
                "MP_UPDATED": "2026-03-05 06:52:02",
                "MP_L_ID": null
            }
        ],
        "attachments": [
            {
                "FA_ID": 539224,
                "FA_DOC_ID": 1460744,
                "FA_DOC_TYPE": "maintenance",
                "FA_NAME": "modi ipsum nostrum",
                "FA_DESC": "Autem et consequatur aut dolores enim non facere tempora.",
                "FA_FILE_TYPE": 2,
                "FA_FILE_SIZE": 2317,
                "FA_FILE_NAME": "vlxjkl.pdf",
                "FA_DELETED": null,
                "FA_CREATED": "2026-02-26 18:13:02",
                "FA_CREATE_L_ID": null,
                "FA_MODIFIED": null,
                "FA_MODIFY_L_ID": null
            }
        ]
    }
}

Request      

POST api/v3/processes

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Body Parameters

type_id   integer     

Task type ID (maintenance_task_types.MTT_ID) Example: 5

name   string     

Process name Example: Network installation

priority   string  optional    

Priority (LOW, MEDIUM, HIGH, CRITICAL) Example: MEDIUM

description   string  optional    

Process description Example: Eius et animi quos velit et.

customer_id   integer  optional    

Customer user ID Example: 100

creation_time   string  optional    

Creation time (defaults to NOW()) Example: 2024-01-15 10:00:00

ml_desc   string  optional    

Detailed description Example: architecto

premise_id   integer  optional    

Premise ID Example: 16

uc_id   integer  optional    

User contact ID Example: 16

user_contact   string  optional    

User contact info Example: architecto

bulk   integer  optional    

Bulk task flag (0 or 1) Example: 16

sla_id   integer  optional    

SLA ID Example: 16

group_task   integer  optional    

Group task flag Example: 16

params   object[]  optional    

Process parameters array [{name, value}]
name   string  optional    

This field is required when params is present. Example: architecto

value   string  optional    

This field is required when params is present. Example: architecto

Response

Response Fields

data   object     
ID   integer     

Unique process identifier (primary key).

NAME   string     

Process name.

ML_DESC   string     

Detailed process description.

ML_CACHE_FULLNAME   string     

Cached display name resolved from process type configuration.

ML_CACHE_FULLNAME_SC   string     

Cached display name optimized for search (stripped/normalized).

ML_MTT_ID   integer     

Process type ID (references maintenance_task_types).

STATE_ID   integer     

Master state ID (references maintenance_states). 1 = reported, 2 = in progress, 3 = resolved, 4 = confirmed.

ML_MSS_ID   integer     

Current substate ID (references maintenance_substates).

ML_FINISH_MSS_ID   integer     

Substate before finish. Used in workflow to determine the substate prior to task completion.

ML_PRIORITY   string     

Process priority.

Must be one of:
  • LOW
  • MEDIUM
  • HIGH
  • CRITICAL
ML_PLANNING_STRATEGY   string     

Planning strategy code for auto-planned jobs. null = unknown (uses default), 'none' = selects all with MSC_STRATEGY_CODE IS NULL.

ML_CACHE_MTT_UNIQUE_ID   integer     

Cached resolved process type unique ID (from maintenance_task_types).

ML_CACHE_MSS_UNIQUE_ID   integer     

Cached resolved substate unique ID (from maintenance_substates).

USER_ID   integer     

Customer ID (references users).

CREATE_ID   integer     

Creator operator ID (references logins).

SERMAN_ID   integer     

Assigned resource/solver ID (references logins).

ML_SG_ID   integer     

Resource group ID (references serman_groups).

ML_UC_ID   integer     

Customer contact ID (references users_contacts).

ML_USER_CONTACT   string     

Customer contact detail (phone number, email, etc.).

CREATION_TIME   string     

Process creation datetime.

FINISH_TIME   string     

Process completion datetime.

ML_CONFIG_DATE   string     

Configuration snapshot datetime. Determines which process type configuration version applies.

ML_WAKE_TIME   string     

Suspended-to datetime. When set, the process is suspended until this time.

ML_SLA_ID   integer     

SLA definition ID (references code_list).

ML_SLA_ACT   string     

Active SLA flags. Set values: 'EXPIRE', 'WARNING'. Empty string when no SLA issues.

ML_SLA_TIME   string     

Datetime of the first expiring unhandled SLA point. Updated by the maintenance_task_sla_update procedure.

ML_CACHE_ADDRESS   string     

Cached address of the activity location.

ML_P_ID   integer     

Premise ID (references premises).

ML_ML_ID   integer     

Parent/bulk process ID (references maintenance_list). Used for process hierarchy.

ML_O_ID   integer     

Order ID.

ML_BULK   integer     

Bulk process flag. 1 = enables assigning other processes underneath this one.

ML_HPC_ID   integer     

Helpdesk phone call ID that initiated this process.

CT   integer     

Company/tenant identifier (multi-tenant discriminator).

ML_NODEAVAIL_SGD_ID   integer     

Deprecated. Process group (technology) ID.

ML_MTT_STARTING_CODE   string     

Deprecated. Initial code of the process type.

ML_MTT_CODE   string     

Deprecated. Finish code of the process type.

SOLVING_TIME   string     

Deprecated. Start-of-solving datetime.

PRE_FINISH_DATE   string     

Deprecated. Estimated end datetime.

ML_N_ID   integer     

Deprecated. Node/device ID.

ML_SA_ID   integer     

Deprecated. Service assignment ID.

ML_DOCUMENT_TYPE   integer     

Deprecated. Document type that initiated this process (references code_list).

ML_EXTERN_SOLVED   integer     

Deprecated. Externally solved flag.

ML_FINISH_MJ_ID   integer     

Deprecated. Finishing job ID.

ML_REQUIRE_DOC_SCAN   integer     

Deprecated. Flag requiring document scan on process completion.

ML_INSERT_PAYMENT   integer     

Deprecated. Allow payment insertion on done job. null = not allowed, 0 = allow without pre-fill, value = pre-fill amount.

ML_FINISH_NOTE   string     

Deprecated. Closing note.

ML_GA_ID   integer     

Deprecated. Geographic area ID.

ML_UCP_ID   integer     

Deprecated. UIR city part ID.

ML_PREV_ML_ID   integer     

Deprecated. Previous/past process ID.

ML_OI_ID   integer     

Deprecated. Order item ID.

ML_US_ID   integer     

Deprecated. UIR street ID.

ML_UA_ID   integer     

Deprecated. UIR address ID.

ML_STREET   string     

Deprecated. Street address text.

ML_HOUSE_ID   string     

Deprecated. House number.

ML_ZIP   string     

Deprecated. Postal code (PSČ).

ML_CITY   string     

Deprecated. City name.

ML_DR_ID   integer     

Deprecated. Debt recovery process ID.

ML_DELAY_ACCEPTED   integer     

Deprecated. Customer requested and accepted delayed resolution.

planned_minutes   number     

Total planned work time in minutes. Present only when ?time_tracking=true.

spent_minutes   number     

Total spent (logged) work time in minutes. Present only when ?time_tracking=true.

actual_minutes   number     

Actual real work volume in minutes. Present only when ?time_tracking=true.

discrepancy_percent   number     

Percentage discrepancy between actual/spent and planned time. 0 when no planned time. Present only when ?time_tracking=true.

params   object[]     

Process parameters — collection of key-value pairs associated with this process.
MP_ID   integer     

Unique process parameter ID (primary key).

MP_ML_ID   integer     

Parent process ID. See GET /v3/processes/{id}.

MP_NAME   string     

Parameter name. Identifies the parameter type, e.g. 'TYPE', 'PROCESS_DESCRIPTION', 'JOB_START_TIME', 'SERVICES', 'TERM', 'SALESMAN'. Defined in maintenance_params_def.

MP_VALUE   string     

Parameter value (legacy encoding).

MP_VALUE_UTF8   string     

Parameter value in UTF-8 encoding. Used when the value contains characters outside the legacy charset.

MP_INDEX   integer     

Index for multi-valued (table/indexed) parameters. Null for single-value parameters. Zero-based ordering within the same MP_NAME.

MP_UPDATED   string     

Timestamp of the last update to this parameter (YYYY-MM-DD HH:MM:SS).

MP_L_ID   integer     

Operator (login session) ID that last modified this parameter.

attachments   object[]     

File attachments associated with this process.
FA_ID   integer     

Unique attachment identifier (primary key).

FA_DOC_ID   integer     

Parent process ID. See GET /v3/processes/{id}.

FA_DOC_TYPE   string     

Document type discriminator. For process attachments, always 'maintenance'.

FA_NAME   string     

Attachment display name.

FA_DESC   string     

Attachment description.

FA_FILE_NAME   string     

Original file name used for download.

FA_FILE_TYPE   integer     

File type ID (references a code list entry). E.g. 0 = unknown, 1 = pdf, 2 = jpg.

FA_FILE_SIZE   integer     

File size in kilobytes.

FA_DELETED   integer     

Soft-delete flag. null/0 = active, 1 = deleted.

FA_CREATED   string     

Creation datetime (YYYY-MM-DD HH:MM:SS).

FA_CREATE_L_ID   integer     

Creator operator (login session) ID.

FA_MODIFIED   string     

Last modification datetime (YYYY-MM-DD HH:MM:SS).

FA_MODIFY_L_ID   integer     

Last modifier operator (login session) ID.

Get Process

requires authentication 

Returns a single maintenance process by ID.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/processes/3" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/processes/3"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "ID": 1460745,
        "ML_SG_ID": null,
        "USER_ID": null,
        "STATE_ID": "03",
        "ML_MSS_ID": null,
        "ML_FINISH_MSS_ID": null,
        "SERMAN_ID": null,
        "CREATE_ID": "977",
        "ML_MTT_ID": "0000000081",
        "ML_NODEAVAIL_SGD_ID": null,
        "ML_MTT_STARTING_CODE": null,
        "ML_MTT_CODE": null,
        "NAME": null,
        "ML_CACHE_FULLNAME": null,
        "CREATION_TIME": "2026-02-08 13:47:27",
        "FINISH_TIME": null,
        "SOLVING_TIME": null,
        "PRE_FINISH_DATE": null,
        "CT": "79",
        "ML_HPC_ID": null,
        "ML_PRIORITY": "HIGH",
        "ML_N_ID": null,
        "ML_SA_ID": null,
        "ML_O_ID": null,
        "ML_DOCUMENT_TYPE": null,
        "ML_EXTERN_SOLVED": 0,
        "ML_FINISH_MJ_ID": null,
        "ML_REQUIRE_DOC_SCAN": 0,
        "ML_INSERT_PAYMENT": null,
        "ML_FINISH_NOTE": null,
        "ML_GA_ID": null,
        "ML_UCP_ID": null,
        "ML_PREV_ML_ID": null,
        "ML_OI_ID": null,
        "ML_US_ID": null,
        "ML_UA_ID": null,
        "ML_STREET": null,
        "ML_HOUSE_ID": null,
        "ML_ZIP": null,
        "ML_CITY": null,
        "ML_USER_CONTACT": null,
        "ML_ML_ID": null,
        "ML_DR_ID": null,
        "ML_DESC": null,
        "ML_DELAY_ACCEPTED": null,
        "ML_PLANNING_STRATEGY": null,
        "ML_CACHE_ADDRESS": "544 Aglae Ridge Apt. 067, Lefflerhaven",
        "ML_CONFIG_DATE": "2026-02-23 07:51:37",
        "ML_BULK": 0,
        "ML_WAKE_TIME": null,
        "ML_SLA_ID": null,
        "ML_SLA_ACT": "",
        "ML_SLA_TIME": null,
        "ML_P_ID": null,
        "ML_UC_ID": null,
        "ML_CACHE_MTT_UNIQUE_ID": 25,
        "ML_CACHE_MSS_UNIQUE_ID": 50,
        "ML_CACHE_FULLNAME_SC": null,
        "params": [
            {
                "MP_ID": 14753309,
                "MP_ML_ID": 1460745,
                "MP_NAME": "JOB_START_TIME",
                "MP_VALUE": "Voluptatem laboriosam praesentium quis adipisci.",
                "MP_INDEX": null,
                "MP_VALUE_UTF8": null,
                "MP_UPDATED": "2026-03-18 04:10:27",
                "MP_L_ID": null
            }
        ],
        "attachments": [
            {
                "FA_ID": 539225,
                "FA_DOC_ID": 1460745,
                "FA_DOC_TYPE": "maintenance",
                "FA_NAME": "deleniti distinctio eum",
                "FA_DESC": "Id aut libero aliquam veniam.",
                "FA_FILE_TYPE": 2,
                "FA_FILE_SIZE": null,
                "FA_FILE_NAME": "noqitp.pdf",
                "FA_DELETED": null,
                "FA_CREATED": "2026-04-11 04:23:29",
                "FA_CREATE_L_ID": null,
                "FA_MODIFIED": null,
                "FA_MODIFY_L_ID": null
            }
        ]
    }
}

Request      

GET api/v3/processes/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the process. Example: 3

Response

Response Fields

data   object     
ID   integer     

Unique process identifier (primary key).

NAME   string     

Process name.

ML_DESC   string     

Detailed process description.

ML_CACHE_FULLNAME   string     

Cached display name resolved from process type configuration.

ML_CACHE_FULLNAME_SC   string     

Cached display name optimized for search (stripped/normalized).

ML_MTT_ID   integer     

Process type ID (references maintenance_task_types).

STATE_ID   integer     

Master state ID (references maintenance_states). 1 = reported, 2 = in progress, 3 = resolved, 4 = confirmed.

ML_MSS_ID   integer     

Current substate ID (references maintenance_substates).

ML_FINISH_MSS_ID   integer     

Substate before finish. Used in workflow to determine the substate prior to task completion.

ML_PRIORITY   string     

Process priority.

Must be one of:
  • LOW
  • MEDIUM
  • HIGH
  • CRITICAL
ML_PLANNING_STRATEGY   string     

Planning strategy code for auto-planned jobs. null = unknown (uses default), 'none' = selects all with MSC_STRATEGY_CODE IS NULL.

ML_CACHE_MTT_UNIQUE_ID   integer     

Cached resolved process type unique ID (from maintenance_task_types).

ML_CACHE_MSS_UNIQUE_ID   integer     

Cached resolved substate unique ID (from maintenance_substates).

USER_ID   integer     

Customer ID (references users).

CREATE_ID   integer     

Creator operator ID (references logins).

SERMAN_ID   integer     

Assigned resource/solver ID (references logins).

ML_SG_ID   integer     

Resource group ID (references serman_groups).

ML_UC_ID   integer     

Customer contact ID (references users_contacts).

ML_USER_CONTACT   string     

Customer contact detail (phone number, email, etc.).

CREATION_TIME   string     

Process creation datetime.

FINISH_TIME   string     

Process completion datetime.

ML_CONFIG_DATE   string     

Configuration snapshot datetime. Determines which process type configuration version applies.

ML_WAKE_TIME   string     

Suspended-to datetime. When set, the process is suspended until this time.

ML_SLA_ID   integer     

SLA definition ID (references code_list).

ML_SLA_ACT   string     

Active SLA flags. Set values: 'EXPIRE', 'WARNING'. Empty string when no SLA issues.

ML_SLA_TIME   string     

Datetime of the first expiring unhandled SLA point. Updated by the maintenance_task_sla_update procedure.

ML_CACHE_ADDRESS   string     

Cached address of the activity location.

ML_P_ID   integer     

Premise ID (references premises).

ML_ML_ID   integer     

Parent/bulk process ID (references maintenance_list). Used for process hierarchy.

ML_O_ID   integer     

Order ID.

ML_BULK   integer     

Bulk process flag. 1 = enables assigning other processes underneath this one.

ML_HPC_ID   integer     

Helpdesk phone call ID that initiated this process.

CT   integer     

Company/tenant identifier (multi-tenant discriminator).

ML_NODEAVAIL_SGD_ID   integer     

Deprecated. Process group (technology) ID.

ML_MTT_STARTING_CODE   string     

Deprecated. Initial code of the process type.

ML_MTT_CODE   string     

Deprecated. Finish code of the process type.

SOLVING_TIME   string     

Deprecated. Start-of-solving datetime.

PRE_FINISH_DATE   string     

Deprecated. Estimated end datetime.

ML_N_ID   integer     

Deprecated. Node/device ID.

ML_SA_ID   integer     

Deprecated. Service assignment ID.

ML_DOCUMENT_TYPE   integer     

Deprecated. Document type that initiated this process (references code_list).

ML_EXTERN_SOLVED   integer     

Deprecated. Externally solved flag.

ML_FINISH_MJ_ID   integer     

Deprecated. Finishing job ID.

ML_REQUIRE_DOC_SCAN   integer     

Deprecated. Flag requiring document scan on process completion.

ML_INSERT_PAYMENT   integer     

Deprecated. Allow payment insertion on done job. null = not allowed, 0 = allow without pre-fill, value = pre-fill amount.

ML_FINISH_NOTE   string     

Deprecated. Closing note.

ML_GA_ID   integer     

Deprecated. Geographic area ID.

ML_UCP_ID   integer     

Deprecated. UIR city part ID.

ML_PREV_ML_ID   integer     

Deprecated. Previous/past process ID.

ML_OI_ID   integer     

Deprecated. Order item ID.

ML_US_ID   integer     

Deprecated. UIR street ID.

ML_UA_ID   integer     

Deprecated. UIR address ID.

ML_STREET   string     

Deprecated. Street address text.

ML_HOUSE_ID   string     

Deprecated. House number.

ML_ZIP   string     

Deprecated. Postal code (PSČ).

ML_CITY   string     

Deprecated. City name.

ML_DR_ID   integer     

Deprecated. Debt recovery process ID.

ML_DELAY_ACCEPTED   integer     

Deprecated. Customer requested and accepted delayed resolution.

planned_minutes   number     

Total planned work time in minutes. Present only when ?time_tracking=true.

spent_minutes   number     

Total spent (logged) work time in minutes. Present only when ?time_tracking=true.

actual_minutes   number     

Actual real work volume in minutes. Present only when ?time_tracking=true.

discrepancy_percent   number     

Percentage discrepancy between actual/spent and planned time. 0 when no planned time. Present only when ?time_tracking=true.

params   object[]     

Process parameters — collection of key-value pairs associated with this process.
MP_ID   integer     

Unique process parameter ID (primary key).

MP_ML_ID   integer     

Parent process ID. See GET /v3/processes/{id}.

MP_NAME   string     

Parameter name. Identifies the parameter type, e.g. 'TYPE', 'PROCESS_DESCRIPTION', 'JOB_START_TIME', 'SERVICES', 'TERM', 'SALESMAN'. Defined in maintenance_params_def.

MP_VALUE   string     

Parameter value (legacy encoding).

MP_VALUE_UTF8   string     

Parameter value in UTF-8 encoding. Used when the value contains characters outside the legacy charset.

MP_INDEX   integer     

Index for multi-valued (table/indexed) parameters. Null for single-value parameters. Zero-based ordering within the same MP_NAME.

MP_UPDATED   string     

Timestamp of the last update to this parameter (YYYY-MM-DD HH:MM:SS).

MP_L_ID   integer     

Operator (login session) ID that last modified this parameter.

attachments   object[]     

File attachments associated with this process.
FA_ID   integer     

Unique attachment identifier (primary key).

FA_DOC_ID   integer     

Parent process ID. See GET /v3/processes/{id}.

FA_DOC_TYPE   string     

Document type discriminator. For process attachments, always 'maintenance'.

FA_NAME   string     

Attachment display name.

FA_DESC   string     

Attachment description.

FA_FILE_NAME   string     

Original file name used for download.

FA_FILE_TYPE   integer     

File type ID (references a code list entry). E.g. 0 = unknown, 1 = pdf, 2 = jpg.

FA_FILE_SIZE   integer     

File size in kilobytes.

FA_DELETED   integer     

Soft-delete flag. null/0 = active, 1 = deleted.

FA_CREATED   string     

Creation datetime (YYYY-MM-DD HH:MM:SS).

FA_CREATE_L_ID   integer     

Creator operator (login session) ID.

FA_MODIFIED   string     

Last modification datetime (YYYY-MM-DD HH:MM:SS).

FA_MODIFY_L_ID   integer     

Last modifier operator (login session) ID.

Update Process

requires authentication 

Updates an existing maintenance process via maintenance_task_edit stored procedure.
Example request:
curl --request PUT \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/processes/3" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"type_id\": 5,
    \"name\": \"Network installation\",
    \"priority\": \"MEDIUM\",
    \"description\": \"Eius et animi quos velit et.\",
    \"customer_id\": 100,
    \"ml_desc\": \"architecto\",
    \"premise_id\": 16,
    \"uc_id\": 16,
    \"user_contact\": \"architecto\",
    \"state_change\": 16,
    \"bulk\": 16,
    \"sla_id\": 16,
    \"group_task\": 16,
    \"params\": [
        {
            \"name\": \"architecto\",
            \"value\": \"architecto\"
        }
    ]
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/processes/3"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "type_id": 5,
    "name": "Network installation",
    "priority": "MEDIUM",
    "description": "Eius et animi quos velit et.",
    "customer_id": 100,
    "ml_desc": "architecto",
    "premise_id": 16,
    "uc_id": 16,
    "user_contact": "architecto",
    "state_change": 16,
    "bulk": 16,
    "sla_id": 16,
    "group_task": 16,
    "params": [
        {
            "name": "architecto",
            "value": "architecto"
        }
    ]
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "data": {
        "ID": 1460746,
        "ML_SG_ID": null,
        "USER_ID": null,
        "STATE_ID": "01",
        "ML_MSS_ID": null,
        "ML_FINISH_MSS_ID": null,
        "SERMAN_ID": null,
        "CREATE_ID": "225",
        "ML_MTT_ID": "0000000076",
        "ML_NODEAVAIL_SGD_ID": null,
        "ML_MTT_STARTING_CODE": null,
        "ML_MTT_CODE": null,
        "NAME": null,
        "ML_CACHE_FULLNAME": null,
        "CREATION_TIME": "2026-03-29 23:08:04",
        "FINISH_TIME": null,
        "SOLVING_TIME": null,
        "PRE_FINISH_DATE": null,
        "CT": "43",
        "ML_HPC_ID": null,
        "ML_PRIORITY": "MEDIUM",
        "ML_N_ID": null,
        "ML_SA_ID": null,
        "ML_O_ID": null,
        "ML_DOCUMENT_TYPE": null,
        "ML_EXTERN_SOLVED": 0,
        "ML_FINISH_MJ_ID": null,
        "ML_REQUIRE_DOC_SCAN": 0,
        "ML_INSERT_PAYMENT": null,
        "ML_FINISH_NOTE": null,
        "ML_GA_ID": null,
        "ML_UCP_ID": null,
        "ML_PREV_ML_ID": null,
        "ML_OI_ID": null,
        "ML_US_ID": null,
        "ML_UA_ID": null,
        "ML_STREET": null,
        "ML_HOUSE_ID": null,
        "ML_ZIP": null,
        "ML_CITY": null,
        "ML_USER_CONTACT": null,
        "ML_ML_ID": null,
        "ML_DR_ID": null,
        "ML_DESC": null,
        "ML_DELAY_ACCEPTED": null,
        "ML_PLANNING_STRATEGY": null,
        "ML_CACHE_ADDRESS": "26343 Cecil Expressway Apt. 748, Gilbertstad",
        "ML_CONFIG_DATE": "2026-01-05 15:30:24",
        "ML_BULK": 0,
        "ML_WAKE_TIME": null,
        "ML_SLA_ID": null,
        "ML_SLA_ACT": "",
        "ML_SLA_TIME": null,
        "ML_P_ID": null,
        "ML_UC_ID": null,
        "ML_CACHE_MTT_UNIQUE_ID": 72,
        "ML_CACHE_MSS_UNIQUE_ID": 7,
        "ML_CACHE_FULLNAME_SC": null,
        "params": [
            {
                "MP_ID": 14753310,
                "MP_ML_ID": 1460746,
                "MP_NAME": "SALESMAN",
                "MP_VALUE": "Qui commodi incidunt iure odit.",
                "MP_INDEX": null,
                "MP_VALUE_UTF8": null,
                "MP_UPDATED": "2026-03-05 06:52:02",
                "MP_L_ID": null
            }
        ],
        "attachments": [
            {
                "FA_ID": 539226,
                "FA_DOC_ID": 1460746,
                "FA_DOC_TYPE": "maintenance",
                "FA_NAME": "modi ipsum nostrum",
                "FA_DESC": "Autem et consequatur aut dolores enim non facere tempora.",
                "FA_FILE_TYPE": 2,
                "FA_FILE_SIZE": 2317,
                "FA_FILE_NAME": "vlxjkl.pdf",
                "FA_DELETED": null,
                "FA_CREATED": "2026-02-26 18:13:02",
                "FA_CREATE_L_ID": null,
                "FA_MODIFIED": null,
                "FA_MODIFY_L_ID": null
            }
        ]
    }
}

Request      

PUT api/v3/processes/{id}

PATCH api/v3/processes/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the process. Example: 3

Body Parameters

type_id   integer  optional    

Task type ID Example: 5

name   string  optional    

Process name Example: Network installation

priority   string  optional    

Priority (LOW, MEDIUM, HIGH, CRITICAL) Example: MEDIUM

description   string  optional    

Process description Example: Eius et animi quos velit et.

customer_id   integer  optional    

Customer user ID Example: 100

ml_desc   string  optional    

Detailed description Example: architecto

premise_id   integer  optional    

Premise ID Example: 16

uc_id   integer  optional    

User contact ID Example: 16

user_contact   string  optional    

User contact info Example: architecto

state_change   integer  optional    

State change (0=none, 1=finish, 2=confirm, 3=confirmall) Example: 16

bulk   integer  optional    

Bulk task flag (0 or 1) Example: 16

sla_id   integer  optional    

SLA ID Example: 16

group_task   integer  optional    

Group task flag Example: 16

params   object[]  optional    

Process parameters array [{name, value}]
name   string  optional    

This field is required when params is present. Example: architecto

value   string  optional    

This field is required when params is present. Example: architecto

Response

Response Fields

data   object     
ID   integer     

Unique process identifier (primary key).

NAME   string     

Process name.

ML_DESC   string     

Detailed process description.

ML_CACHE_FULLNAME   string     

Cached display name resolved from process type configuration.

ML_CACHE_FULLNAME_SC   string     

Cached display name optimized for search (stripped/normalized).

ML_MTT_ID   integer     

Process type ID (references maintenance_task_types).

STATE_ID   integer     

Master state ID (references maintenance_states). 1 = reported, 2 = in progress, 3 = resolved, 4 = confirmed.

ML_MSS_ID   integer     

Current substate ID (references maintenance_substates).

ML_FINISH_MSS_ID   integer     

Substate before finish. Used in workflow to determine the substate prior to task completion.

ML_PRIORITY   string     

Process priority.

Must be one of:
  • LOW
  • MEDIUM
  • HIGH
  • CRITICAL
ML_PLANNING_STRATEGY   string     

Planning strategy code for auto-planned jobs. null = unknown (uses default), 'none' = selects all with MSC_STRATEGY_CODE IS NULL.

ML_CACHE_MTT_UNIQUE_ID   integer     

Cached resolved process type unique ID (from maintenance_task_types).

ML_CACHE_MSS_UNIQUE_ID   integer     

Cached resolved substate unique ID (from maintenance_substates).

USER_ID   integer     

Customer ID (references users).

CREATE_ID   integer     

Creator operator ID (references logins).

SERMAN_ID   integer     

Assigned resource/solver ID (references logins).

ML_SG_ID   integer     

Resource group ID (references serman_groups).

ML_UC_ID   integer     

Customer contact ID (references users_contacts).

ML_USER_CONTACT   string     

Customer contact detail (phone number, email, etc.).

CREATION_TIME   string     

Process creation datetime.

FINISH_TIME   string     

Process completion datetime.

ML_CONFIG_DATE   string     

Configuration snapshot datetime. Determines which process type configuration version applies.

ML_WAKE_TIME   string     

Suspended-to datetime. When set, the process is suspended until this time.

ML_SLA_ID   integer     

SLA definition ID (references code_list).

ML_SLA_ACT   string     

Active SLA flags. Set values: 'EXPIRE', 'WARNING'. Empty string when no SLA issues.

ML_SLA_TIME   string     

Datetime of the first expiring unhandled SLA point. Updated by the maintenance_task_sla_update procedure.

ML_CACHE_ADDRESS   string     

Cached address of the activity location.

ML_P_ID   integer     

Premise ID (references premises).

ML_ML_ID   integer     

Parent/bulk process ID (references maintenance_list). Used for process hierarchy.

ML_O_ID   integer     

Order ID.

ML_BULK   integer     

Bulk process flag. 1 = enables assigning other processes underneath this one.

ML_HPC_ID   integer     

Helpdesk phone call ID that initiated this process.

CT   integer     

Company/tenant identifier (multi-tenant discriminator).

ML_NODEAVAIL_SGD_ID   integer     

Deprecated. Process group (technology) ID.

ML_MTT_STARTING_CODE   string     

Deprecated. Initial code of the process type.

ML_MTT_CODE   string     

Deprecated. Finish code of the process type.

SOLVING_TIME   string     

Deprecated. Start-of-solving datetime.

PRE_FINISH_DATE   string     

Deprecated. Estimated end datetime.

ML_N_ID   integer     

Deprecated. Node/device ID.

ML_SA_ID   integer     

Deprecated. Service assignment ID.

ML_DOCUMENT_TYPE   integer     

Deprecated. Document type that initiated this process (references code_list).

ML_EXTERN_SOLVED   integer     

Deprecated. Externally solved flag.

ML_FINISH_MJ_ID   integer     

Deprecated. Finishing job ID.

ML_REQUIRE_DOC_SCAN   integer     

Deprecated. Flag requiring document scan on process completion.

ML_INSERT_PAYMENT   integer     

Deprecated. Allow payment insertion on done job. null = not allowed, 0 = allow without pre-fill, value = pre-fill amount.

ML_FINISH_NOTE   string     

Deprecated. Closing note.

ML_GA_ID   integer     

Deprecated. Geographic area ID.

ML_UCP_ID   integer     

Deprecated. UIR city part ID.

ML_PREV_ML_ID   integer     

Deprecated. Previous/past process ID.

ML_OI_ID   integer     

Deprecated. Order item ID.

ML_US_ID   integer     

Deprecated. UIR street ID.

ML_UA_ID   integer     

Deprecated. UIR address ID.

ML_STREET   string     

Deprecated. Street address text.

ML_HOUSE_ID   string     

Deprecated. House number.

ML_ZIP   string     

Deprecated. Postal code (PSČ).

ML_CITY   string     

Deprecated. City name.

ML_DR_ID   integer     

Deprecated. Debt recovery process ID.

ML_DELAY_ACCEPTED   integer     

Deprecated. Customer requested and accepted delayed resolution.

planned_minutes   number     

Total planned work time in minutes. Present only when ?time_tracking=true.

spent_minutes   number     

Total spent (logged) work time in minutes. Present only when ?time_tracking=true.

actual_minutes   number     

Actual real work volume in minutes. Present only when ?time_tracking=true.

discrepancy_percent   number     

Percentage discrepancy between actual/spent and planned time. 0 when no planned time. Present only when ?time_tracking=true.

params   object[]     

Process parameters — collection of key-value pairs associated with this process.
MP_ID   integer     

Unique process parameter ID (primary key).

MP_ML_ID   integer     

Parent process ID. See GET /v3/processes/{id}.

MP_NAME   string     

Parameter name. Identifies the parameter type, e.g. 'TYPE', 'PROCESS_DESCRIPTION', 'JOB_START_TIME', 'SERVICES', 'TERM', 'SALESMAN'. Defined in maintenance_params_def.

MP_VALUE   string     

Parameter value (legacy encoding).

MP_VALUE_UTF8   string     

Parameter value in UTF-8 encoding. Used when the value contains characters outside the legacy charset.

MP_INDEX   integer     

Index for multi-valued (table/indexed) parameters. Null for single-value parameters. Zero-based ordering within the same MP_NAME.

MP_UPDATED   string     

Timestamp of the last update to this parameter (YYYY-MM-DD HH:MM:SS).

MP_L_ID   integer     

Operator (login session) ID that last modified this parameter.

attachments   object[]     

File attachments associated with this process.
FA_ID   integer     

Unique attachment identifier (primary key).

FA_DOC_ID   integer     

Parent process ID. See GET /v3/processes/{id}.

FA_DOC_TYPE   string     

Document type discriminator. For process attachments, always 'maintenance'.

FA_NAME   string     

Attachment display name.

FA_DESC   string     

Attachment description.

FA_FILE_NAME   string     

Original file name used for download.

FA_FILE_TYPE   integer     

File type ID (references a code list entry). E.g. 0 = unknown, 1 = pdf, 2 = jpg.

FA_FILE_SIZE   integer     

File size in kilobytes.

FA_DELETED   integer     

Soft-delete flag. null/0 = active, 1 = deleted.

FA_CREATED   string     

Creation datetime (YYYY-MM-DD HH:MM:SS).

FA_CREATE_L_ID   integer     

Creator operator (login session) ID.

FA_MODIFIED   string     

Last modification datetime (YYYY-MM-DD HH:MM:SS).

FA_MODIFY_L_ID   integer     

Last modifier operator (login session) ID.

Delete Process (State Change)

requires authentication 

Performs a substate transition on a process via maintenance_task_change_substate.
Requires transition_id in the request body.
Example request:
curl --request DELETE \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/processes/3" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"transition_id\": 84
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/processes/3"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "transition_id": 84
};

fetch(url, {
    method: "DELETE",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (204):

Empty response

Request      

DELETE api/v3/processes/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the process. Example: 3

Body Parameters

transition_id   integer     

Substate transition ID (maintenance_substates_transitions.MSST_ID) Example: 84

Download Process Attachment

requires authentication 

Downloads a file attachment belonging to a process.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/processes/3/attachments/architecto/download" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/processes/3/attachments/architecto/download"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "message": "Unauthenticated."
}

Request      

GET api/v3/processes/{process}/attachments/{attachment}/download

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

process   integer     

The process. Example: 3

attachment   string     

The attachment. Example: architecto

Reminders

List Debt Recovery Processes

requires authentication

Returns a paginated list of debt recovery processes. At least one of the following filters must be provided: customer, state. Without a narrowing filter the endpoint returns HTTP 422.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/debt-recovery-processes?per_page=10&page=1&ids=1%2C2%2C3&cts=1%2C2%2C3&customer=345&state=IN_PROGRESS%2CBLOCKED" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/debt-recovery-processes"
);

const params = {
    "per_page": "10",
    "page": "1",
    "ids": "1,2,3",
    "cts": "1,2,3",
    "customer": "345",
    "state": "IN_PROGRESS,BLOCKED",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "DR_ID": 491669,
            "DR_U_ID": 299,
            "DR_START": "2025-08-27 07:36:41",
            "DR_STATE": "REMINDER_ACK",
            "DR_ORDER": 4,
            "DR_PROVISIONING": 1,
            "DR_END": null,
            "DR_SUSPENDED_TO": null,
            "DR_UNBLOCK_FEE": 0,
            "DR_CHANGED": null,
            "DR_L_ID": null
        },
        {
            "DR_ID": 491670,
            "DR_U_ID": 8082,
            "DR_START": "2025-01-17 17:03:54",
            "DR_STATE": "BLOCKED",
            "DR_ORDER": 2,
            "DR_PROVISIONING": 0,
            "DR_END": null,
            "DR_SUSPENDED_TO": null,
            "DR_UNBLOCK_FEE": 0,
            "DR_CHANGED": null,
            "DR_L_ID": null
        }
    ]
}

Request      

GET api/v3/debt-recovery-processes

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of items per page. Example: 10

page   integer  optional    

Page number. Example: 1

ids   string  optional    

Filter by comma-separated debt recovery process IDs. Example: 1,2,3

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Example: 1,2,3

customer   integer  optional    

Filter by customer (user) ID. Example: 345

state   string  optional    

Filter by process state. Accepts comma-separated values. Example: IN_PROGRESS,BLOCKED

Response

Response Fields

data   object     
DR_ID   integer     

Unique debt recovery process identifier (primary key).

DR_U_ID   integer     

Customer (user) ID. See GET /v3/customers/{id}.

DR_START   string     

Process start date and time (YYYY-MM-DD HH:MM:SS).

DR_STATE   string     

Current process state. One of: REMINDER_GEN, REMINDER_EXP, REMINDER_ACK, SUSPENDED, IN_PROGRESS, BLOCKED, CANCELED, EXTERNAL, AVIZO.

DR_ORDER   integer     

Reminder sequence number within this process.

DR_PROVISIONING   integer     

Provisioning flag. 1 = provisioning affected.

DR_END   string     

Process end date and time.

DR_SUSPENDED_TO   string     

Date until which the process is suspended (YYYY-MM-DD).

DR_UNBLOCK_FEE   integer     

Unblock fee flag. 1 = fee applies.

DR_CHANGED   string     

Last modification date and time.

DR_L_ID   integer     

Login session ID of the last modifier.

Get Debt Recovery Process

requires authentication

Returns a single debt recovery process by ID.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/debt-recovery-processes/1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/debt-recovery-processes/1"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "DR_ID": 491671,
        "DR_U_ID": 2878,
        "DR_START": "2024-08-04 05:50:08",
        "DR_STATE": "BLOCKED",
        "DR_ORDER": 3,
        "DR_PROVISIONING": 0,
        "DR_END": null,
        "DR_SUSPENDED_TO": null,
        "DR_UNBLOCK_FEE": 0,
        "DR_CHANGED": null,
        "DR_L_ID": null
    }
}

Request      

GET api/v3/debt-recovery-processes/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the debt recovery process. Example: 1

Response

Response Fields

data   object     
DR_ID   integer     

Unique debt recovery process identifier (primary key).

DR_U_ID   integer     

Customer (user) ID. See GET /v3/customers/{id}.

DR_START   string     

Process start date and time (YYYY-MM-DD HH:MM:SS).

DR_STATE   string     

Current process state. One of: REMINDER_GEN, REMINDER_EXP, REMINDER_ACK, SUSPENDED, IN_PROGRESS, BLOCKED, CANCELED, EXTERNAL, AVIZO.

DR_ORDER   integer     

Reminder sequence number within this process.

DR_PROVISIONING   integer     

Provisioning flag. 1 = provisioning affected.

DR_END   string     

Process end date and time.

DR_SUSPENDED_TO   string     

Date until which the process is suspended (YYYY-MM-DD).

DR_UNBLOCK_FEE   integer     

Unblock fee flag. 1 = fee applies.

DR_CHANGED   string     

Last modification date and time.

DR_L_ID   integer     

Login session ID of the last modifier.

List Reminder Batches

requires authentication

Returns a paginated list of reminder batches. At least one of the following filters must be provided: date_from, date_to. Without a narrowing filter the endpoint returns HTTP 422. Reminders within batches are NOT loaded in the list — use the detail endpoint.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/reminder-batches?per_page=10&page=1&ids=1%2C2%2C3&cts=1%2C2%2C3&date_from=2024-01-01&date_to=2024-12-31" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/reminder-batches"
);

const params = {
    "per_page": "10",
    "page": "1",
    "ids": "1,2,3",
    "cts": "1,2,3",
    "date_from": "2024-01-01",
    "date_to": "2024-12-31",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "RHB_ID": 5516,
            "RHB_BATCH": 592,
            "RHB_ML_ID": null,
            "RHB_MJ_ID": null,
            "RHB_TYPE": "REMINDER",
            "RHB_DATE": null,
            "RHB_FINAL_DATE": null,
            "RHB_LAST_REM_DATE": null,
            "RHB_DUE_DAYS": null,
            "RHB_DUE_DATE": null,
            "RHB_DUE_DATE1": null,
            "RHB_DUE_DATE2": null,
            "RHB_TAX_DATE1": null,
            "RHB_TAX_DATE2": null,
            "RHB_ADDRESS": null,
            "RHB_U_FILTER": null,
            "RHB_NOTAX": null,
            "RHB_GROUP": null,
            "RHB_DEBTFROM": null,
            "RHB_DEBTTO": null,
            "RHB_NOTE": null,
            "RHB_CREATOR": null,
            "RHB_CREATED": null
        },
        {
            "RHB_ID": 5517,
            "RHB_BATCH": 339,
            "RHB_ML_ID": null,
            "RHB_MJ_ID": null,
            "RHB_TYPE": "REMINDER",
            "RHB_DATE": null,
            "RHB_FINAL_DATE": null,
            "RHB_LAST_REM_DATE": null,
            "RHB_DUE_DAYS": null,
            "RHB_DUE_DATE": null,
            "RHB_DUE_DATE1": null,
            "RHB_DUE_DATE2": null,
            "RHB_TAX_DATE1": null,
            "RHB_TAX_DATE2": null,
            "RHB_ADDRESS": null,
            "RHB_U_FILTER": null,
            "RHB_NOTAX": null,
            "RHB_GROUP": null,
            "RHB_DEBTFROM": null,
            "RHB_DEBTTO": null,
            "RHB_NOTE": null,
            "RHB_CREATOR": null,
            "RHB_CREATED": null
        }
    ]
}

Request      

GET api/v3/reminder-batches

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of items per page. Example: 10

page   integer  optional    

Page number. Example: 1

ids   string  optional    

Filter by comma-separated batch IDs. Example: 1,2,3

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Example: 1,2,3

date_from   string  optional    

Filter batches created on or after this date (YYYY-MM-DD). Applies to RHB_DATE. Example: 2024-01-01

date_to   string  optional    

Filter batches created on or before this date (YYYY-MM-DD). Applies to RHB_DATE. Example: 2024-12-31

Response

Response Fields

data   object     
RHB_ID   integer     

Unique batch identifier (primary key).

RHB_BATCH   integer     

Batch sequence number.

RHB_ML_ID   integer     

Maintenance list (process) ID. See GET /v3/processes/{id}.

RHB_MJ_ID   integer     

Maintenance job ID within the process.

RHB_TYPE   string     

Batch type identifier (up to 30 characters).

RHB_DATE   string     

Batch creation/run date (YYYY-MM-DD).

RHB_FINAL_DATE   string     

Payment due date for the batch (YYYY-MM-DD).

RHB_LAST_REM_DATE   string     

Date of the last reminder in this batch (YYYY-MM-DD).

RHB_DUE_DAYS   integer     

Number of days until due.

RHB_DUE_DATE   string     

Primary due date (YYYY-MM-DD).

RHB_DUE_DATE1   string     

Secondary due date (YYYY-MM-DD).

RHB_DUE_DATE2   string     

Tertiary due date (YYYY-MM-DD).

RHB_TAX_DATE1   string     

Tax period start date (YYYY-MM-DD).

RHB_TAX_DATE2   string     

Tax period end date (YYYY-MM-DD).

RHB_ADDRESS   string     

Delivery address override (up to 100 characters).

RHB_U_FILTER   integer     

Customer filter ID applied during batch generation.

RHB_NOTAX   integer     

Exclude tax documents flag.

RHB_GROUP   string     

Customer group filter (up to 10 characters).

RHB_DEBTFROM   number     

Minimum debt threshold for inclusion.

RHB_DEBTTO   number     

Maximum debt threshold for inclusion.

RHB_NOTE   string     

Batch note / description.

RHB_CREATOR   integer     

Login ID of the batch creator.

RHB_CREATED   string     

Batch creation timestamp (YYYY-MM-DD HH:MM:SS).

reminders   object[]     

Reminders in this batch (loaded in detail view only).

Get Reminder Batch

requires authentication

Returns a single reminder batch by ID. Includes the reminders relation (loaded only in this detail view).

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/reminder-batches/1" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/reminder-batches/1"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "RHB_ID": 5518,
        "RHB_BATCH": 592,
        "RHB_ML_ID": null,
        "RHB_MJ_ID": null,
        "RHB_TYPE": "REMINDER",
        "RHB_DATE": null,
        "RHB_FINAL_DATE": null,
        "RHB_LAST_REM_DATE": null,
        "RHB_DUE_DAYS": null,
        "RHB_DUE_DATE": null,
        "RHB_DUE_DATE1": null,
        "RHB_DUE_DATE2": null,
        "RHB_TAX_DATE1": null,
        "RHB_TAX_DATE2": null,
        "RHB_ADDRESS": null,
        "RHB_U_FILTER": null,
        "RHB_NOTAX": null,
        "RHB_GROUP": null,
        "RHB_DEBTFROM": null,
        "RHB_DEBTTO": null,
        "RHB_NOTE": null,
        "RHB_CREATOR": null,
        "RHB_CREATED": null,
        "reminders": [
            {
                "ID": 1839459,
                "RH_DOC_ID": 80304,
                "USER_ID": 2617,
                "DATE_REMIND": "2010-09-17",
                "NOTE": 0,
                "CT": 40,
                "SEND_NOTE": null,
                "RH_ORDER": 1,
                "RH_AUTHOR": 274,
                "RH_CREATED": null,
                "RH_FINAL_DATE": null,
                "RH_NOTE": null,
                "RH_RHB_ID": 5518,
                "RH_DATE_ACK": null,
                "RH_DR_ID": null,
                "RH_PROVIDER_USER_ID": null
            }
        ]
    }
}

Request      

GET api/v3/reminder-batches/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the reminder batch. Example: 1

Response

Response Fields

data   object     
RHB_ID   integer     

Unique batch identifier (primary key).

RHB_BATCH   integer     

Batch sequence number.

RHB_ML_ID   integer     

Maintenance list (process) ID. See GET /v3/processes/{id}.

RHB_MJ_ID   integer     

Maintenance job ID within the process.

RHB_TYPE   string     

Batch type identifier (up to 30 characters).

RHB_DATE   string     

Batch creation/run date (YYYY-MM-DD).

RHB_FINAL_DATE   string     

Payment due date for the batch (YYYY-MM-DD).

RHB_LAST_REM_DATE   string     

Date of the last reminder in this batch (YYYY-MM-DD).

RHB_DUE_DAYS   integer     

Number of days until due.

RHB_DUE_DATE   string     

Primary due date (YYYY-MM-DD).

RHB_DUE_DATE1   string     

Secondary due date (YYYY-MM-DD).

RHB_DUE_DATE2   string     

Tertiary due date (YYYY-MM-DD).

RHB_TAX_DATE1   string     

Tax period start date (YYYY-MM-DD).

RHB_TAX_DATE2   string     

Tax period end date (YYYY-MM-DD).

RHB_ADDRESS   string     

Delivery address override (up to 100 characters).

RHB_U_FILTER   integer     

Customer filter ID applied during batch generation.

RHB_NOTAX   integer     

Exclude tax documents flag.

RHB_GROUP   string     

Customer group filter (up to 10 characters).

RHB_DEBTFROM   number     

Minimum debt threshold for inclusion.

RHB_DEBTTO   number     

Maximum debt threshold for inclusion.

RHB_NOTE   string     

Batch note / description.

RHB_CREATOR   integer     

Login ID of the batch creator.

RHB_CREATED   string     

Batch creation timestamp (YYYY-MM-DD HH:MM:SS).

reminders   object[]     

Reminders in this batch (loaded in detail view only).

List Reminders

requires authentication

Returns a paginated list of reminders with computed financial data and line items. At least one of the following filters must be provided: customer, batch, date_from, year. Without a narrowing filter the endpoint returns HTTP 422.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/reminders?per_page=10&page=1&ids=1%2C2%2C3&cts=1%2C2%2C3&customer=345&batch=100&debt_recovery=50&provider=200&date_from=2024-01-01&date_to=2024-12-31&order=1&year=2024" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/reminders"
);

const params = {
    "per_page": "10",
    "page": "1",
    "ids": "1,2,3",
    "cts": "1,2,3",
    "customer": "345",
    "batch": "100",
    "debt_recovery": "50",
    "provider": "200",
    "date_from": "2024-01-01",
    "date_to": "2024-12-31",
    "order": "1",
    "year": "2024",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "ID": 1839460,
            "RH_DOC_ID": 79198,
            "USER_ID": 2839,
            "DATE_REMIND": "2006-09-25",
            "NOTE": 0,
            "CT": 43,
            "SEND_NOTE": null,
            "RH_ORDER": 2,
            "RH_AUTHOR": 481,
            "RH_CREATED": null,
            "RH_FINAL_DATE": null,
            "RH_NOTE": null,
            "RH_RHB_ID": null,
            "RH_DATE_ACK": null,
            "RH_DR_ID": null,
            "RH_PROVIDER_USER_ID": null,
            "items": [
                {
                    "ID": 4109519,
                    "ID_REMIND": 1839460,
                    "AMOUNT": "2045.3884",
                    "MONTH": "12",
                    "YEAR": "2021",
                    "USER_SERVICE_ID": 1839,
                    "RB_PAID": "4426.6266",
                    "RB_MATURITY": null,
                    "RB_DELAY": null,
                    "RB_ITD_ID": 35644,
                    "RB_ITD_ADVANCE_ID": 0,
                    "RB_SA_BASE_ID": null
                }
            ]
        },
        {
            "ID": 1839461,
            "RH_DOC_ID": 8317,
            "USER_ID": 7018,
            "DATE_REMIND": "2009-07-27",
            "NOTE": 0,
            "CT": 38,
            "SEND_NOTE": null,
            "RH_ORDER": 2,
            "RH_AUTHOR": 94,
            "RH_CREATED": null,
            "RH_FINAL_DATE": null,
            "RH_NOTE": null,
            "RH_RHB_ID": null,
            "RH_DATE_ACK": null,
            "RH_DR_ID": null,
            "RH_PROVIDER_USER_ID": null,
            "items": [
                {
                    "ID": 4109520,
                    "ID_REMIND": 1839461,
                    "AMOUNT": "2384.8442",
                    "MONTH": "02",
                    "YEAR": "2020",
                    "USER_SERVICE_ID": 5040,
                    "RB_PAID": "3688.2401",
                    "RB_MATURITY": null,
                    "RB_DELAY": null,
                    "RB_ITD_ID": 20535,
                    "RB_ITD_ADVANCE_ID": 0,
                    "RB_SA_BASE_ID": null
                }
            ]
        }
    ]
}

Request      

GET api/v3/reminders

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of items per page. Example: 10

page   integer  optional    

Page number. Example: 1

ids   string  optional    

Filter by comma-separated reminder IDs. Example: 1,2,3

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Example: 1,2,3

customer   integer  optional    

Filter by customer (user) ID. Example: 345

batch   integer  optional    

Filter by reminder batch ID. Example: 100

debt_recovery   integer  optional    

Filter by debt recovery process ID. Example: 50

provider   integer  optional    

Filter by provider (user) ID. Example: 200

date_from   string  optional    

Filter reminders issued on or after this date (YYYY-MM-DD). Applies to DATE_REMIND. Example: 2024-01-01

date_to   string  optional    

Filter reminders issued on or before this date (YYYY-MM-DD). Applies to DATE_REMIND. Example: 2024-12-31

order   integer  optional    

Filter by reminder sequence number (1st, 2nd, etc.). Example: 1

year   integer  optional    

Filter by year extracted from DATE_REMIND. Example: 2024

Response

Response Fields

data   object     
ID   integer     

Unique reminder identifier (primary key).

RH_DOC_ID   integer     

Reminder document number.

DATE_REMIND   string     

Reminder issue date (YYYY-MM-DD).

RH_ORDER   integer     

Reminder sequence number (1st, 2nd, etc.).

USER_ID   integer     

Customer (user) ID. See GET /v3/customers/{id}.

CT   integer     

Location / installation CT ID.

customer_name   string     

Full customer name (computed via get_user_name).

amount_tax   number     

Total prescription amount (computed via reminders_sum_get).

amount_paid   number     

Amount paid to date (computed via reminders_sum_pay_get).

amount_saldo   number     

Remaining balance: amount_tax minus amount_paid.

NOTE   integer     

Legacy note code.

SEND_NOTE   string     

Note displayed on the reminder document.

RH_NOTE   string     

Extended internal note.

RH_FINAL_DATE   string     

Payment due date (YYYY-MM-DD).

RH_CREATED   string     

Creation timestamp (YYYY-MM-DD HH:MM:SS).

RH_DATE_ACK   string     

Acknowledgment timestamp.

RH_AUTHOR   integer     

Login ID of the reminder creator.

RH_PROVIDER_USER_ID   integer     

Provider (user) ID.

RH_RHB_ID   integer     

Reminder batch ID. See GET /v3/reminder-batches/{id}.

RH_DR_ID   integer     

Debt recovery process ID. See GET /v3/debt-recovery-processes/{id}.

items   object[]     

Reminder line items (always included).
ID   integer     

Unique item identifier (primary key).

ID_REMIND   integer     

Parent reminder ID.

AMOUNT   number     

Prescription amount.

MONTH   string     

Billing month (2-char).

YEAR   string     

Billing year (4-char).

USER_SERVICE_ID   integer     

Customer service ID.

RB_PAID   number     

Amount already paid at time of reminder issuance.

RB_MATURITY   string     

Payment maturity date (YYYY-MM-DD).

RB_DELAY   integer     

Days overdue.

RB_ITD_ID   integer     

Internal tax document ID.

RB_ITD_ADVANCE_ID   integer     

Internal tax document advance ID.

RB_SA_BASE_ID   integer     

Base service agreement ID.

Get Reminder

requires authentication

Returns a single reminder by ID with computed financial data and line items.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/reminders/1732" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/reminders/1732"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "ID": 1839462,
        "RH_DOC_ID": 79198,
        "USER_ID": 2839,
        "DATE_REMIND": "2006-09-25",
        "NOTE": 0,
        "CT": 43,
        "SEND_NOTE": null,
        "RH_ORDER": 2,
        "RH_AUTHOR": 481,
        "RH_CREATED": null,
        "RH_FINAL_DATE": null,
        "RH_NOTE": null,
        "RH_RHB_ID": null,
        "RH_DATE_ACK": null,
        "RH_DR_ID": null,
        "RH_PROVIDER_USER_ID": null,
        "items": [
            {
                "ID": 4109521,
                "ID_REMIND": 1839462,
                "AMOUNT": "2045.3884",
                "MONTH": "12",
                "YEAR": "2021",
                "USER_SERVICE_ID": 1839,
                "RB_PAID": "4426.6266",
                "RB_MATURITY": null,
                "RB_DELAY": null,
                "RB_ITD_ID": 35644,
                "RB_ITD_ADVANCE_ID": 0,
                "RB_SA_BASE_ID": null
            }
        ]
    }
}

Request      

GET api/v3/reminders/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the reminder. Example: 1732

Response

Response Fields

data   object     
ID   integer     

Unique reminder identifier (primary key).

RH_DOC_ID   integer     

Reminder document number.

DATE_REMIND   string     

Reminder issue date (YYYY-MM-DD).

RH_ORDER   integer     

Reminder sequence number (1st, 2nd, etc.).

USER_ID   integer     

Customer (user) ID. See GET /v3/customers/{id}.

CT   integer     

Location / installation CT ID.

customer_name   string     

Full customer name (computed via get_user_name).

amount_tax   number     

Total prescription amount (computed via reminders_sum_get).

amount_paid   number     

Amount paid to date (computed via reminders_sum_pay_get).

amount_saldo   number     

Remaining balance: amount_tax minus amount_paid.

NOTE   integer     

Legacy note code.

SEND_NOTE   string     

Note displayed on the reminder document.

RH_NOTE   string     

Extended internal note.

RH_FINAL_DATE   string     

Payment due date (YYYY-MM-DD).

RH_CREATED   string     

Creation timestamp (YYYY-MM-DD HH:MM:SS).

RH_DATE_ACK   string     

Acknowledgment timestamp.

RH_AUTHOR   integer     

Login ID of the reminder creator.

RH_PROVIDER_USER_ID   integer     

Provider (user) ID.

RH_RHB_ID   integer     

Reminder batch ID. See GET /v3/reminder-batches/{id}.

RH_DR_ID   integer     

Debt recovery process ID. See GET /v3/debt-recovery-processes/{id}.

items   object[]     

Reminder line items (always included).
ID   integer     

Unique item identifier (primary key).

ID_REMIND   integer     

Parent reminder ID.

AMOUNT   number     

Prescription amount.

MONTH   string     

Billing month (2-char).

YEAR   string     

Billing year (4-char).

USER_SERVICE_ID   integer     

Customer service ID.

RB_PAID   number     

Amount already paid at time of reminder issuance.

RB_MATURITY   string     

Payment maturity date (YYYY-MM-DD).

RB_DELAY   integer     

Days overdue.

RB_ITD_ID   integer     

Internal tax document ID.

RB_ITD_ADVANCE_ID   integer     

Internal tax document advance ID.

RB_SA_BASE_ID   integer     

Base service agreement ID.

Right Definitions

List Right Definitions

requires authentication 

Returns a paginated list of all right definitions (global codelist).
No CT or partner scoping — this is a system-wide catalogue of available rights.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/rights-definitions?per_page=15&page=1&ids=1%2C2%2C3&search=MODULE" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/rights-definitions"
);

const params = {
    "per_page": "15",
    "page": "1",
    "ids": "1,2,3",
    "search": "MODULE",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "RD_ID": 3694,
            "RD_NAME": "adipisci-quidem-nostrum",
            "RD_LEVEL": 10,
            "RD_ROLES_ACCESS": 1,
            "RD_DISTINCT": 1,
            "RD_TYPE": "MODULE",
            "RD_DOMAIN": null,
            "RD_SETTING": 0,
            "RD_CATEGORY": "OTHER"
        },
        {
            "RD_ID": 3695,
            "RD_NAME": "omnis-autem",
            "RD_LEVEL": 10,
            "RD_ROLES_ACCESS": 1,
            "RD_DISTINCT": 1,
            "RD_TYPE": "SELECT",
            "RD_DOMAIN": null,
            "RD_SETTING": 0,
            "RD_CATEGORY": "OTHER"
        }
    ]
}

Request      

GET api/v3/rights-definitions

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of results per page. Example: 15

page   integer  optional    

Page number. Example: 1

ids   string  optional    

Filter by comma-separated right definition IDs. Example: 1,2,3

search   string  optional    

Search in right name (RD_NAME). Example: MODULE

Response

Response Fields

data   object     
RD_ID   integer     

Unique right definition identifier (primary key).

RD_NAME   string     

Unique right name/key.

RD_TYPE   string     

Data type of the right value.

Must be one of:
  • BOOL
  • LOCID
  • NODEID
  • NUM
  • PAID
  • SELECT
  • STRING
  • MENUID
  • MODULE
  • MODULEVIEW
  • GROUP
  • CLASS_DEF
  • RADIOGROUP
  • TEXT
RD_DOMAIN   string     

Comma-separated list of allowed values (domain).

RD_CATEGORY   string     

Right category.

Must be one of:
  • OTHER
  • OBJECT
  • ACTION
RD_LEVEL   integer     

Visibility level. Only operators with equal or higher level can see/assign this right.

RD_ROLES_ACCESS   integer     

Flag: right is assignable via roles (0/1).

RD_DISTINCT   integer     

Flag: distinct behavior for value deduplication (0/1).

RD_SETTING   integer     

Flag: system setting right (0/1).

SIPO

List SIPO Contracts

requires authentication

Returns a paginated list of SIPO / INKASO collection contracts. Each contract includes its assigned business locations.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/sipo-contracts?per_page=10&page=1&ids=1%2C2%2C3&cts=12%2C14&collection_type=SIPO" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/sipo-contracts"
);

const params = {
    "per_page": "10",
    "page": "1",
    "ids": "1,2,3",
    "cts": "12,14",
    "collection_type": "SIPO",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "SCL_ID": 73,
            "SCL_ORGNUM": 857680,
            "SCL_EXPORT_TYPE": "FULL",
            "SCL_PA_ID": 599,
            "SCL_LIMIT_DAY": 26,
            "SCL_NOTE": "Qui commodi incidunt iure odit.",
            "SCL_CP_ID": 64,
            "SCL_COLLECTION_TYPE": "SIPO",
            "SCL_MATURITY": 45,
            "SCL_CREATED": "2026-02-04 07:48:07",
            "SCL_CREATE_L_ID": 247,
            "locations": [
                {
                    "SCLL_ID": 159,
                    "SCLL_SCL_ID": 73,
                    "SCLL_CT": 66,
                    "SCLL_PROVIDER_USER_ID": null
                }
            ]
        },
        {
            "SCL_ID": 74,
            "SCL_ORGNUM": 469606,
            "SCL_EXPORT_TYPE": "FULL",
            "SCL_PA_ID": 994,
            "SCL_LIMIT_DAY": 16,
            "SCL_NOTE": "Dolores enim non facere tempora.",
            "SCL_CP_ID": 173,
            "SCL_COLLECTION_TYPE": "FETCH",
            "SCL_MATURITY": 51,
            "SCL_CREATED": "2026-02-09 05:42:05",
            "SCL_CREATE_L_ID": 292,
            "locations": [
                {
                    "SCLL_ID": 160,
                    "SCLL_SCL_ID": 74,
                    "SCLL_CT": 29,
                    "SCLL_PROVIDER_USER_ID": 89143
                }
            ]
        }
    ]
}

Request      

GET api/v3/sipo-contracts

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of items per page. Example: 10

page   integer  optional    

Page number. Example: 1

ids   string  optional    

Filter by comma-separated contract IDs. Example: 1,2,3

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Example: 12,14

collection_type   string  optional    

Filter by collection type. Example: SIPO

Response

Response Fields

data   object     
SCL_ID   integer     

Unique contract ID.

SCL_ORGNUM   integer     

Organization number (6-digit, Czech Post). Relevant only for SIPO type.

SCL_EXPORT_TYPE   string     

Export type.

Must be one of:
  • FULL
  • CHANGES
SCL_PA_ID   integer     

Payment account ID. Relevant only for SIPO type.

SCL_LIMIT_DAY   integer     

Monthly deadline day for SIPO prescriptions (1–28).

SCL_NOTE   string     

Note / description.

SCL_CP_ID   integer     

CIBS partner (operator) ID.

SCL_COLLECTION_TYPE   string     

Collection type.

Must be one of:
  • SIPO
  • FETCH
SCL_MATURITY   integer     

Maturity days for money-in-transit calculation.

SCL_CREATED   string     

Creation timestamp.

SCL_CREATE_L_ID   integer     

Login ID of the creator.

locations   object[]     

Assigned business locations.
SCLL_ID   integer     

Location assignment record ID.

SCLL_SCL_ID   integer     

Parent contract ID. See GET /v3/sipo-contracts/{id}.

SCLL_CT   integer     

Location (installation) ID.

SCLL_PROVIDER_USER_ID   integer     

Provider customer ID for this location. See GET /v3/customers/{id}.

Get SIPO Contract

requires authentication

Returns a single SIPO / INKASO collection contract by ID, including its assigned business locations.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/sipo-contracts/13" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/sipo-contracts/13"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "SCL_ID": 75,
        "SCL_ORGNUM": 857680,
        "SCL_EXPORT_TYPE": "FULL",
        "SCL_PA_ID": 997,
        "SCL_LIMIT_DAY": 26,
        "SCL_NOTE": "Qui commodi incidunt iure odit.",
        "SCL_CP_ID": 82,
        "SCL_COLLECTION_TYPE": "SIPO",
        "SCL_MATURITY": 45,
        "SCL_CREATED": "2026-02-04 07:48:07",
        "SCL_CREATE_L_ID": 247,
        "locations": [
            {
                "SCLL_ID": 161,
                "SCLL_SCL_ID": 75,
                "SCLL_CT": 97,
                "SCLL_PROVIDER_USER_ID": null
            }
        ]
    }
}

Request      

GET api/v3/sipo-contracts/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the sipo contract. Example: 13

Response

Response Fields

data   object     
SCL_ID   integer     

Unique contract ID.

SCL_ORGNUM   integer     

Organization number (6-digit, Czech Post). Relevant only for SIPO type.

SCL_EXPORT_TYPE   string     

Export type.

Must be one of:
  • FULL
  • CHANGES
SCL_PA_ID   integer     

Payment account ID. Relevant only for SIPO type.

SCL_LIMIT_DAY   integer     

Monthly deadline day for SIPO prescriptions (1–28).

SCL_NOTE   string     

Note / description.

SCL_CP_ID   integer     

CIBS partner (operator) ID.

SCL_COLLECTION_TYPE   string     

Collection type.

Must be one of:
  • SIPO
  • FETCH
SCL_MATURITY   integer     

Maturity days for money-in-transit calculation.

SCL_CREATED   string     

Creation timestamp.

SCL_CREATE_L_ID   integer     

Login ID of the creator.

locations   object[]     

Assigned business locations.
SCLL_ID   integer     

Location assignment record ID.

SCLL_SCL_ID   integer     

Parent contract ID. See GET /v3/sipo-contracts/{id}.

SCLL_CT   integer     

Location (installation) ID.

SCLL_PROVIDER_USER_ID   integer     

Provider customer ID for this location. See GET /v3/customers/{id}.

List SIPO Lists

requires authentication

Returns a paginated list of generated SIPO / INKASO prescription lists.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/sipo-lists?per_page=10&page=1&ids=100%2C200&cts=12%2C14&contract=1&year=2024&month=6&date_from=2024-01-01&date_to=2024-12-31&collection_type=SIPO" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/sipo-lists"
);

const params = {
    "per_page": "10",
    "page": "1",
    "ids": "100,200",
    "cts": "12,14",
    "contract": "1",
    "year": "2024",
    "month": "6",
    "date_from": "2024-01-01",
    "date_to": "2024-12-31",
    "collection_type": "SIPO",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "SL_ID": 20859,
            "SL_DATE": "1981-11-24",
            "SL_MONTH": 1,
            "SL_YEAR": 2024,
            "SL_CT": 556,
            "SL_CREATION": "2026-03-08 11:29:09",
            "SL_AUTHOR": 5485,
            "SL_TYPE": "FULL",
            "SL_SCL_ID": null,
            "SL_COLLECTION_TYPE": "SIPO",
            "SL_DUE_DATE": null,
            "SL_PA_ID": 1839,
            "SL_DATE_M": "1971-11-16",
            "SL_PROVIDER_USER_ID": null
        },
        {
            "SL_ID": 20860,
            "SL_DATE": "2018-11-23",
            "SL_MONTH": 7,
            "SL_YEAR": 2021,
            "SL_CT": 383,
            "SL_CREATION": "2026-02-09 00:40:29",
            "SL_AUTHOR": 4639,
            "SL_TYPE": "FULL",
            "SL_SCL_ID": null,
            "SL_COLLECTION_TYPE": "FETCH",
            "SL_DUE_DATE": "2020-03-13",
            "SL_PA_ID": null,
            "SL_DATE_M": "2023-08-06",
            "SL_PROVIDER_USER_ID": 79168
        }
    ]
}

Request      

GET api/v3/sipo-lists

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of items per page. Example: 10

page   integer  optional    

Page number. Example: 1

ids   string  optional    

Filter by comma-separated SIPO list IDs. Example: 100,200

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Example: 12,14

contract   integer  optional    

Filter by contract ID (SL_SCL_ID). Example: 1

year   integer  optional    

Filter by year. Example: 2024

month   integer  optional    

Filter by month (1–12). Example: 6

date_from   string  optional    

Filter lists on or after this date (YYYY-MM-DD). Example: 2024-01-01

date_to   string  optional    

Filter lists on or before this date (YYYY-MM-DD). Example: 2024-12-31

collection_type   string  optional    

Filter by collection type. Example: SIPO

Response

Response Fields

data   object     
SL_ID   integer     

Unique SIPO list ID.

SL_DATE   string     

List date (YYYY-MM-DD).

SL_MONTH   integer     

Month of the prescription period.

SL_YEAR   integer     

Year of the prescription period.

SL_CT   integer     

Location (installation) ID.

SL_CREATION   string     

Creation timestamp.

SL_AUTHOR   integer     

Author (operator login) ID.

SL_TYPE   string     

Export type.

Must be one of:
  • FULL
  • CHANGES
SL_SCL_ID   integer     

Parent contract ID.

SL_COLLECTION_TYPE   string     

Collection type.

Must be one of:
  • SIPO
  • FETCH
SL_DUE_DATE   string     

Due date (YYYY-MM-DD).

SL_PA_ID   integer     

Payment account ID.

SL_DATE_M   string     

Maturity reference date (YYYY-MM-DD).

SL_PROVIDER_USER_ID   integer     

Provider user ID.

Get SIPO List

requires authentication

Returns a single SIPO / INKASO prescription list by ID.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/sipo-lists/15" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/sipo-lists/15"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "SL_ID": 20861,
        "SL_DATE": "1981-11-24",
        "SL_MONTH": 1,
        "SL_YEAR": 2024,
        "SL_CT": 556,
        "SL_CREATION": "2026-03-08 11:29:09",
        "SL_AUTHOR": 5485,
        "SL_TYPE": "FULL",
        "SL_SCL_ID": null,
        "SL_COLLECTION_TYPE": "SIPO",
        "SL_DUE_DATE": null,
        "SL_PA_ID": 1839,
        "SL_DATE_M": "1971-11-16",
        "SL_PROVIDER_USER_ID": null
    }
}

Request      

GET api/v3/sipo-lists/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the sipo list. Example: 15

Response

Response Fields

data   object     
SL_ID   integer     

Unique SIPO list ID.

SL_DATE   string     

List date (YYYY-MM-DD).

SL_MONTH   integer     

Month of the prescription period.

SL_YEAR   integer     

Year of the prescription period.

SL_CT   integer     

Location (installation) ID.

SL_CREATION   string     

Creation timestamp.

SL_AUTHOR   integer     

Author (operator login) ID.

SL_TYPE   string     

Export type.

Must be one of:
  • FULL
  • CHANGES
SL_SCL_ID   integer     

Parent contract ID.

SL_COLLECTION_TYPE   string     

Collection type.

Must be one of:
  • SIPO
  • FETCH
SL_DUE_DATE   string     

Due date (YYYY-MM-DD).

SL_PA_ID   integer     

Payment account ID.

SL_DATE_M   string     

Maturity reference date (YYYY-MM-DD).

SL_PROVIDER_USER_ID   integer     

Provider user ID.

List SIPO Items

requires authentication

Returns a paginated list of SIPO / INKASO prescription line items. At least one of the following filters must be provided: sipo_list, customer. Without a narrowing filter the endpoint returns HTTP 422.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/sipo-items?per_page=10&page=1&ids=1000%2C2000&cts=12%2C14&sipo_list=100&customer=345" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/sipo-items"
);

const params = {
    "per_page": "10",
    "page": "1",
    "ids": "1000,2000",
    "cts": "12,14",
    "sipo_list": "100",
    "customer": "345",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "SD_ID": 10028765,
            "SD_SL_ID": 4609,
            "SD_USER_ID": 419465,
            "SD_SIPO_NUM": null,
            "SD_SIPO_CODE": "wp",
            "SD_PRICE": "66203084.7019",
            "SD_EXPORT_TYPE": "Z",
            "SD_TYPE": 709,
            "SD_TEXT": null,
            "SD_ACC_PRE_NUMBER": null,
            "SD_ACC_NUMBER": null,
            "SD_ACC_BANK": null,
            "SD_ACC_SPECSYM": null,
            "SD_MATURITY": "1990-02-03",
            "SD_EU": null,
            "SD_TAX": null,
            "SD_PAY": null,
            "SD_TAX_ACTUAL": null,
            "SD_FUNDS_IN_TRANSIT": null,
            "SD_OVERPAYMENT": null
        },
        {
            "SD_ID": 10028766,
            "SD_SL_ID": 20054,
            "SD_USER_ID": 492863,
            "SD_SIPO_NUM": 3390204808,
            "SD_SIPO_CODE": "cp",
            "SD_PRICE": "54565323.4621",
            "SD_EXPORT_TYPE": "N",
            "SD_TYPE": null,
            "SD_TEXT": null,
            "SD_ACC_PRE_NUMBER": null,
            "SD_ACC_NUMBER": null,
            "SD_ACC_BANK": null,
            "SD_ACC_SPECSYM": null,
            "SD_MATURITY": "2019-08-30",
            "SD_EU": null,
            "SD_TAX": null,
            "SD_PAY": null,
            "SD_TAX_ACTUAL": null,
            "SD_FUNDS_IN_TRANSIT": null,
            "SD_OVERPAYMENT": null
        }
    ]
}

Request      

GET api/v3/sipo-items

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of items per page. Example: 10

page   integer  optional    

Page number. Example: 1

ids   string  optional    

Filter by comma-separated item IDs. Example: 1000,2000

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Example: 12,14

sipo_list   integer  optional    

Filter by SIPO list ID. At least one of sipo_list or customer is required. Example: 100

customer   integer  optional    

Filter by customer (user) ID. At least one of sipo_list or customer is required. Example: 345

Response

Response Fields

data   object     
SD_ID   integer     

Unique item ID.

SD_SL_ID   integer     

Parent SIPO list ID.

SD_USER_ID   integer     

Customer (user) ID.

SD_SIPO_NUM   integer     

SIPO connector number.

SD_SIPO_CODE   string     

SIPO code (2-char).

SD_PRICE   string     

Price amount (decimal).

SD_EXPORT_TYPE   string     

Export type flag (1-char).

SD_TYPE   integer     

Item type code.

SD_TEXT   string     

Item description text.

SD_ACC_PRE_NUMBER   integer     

Account prefix number.

SD_ACC_NUMBER   integer     

Account number.

SD_ACC_BANK   integer     

Bank code.

SD_ACC_SPECSYM   integer     

Specific symbol.

SD_MATURITY   string     

Maturity date (YYYY-MM-DD).

SD_EU   integer     

EU flag.

SD_TAX   string     

Tax amount (decimal).

SD_PAY   string     

Payment amount (decimal).

SD_TAX_ACTUAL   string     

Actual tax amount (decimal).

SD_FUNDS_IN_TRANSIT   string     

Funds in transit amount (decimal).

SD_OVERPAYMENT   string     

Overpayment amount (decimal).

Service Definitions

List Service Definitions

requires authentication 

Returns a paginated list of service definitions.
By default only enabled definitions are returned (SN_DISABLED=0).
Use the `disabled` filter to include/filter disabled definitions.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/service-definitions?ids=1%2C2%2C3&cts=1%2C2%2C3&disabled=true&class=5&kind=SCF_DATA%2CSCF_VOIP&base_service=10&search=internet" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/service-definitions"
);

const params = {
    "ids": "1,2,3",
    "cts": "1,2,3",
    "disabled": "true",
    "class": "5",
    "kind": "SCF_DATA,SCF_VOIP",
    "base_service": "10",
    "search": "internet",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "ID": 185286,
            "NAME": "nostrum qui commodi",
            "PRICE": "7404.2747",
            "SN_SUGGEST_PRICE": "0.0000",
            "CLASS": "03",
            "TYPE": "S",
            "SN_DEP_TYPE": "dependent",
            "NOTE": null,
            "CT": "027",
            "SWITCH_TYPE": 0,
            "ACC_GROUP_ID": "0045",
            "SN_DISABLED": 0,
            "SN_START_RESTRICTION": "NONE",
            "SN_END_RESTRICTION": "NONE",
            "SN_ACCOUNTFROM_RESTRICTION": "NONE",
            "SN_ACCOUNTTO_RESTRICTION": "NONE",
            "SN_ACCOUNTCHANGE_RESTRICTION": "NONE",
            "SN_TL_ID": 0,
            "SN_TG_ID": null,
            "SN_WEB_ENABLE": 0,
            "SN_PRICE_WO_VAT": "8852.3678",
            "SN_PRICE_VAT": "275.3415",
            "SN_PRICE_ROUND": null,
            "SN_VAR_PRICE_ENABLED": 0,
            "SN_MIN_BOND": 0,
            "SN_FIXED_MONTHS": 0,
            "SN_PERIOD": "none",
            "SN_BP_ID": "000059",
            "SN_FIXED_BP": 0,
            "SN_CODE": null,
            "SN_DISABLE_ATTACH_ALL": 0,
            "SN_VAT_BOTTOMUP": 0,
            "SN_EU_NAME": null,
            "SN_INV_VAR_PRICE": null,
            "SN_TYPE": "S",
            "SN_UNIT_PACK": null,
            "SN_BARCODE": null,
            "SN_WARRANTY_PERIOD": null,
            "SN_VAR_SYMBOL_TMPL": null,
            "SN_UNICREDIT_ASSIGN": "never",
            "SN_PROVISIONING": 0,
            "SN_TRANSFER_SPLITTED": 0,
            "SN_MOVE_SPLITTED": 0,
            "SN_PRICE_CHANGE": 3,
            "SN_POINTS_DISCOUNT": null,
            "SN_POINTS_DISCOUNT_VAT": null,
            "SN_POINTS_DISCOUNT_WO_VAT": null,
            "SN_POINTS_PRICE": null,
            "SN_POINTS_REWARD": null,
            "SN_UNICREDIT_TYPE": null,
            "SN_PRICE_CALC": "LOC_PRICE",
            "SN_TRANSPORT": 0,
            "SN_FORCE_MOVE_ON_TRANSFER": 0,
            "SN_DELIVERY": null,
            "SN_NAME_PART": 0,
            "SN_PRICE_TOTAL_PERIOD": 0,
            "SN_PENALTY": null,
            "SN_WAREHOUSE": null,
            "SN_SC_AVAIL_TYPE": null,
            "SN_SC_AVAIL_TO": null,
            "SN_PREMISE_AVAIL_TYPE": null,
            "SN_CACHE_WAREHOUSE_AVAILABLE": 0,
            "SN_CREATED": null,
            "SN_CREATED_L_ID": null,
            "SN_CHANGED": null,
            "SN_CHANGED_L_ID": null,
            "SN_WORK": 0,
            "SN_LAST_CHANGE": null,
            "ACC_GROUP_ID_OLD": null,
            "ACC_GROUP_ID_NEW": null,
            "params": [
                {
                    "ID": 1867326,
                    "SERVICES_NAME_ID": 185286,
                    "CLASS_PAR_NAME": "speed_download",
                    "SNC_PAR_INDEX": null,
                    "CLASS_PAR_VALUE": null,
                    "SNC_DOMAIN": null,
                    "SNC_DOMAIN_EU": null,
                    "SNC_VALID_FROM": null,
                    "SNC_VALID_TO": null,
                    "SNC_EU_VISIBLE": 1
                }
            ]
        },
        {
            "ID": 185287,
            "NAME": "aut dolores enim",
            "PRICE": "7783.7442",
            "SN_SUGGEST_PRICE": "0.0000",
            "CLASS": "08",
            "TYPE": "S",
            "SN_DEP_TYPE": "none",
            "NOTE": null,
            "CT": "023",
            "SWITCH_TYPE": 0,
            "ACC_GROUP_ID": "0091",
            "SN_DISABLED": 0,
            "SN_START_RESTRICTION": "NONE",
            "SN_END_RESTRICTION": "NONE",
            "SN_ACCOUNTFROM_RESTRICTION": "NONE",
            "SN_ACCOUNTTO_RESTRICTION": "NONE",
            "SN_ACCOUNTCHANGE_RESTRICTION": "NONE",
            "SN_TL_ID": 0,
            "SN_TG_ID": null,
            "SN_WEB_ENABLE": 0,
            "SN_PRICE_WO_VAT": "8661.9358",
            "SN_PRICE_VAT": "7874.8594",
            "SN_PRICE_ROUND": null,
            "SN_VAR_PRICE_ENABLED": 0,
            "SN_MIN_BOND": 0,
            "SN_FIXED_MONTHS": 0,
            "SN_PERIOD": "none",
            "SN_BP_ID": "000024",
            "SN_FIXED_BP": 0,
            "SN_CODE": null,
            "SN_DISABLE_ATTACH_ALL": 0,
            "SN_VAT_BOTTOMUP": 0,
            "SN_EU_NAME": null,
            "SN_INV_VAR_PRICE": null,
            "SN_TYPE": "S",
            "SN_UNIT_PACK": null,
            "SN_BARCODE": null,
            "SN_WARRANTY_PERIOD": null,
            "SN_VAR_SYMBOL_TMPL": null,
            "SN_UNICREDIT_ASSIGN": "never",
            "SN_PROVISIONING": 0,
            "SN_TRANSFER_SPLITTED": 0,
            "SN_MOVE_SPLITTED": 0,
            "SN_PRICE_CHANGE": 3,
            "SN_POINTS_DISCOUNT": null,
            "SN_POINTS_DISCOUNT_VAT": null,
            "SN_POINTS_DISCOUNT_WO_VAT": null,
            "SN_POINTS_PRICE": null,
            "SN_POINTS_REWARD": null,
            "SN_UNICREDIT_TYPE": null,
            "SN_PRICE_CALC": "LOC_PRICE",
            "SN_TRANSPORT": 0,
            "SN_FORCE_MOVE_ON_TRANSFER": 0,
            "SN_DELIVERY": null,
            "SN_NAME_PART": 0,
            "SN_PRICE_TOTAL_PERIOD": 0,
            "SN_PENALTY": null,
            "SN_WAREHOUSE": null,
            "SN_SC_AVAIL_TYPE": null,
            "SN_SC_AVAIL_TO": null,
            "SN_PREMISE_AVAIL_TYPE": null,
            "SN_CACHE_WAREHOUSE_AVAILABLE": 0,
            "SN_CREATED": null,
            "SN_CREATED_L_ID": null,
            "SN_CHANGED": null,
            "SN_CHANGED_L_ID": null,
            "SN_WORK": 0,
            "SN_LAST_CHANGE": null,
            "ACC_GROUP_ID_OLD": null,
            "ACC_GROUP_ID_NEW": null,
            "params": [
                {
                    "ID": 1867327,
                    "SERVICES_NAME_ID": 185287,
                    "CLASS_PAR_NAME": "speed_upload",
                    "SNC_PAR_INDEX": null,
                    "CLASS_PAR_VALUE": null,
                    "SNC_DOMAIN": null,
                    "SNC_DOMAIN_EU": null,
                    "SNC_VALID_FROM": null,
                    "SNC_VALID_TO": null,
                    "SNC_EU_VISIBLE": 1
                }
            ]
        }
    ]
}

Request      

GET api/v3/service-definitions

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

ids   string  optional    

Filter by comma-separated IDs Example: 1,2,3

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Example: 1,2,3

disabled   string  optional    

Filter by disabled status. When true, return only disabled. When not set, return only enabled. Example: true

class   integer  optional    

Filter by service class ID Example: 5

kind   string  optional    

Filter by service class flag(s) (comma-separated). Valid: SCF_DATA, SCF_TV_ANALOG, SCF_TV_DVB, SCF_TV_IPTV, SCF_VOIP, SCF_GSM, SCF_SMS, SCF_WHOLESALE, SCF_DATA_LINK, SCF_EMAIL, SCF_VPS, SCF_LOC, SCF_3S, SCF_LEASE, SCF_LOAN Example: SCF_DATA,SCF_VOIP

base_service   integer  optional    

Filter definitions that can be dependent on the given base service ID Example: 10

search   string  optional    

Search by service name (NAME) or end-user name (SN_EU_NAME) Example: internet

Response

Response Fields

data   object     
ID   integer     

Service definition ID (primary key).

NAME   string     

Service definition name.

SN_CODE   string     

Service code identifier.

SN_EU_NAME   string     

Alternative service name displayed on the end-user (SelfCare) portal.

SN_TYPE   string     

Definition type. 'S' = service, 'P' = product.

Must be one of:
  • S
  • P
TYPE   string     

Service periodicity type. 'M' = periodic (monthly), 'S' = one-time. References services_type.

SN_DEP_TYPE   string     

Service position in hierarchy. 'none' = base service, 'dependent' = dependent (child) service.

Must be one of:
  • none
  • dependent
CLASS   integer     

Service class ID (references services_class). Determines the service category and capabilities.

CT   integer     

Location (CT) ID. Identifies which Mango location this definition belongs to.

PRICE   number     

Price including VAT (one-time or per month).

SN_PRICE_WO_VAT   number     

Price excluding VAT.

SN_PRICE_VAT   number     

VAT amount (one-time or per month).

SN_PRICE_ROUND   number     

Rounding amount when computing price from the price without VAT.

SN_SUGGEST_PRICE   number     

Suggested price with VAT, used when proposing payment amounts (e.g. when closing resource tasks).

SN_VAR_PRICE_ENABLED   integer     

Variable price flag. 1 = service has a variable (consumption-based) price component.

SN_INV_VAR_PRICE   string     

Alternative label for the variable price component on printed invoices.

SN_VAT_BOTTOMUP   integer     

VAT calculation direction. 0 = price entered with VAT (top-down), 1 = price entered without VAT (bottom-up).

SN_PRICE_CALC   string     

Price calculation type. 'LOC_PRICE' = location/time-dependent price (default), 'CALCULATION' = volume/delivery-based calculation, 'UNIT' = unit price with quantity recalculation.

Must be one of:
  • LOC_PRICE
  • CALCULATION
  • UNIT
SN_PRICE_CHANGE   integer     

Price change permission level. Controls whether and how the price can be changed on active services.

SN_PRICE_TOTAL_PERIOD   integer     

Price total period flag. Controls whether the price is shown for the total period.

SN_TL_ID   integer     

VAT rate ID (references taxation_list). Defines the VAT percentage applied to this service.

SN_TG_ID   integer     

Tax group ID (references taxation_groups).

ACC_GROUP_ID   integer     

Accounting group ID (references acc_groups).

ACC_GROUP_ID_OLD   integer     

Previous accounting group ID (before the last change).

ACC_GROUP_ID_NEW   integer     

New accounting group ID (after the last change).

SN_PERIOD   string     

Billing period. Possible values: 'none', 'month', 'cquarter', 'chalfyear', 'cyear', 'cyears2', 'cyears3', 'cmonths18', 'vmonth', 'vquarter', 'vhalfyear', 'vyear', 'vyears2', 'vyears3', 'vmonths18', 'all', 'optional'. Prefix 'c' = calendar-aligned, 'v' = anniversary-aligned, 'optional' = chosen at activation.

Must be one of:
  • all
  • chalfyear
  • cquarter
  • cyear
  • month
  • none
  • vhalfyear
  • vmonth
  • vquarter
  • vyear
  • cyears2
  • cyears3
  • cmonths18
  • vyears2
  • vyears3
  • vmonths18
  • optional
SN_BP_ID   integer     

Default billing plan ID (references billing_plans).

SN_FIXED_BP   integer     

Fixed billing plan flag. 1 = billing plan is enforced and cannot be changed by the operator.

SN_FIXED_MONTHS   integer     

Fixed contract duration in months. 0 = open-ended (no fixed term).

SN_MIN_BOND   integer     

Minimum commitment type (references code_list, CL_CATEGORY='SN_MIN_BOND'). 0 = no minimum commitment.

SN_DISABLE_ATTACH_ALL   integer     

Disable automatic payment matching flag. 1 = payments will not be matched to this service via automatic bulk matching to oldest debts.

SN_START_RESTRICTION   string     

Restriction for service provision start date. 'NONE' = no restriction, 'START_MONTH' = first day of month only, 'START_NEXT_MONTH' = first day of the following month only.

SN_END_RESTRICTION   string     

Restriction for service provision end date. 'NONE' = no restriction, 'END_MONTH' = last day of month only, 'END_NEXT_MONTH' = last day of the following month only.

SN_ACCOUNTFROM_RESTRICTION   string     

Restriction for billing start date. 'NONE' = no restriction, 'START_MONTH' = first day of month only, 'START_NEXT_MONTH' = first day of the following month only.

SN_ACCOUNTTO_RESTRICTION   string     

Restriction for billing end date. 'NONE' = no restriction, 'END_MONTH' = last day of month only, 'END_NEXT_MONTH' = last day of the following month only.

SN_ACCOUNTCHANGE_RESTRICTION   string     

Restriction for billing change date (price, payment, period). 'NONE' = no restriction, 'START_MONTH' = first day of month only, 'START_NEXT_MONTH' = first day of the following month only.

SWITCH_TYPE   integer     

Separate activation and provisioning flag. 0 = activation and provisioning happen together, 1 = separate steps.

SN_PROVISIONING   integer     

Provisioning flag. Controls whether automatic reminding and blocking is enabled for this service.

SN_TRANSFER_SPLITTED   integer     

Split transfer flag. 1 = provisioning is performed as a separate step during service transfer.

SN_MOVE_SPLITTED   integer     

Split move flag. 0 = the move operation is done at once, 1 = the move is initiated and completed as separate steps.

SN_FORCE_MOVE_ON_TRANSFER   integer     

Force move on transfer flag (relevant for dependent services only). 1 = this dependent service is always moved to the new base service during transfer.

SN_DISABLED   integer     

Disabled flag. 1 = service definition is no longer available in the current offer.

SN_PENALTY   integer     

Penalty flag. Controls early termination penalty for this service.

SN_UNIT_PACK   integer     

Packaging unit quantity (for products).

SN_BARCODE   integer     

Barcode number (EAN) for the product.

SN_WARRANTY_PERIOD   integer     

Warranty period in months (for products).

SN_TRANSPORT   integer     

Transport/shipping requirement flag. 1 = transport expedition is required for this service/product.

SN_DELIVERY   integer     

Delivery option flag.

SN_WAREHOUSE   integer     

Warehouse flag. Links this product to warehouse/stock management.

SN_CACHE_WAREHOUSE_AVAILABLE   integer     

Cached count of available products in the sales warehouse (warehouse_item_count minus warehouse_item_blocked).

SN_UNICREDIT_ASSIGN   string     

UniCredit assignment policy on activation. 'never' = cannot assign, 'default_yes' = can assign (default: yes), 'default_no' = can assign (default: no), 'always' = always assign.

Must be one of:
  • never
  • default_yes
  • default_no
  • always
SN_UNICREDIT_TYPE   string     

UniCredit type. 'finance' = financial credit, 'points' = loyalty points.

Must be one of:
  • finance
  • points
SN_POINTS_DISCOUNT   number     

Points discount price with VAT.

SN_POINTS_DISCOUNT_VAT   number     

Points discount VAT amount.

SN_POINTS_DISCOUNT_WO_VAT   number     

Points discount price without VAT.

SN_POINTS_PRICE   integer     

Price in loyalty points.

SN_POINTS_REWARD   integer     

Loyalty points reward for purchasing this service.

SN_WEB_ENABLE   integer     

Web visibility flag. 1 = service is visible on the external web price list.

SN_SC_AVAIL_TYPE   string     

SelfCare availability type. 'none' = not available, 'all' = available to all, 'user_group' = available to a specific customer group, 'user' = available to a specific customer.

Must be one of:
  • none
  • all
  • user_group
  • user
SN_SC_AVAIL_TO   integer     

SelfCare availability target ID. References a customer (USER_ID) or customer group (GROUP_ID) depending on SN_SC_AVAIL_TYPE.

SN_PREMISE_AVAIL_TYPE   string     

Premise availability type. 'all' = available at all premises, 'selected' = available only at selected premises.

Must be one of:
  • all
  • selected
SN_VAR_SYMBOL_TMPL   string     

Template for generating a variable symbol (payment identifier) upon service activation.

SN_NAME_PART   integer     

Name part flag. 1 = this service's name is used for naming the customer's overall service assembly.

SN_WORK   integer     

Work tracking flag. 1 = this service definition is used for time tracking / work management.

NOTE   string     

Note / remark for the service definition.

SN_CREATED   string     

Datetime when this service definition was created.

SN_CREATED_L_ID   integer     

Login ID of the user who created this service definition.

SN_CHANGED   string     

Datetime when this service definition was last modified.

SN_CHANGED_L_ID   integer     

Login ID of the user who last modified this service definition.

SN_LAST_CHANGE   string     

Datetime of the last change (auto-updated).

params   object[]     

Service definition parameters (configuration values). Array of ServiceDefinitionParam objects.
ID   integer     

Parameter record ID (primary key).

SERVICES_NAME_ID   integer     

Parent service definition ID. See GET /v3/service-definitions/{id}.

CLASS_PAR_NAME   string     

Parameter name. Identifies the service-class parameter (e.g. 'fup_enabled', 'transport_service').

SNC_PAR_INDEX   integer     

Parameter index. Used when the same parameter name has multiple indexed values (e.g. FUP levels).

CLASS_PAR_VALUE   string     

Parameter value. The configured value for this parameter on the service definition.

SNC_DOMAIN   string     

Domain (allowed values) for operator use. Comma-separated list of permitted values for this parameter.

SNC_DOMAIN_EU   string     

Domain (allowed values) for end-user (SelfCare) use. Comma-separated list of permitted values visible to customers.

SNC_VALID_FROM   string     

Validity start date (Y-m-d). Parameter is active from this date.

SNC_VALID_TO   string     

Validity end date (Y-m-d). Parameter is active until this date.

SNC_EU_VISIBLE   integer     

End-user visibility flag. 1 = parameter is visible on the SelfCare portal, 0 = hidden from end-users.

Get Service Definition

requires authentication 

Returns a single service definition by ID.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/service-definitions/19" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/service-definitions/19"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "ID": 185288,
        "NAME": "incidunt iure odit",
        "PRICE": "1119.7570",
        "SN_SUGGEST_PRICE": "0.0000",
        "CLASS": "05",
        "TYPE": "S",
        "SN_DEP_TYPE": "dependent",
        "NOTE": null,
        "CT": "076",
        "SWITCH_TYPE": 0,
        "ACC_GROUP_ID": "0066",
        "SN_DISABLED": 0,
        "SN_START_RESTRICTION": "NONE",
        "SN_END_RESTRICTION": "NONE",
        "SN_ACCOUNTFROM_RESTRICTION": "NONE",
        "SN_ACCOUNTTO_RESTRICTION": "NONE",
        "SN_ACCOUNTCHANGE_RESTRICTION": "NONE",
        "SN_TL_ID": 0,
        "SN_TG_ID": null,
        "SN_WEB_ENABLE": 0,
        "SN_PRICE_WO_VAT": "5455.9867",
        "SN_PRICE_VAT": "5813.9895",
        "SN_PRICE_ROUND": null,
        "SN_VAR_PRICE_ENABLED": 0,
        "SN_MIN_BOND": 0,
        "SN_FIXED_MONTHS": 0,
        "SN_PERIOD": "vyear",
        "SN_BP_ID": "000068",
        "SN_FIXED_BP": 0,
        "SN_CODE": null,
        "SN_DISABLE_ATTACH_ALL": 0,
        "SN_VAT_BOTTOMUP": 0,
        "SN_EU_NAME": null,
        "SN_INV_VAR_PRICE": null,
        "SN_TYPE": "S",
        "SN_UNIT_PACK": null,
        "SN_BARCODE": null,
        "SN_WARRANTY_PERIOD": null,
        "SN_VAR_SYMBOL_TMPL": null,
        "SN_UNICREDIT_ASSIGN": "never",
        "SN_PROVISIONING": 0,
        "SN_TRANSFER_SPLITTED": 0,
        "SN_MOVE_SPLITTED": 0,
        "SN_PRICE_CHANGE": 3,
        "SN_POINTS_DISCOUNT": null,
        "SN_POINTS_DISCOUNT_VAT": null,
        "SN_POINTS_DISCOUNT_WO_VAT": null,
        "SN_POINTS_PRICE": null,
        "SN_POINTS_REWARD": null,
        "SN_UNICREDIT_TYPE": null,
        "SN_PRICE_CALC": "LOC_PRICE",
        "SN_TRANSPORT": 0,
        "SN_FORCE_MOVE_ON_TRANSFER": 0,
        "SN_DELIVERY": null,
        "SN_NAME_PART": 0,
        "SN_PRICE_TOTAL_PERIOD": 0,
        "SN_PENALTY": null,
        "SN_WAREHOUSE": null,
        "SN_SC_AVAIL_TYPE": null,
        "SN_SC_AVAIL_TO": null,
        "SN_PREMISE_AVAIL_TYPE": null,
        "SN_CACHE_WAREHOUSE_AVAILABLE": 0,
        "SN_CREATED": null,
        "SN_CREATED_L_ID": null,
        "SN_CHANGED": null,
        "SN_CHANGED_L_ID": null,
        "SN_WORK": 0,
        "SN_LAST_CHANGE": null,
        "ACC_GROUP_ID_OLD": null,
        "ACC_GROUP_ID_NEW": null,
        "params": [
            {
                "ID": 1867328,
                "SERVICES_NAME_ID": 185288,
                "CLASS_PAR_NAME": "speed_upload",
                "SNC_PAR_INDEX": null,
                "CLASS_PAR_VALUE": "non",
                "SNC_DOMAIN": null,
                "SNC_DOMAIN_EU": null,
                "SNC_VALID_FROM": null,
                "SNC_VALID_TO": null,
                "SNC_EU_VISIBLE": 1
            }
        ]
    }
}

Request      

GET api/v3/service-definitions/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the service definition. Example: 19

Response

Response Fields

data   object     
ID   integer     

Service definition ID (primary key).

NAME   string     

Service definition name.

SN_CODE   string     

Service code identifier.

SN_EU_NAME   string     

Alternative service name displayed on the end-user (SelfCare) portal.

SN_TYPE   string     

Definition type. 'S' = service, 'P' = product.

Must be one of:
  • S
  • P
TYPE   string     

Service periodicity type. 'M' = periodic (monthly), 'S' = one-time. References services_type.

SN_DEP_TYPE   string     

Service position in hierarchy. 'none' = base service, 'dependent' = dependent (child) service.

Must be one of:
  • none
  • dependent
CLASS   integer     

Service class ID (references services_class). Determines the service category and capabilities.

CT   integer     

Location (CT) ID. Identifies which Mango location this definition belongs to.

PRICE   number     

Price including VAT (one-time or per month).

SN_PRICE_WO_VAT   number     

Price excluding VAT.

SN_PRICE_VAT   number     

VAT amount (one-time or per month).

SN_PRICE_ROUND   number     

Rounding amount when computing price from the price without VAT.

SN_SUGGEST_PRICE   number     

Suggested price with VAT, used when proposing payment amounts (e.g. when closing resource tasks).

SN_VAR_PRICE_ENABLED   integer     

Variable price flag. 1 = service has a variable (consumption-based) price component.

SN_INV_VAR_PRICE   string     

Alternative label for the variable price component on printed invoices.

SN_VAT_BOTTOMUP   integer     

VAT calculation direction. 0 = price entered with VAT (top-down), 1 = price entered without VAT (bottom-up).

SN_PRICE_CALC   string     

Price calculation type. 'LOC_PRICE' = location/time-dependent price (default), 'CALCULATION' = volume/delivery-based calculation, 'UNIT' = unit price with quantity recalculation.

Must be one of:
  • LOC_PRICE
  • CALCULATION
  • UNIT
SN_PRICE_CHANGE   integer     

Price change permission level. Controls whether and how the price can be changed on active services.

SN_PRICE_TOTAL_PERIOD   integer     

Price total period flag. Controls whether the price is shown for the total period.

SN_TL_ID   integer     

VAT rate ID (references taxation_list). Defines the VAT percentage applied to this service.

SN_TG_ID   integer     

Tax group ID (references taxation_groups).

ACC_GROUP_ID   integer     

Accounting group ID (references acc_groups).

ACC_GROUP_ID_OLD   integer     

Previous accounting group ID (before the last change).

ACC_GROUP_ID_NEW   integer     

New accounting group ID (after the last change).

SN_PERIOD   string     

Billing period. Possible values: 'none', 'month', 'cquarter', 'chalfyear', 'cyear', 'cyears2', 'cyears3', 'cmonths18', 'vmonth', 'vquarter', 'vhalfyear', 'vyear', 'vyears2', 'vyears3', 'vmonths18', 'all', 'optional'. Prefix 'c' = calendar-aligned, 'v' = anniversary-aligned, 'optional' = chosen at activation.

Must be one of:
  • all
  • chalfyear
  • cquarter
  • cyear
  • month
  • none
  • vhalfyear
  • vmonth
  • vquarter
  • vyear
  • cyears2
  • cyears3
  • cmonths18
  • vyears2
  • vyears3
  • vmonths18
  • optional
SN_BP_ID   integer     

Default billing plan ID (references billing_plans).

SN_FIXED_BP   integer     

Fixed billing plan flag. 1 = billing plan is enforced and cannot be changed by the operator.

SN_FIXED_MONTHS   integer     

Fixed contract duration in months. 0 = open-ended (no fixed term).

SN_MIN_BOND   integer     

Minimum commitment type (references code_list, CL_CATEGORY='SN_MIN_BOND'). 0 = no minimum commitment.

SN_DISABLE_ATTACH_ALL   integer     

Disable automatic payment matching flag. 1 = payments will not be matched to this service via automatic bulk matching to oldest debts.

SN_START_RESTRICTION   string     

Restriction for service provision start date. 'NONE' = no restriction, 'START_MONTH' = first day of month only, 'START_NEXT_MONTH' = first day of the following month only.

SN_END_RESTRICTION   string     

Restriction for service provision end date. 'NONE' = no restriction, 'END_MONTH' = last day of month only, 'END_NEXT_MONTH' = last day of the following month only.

SN_ACCOUNTFROM_RESTRICTION   string     

Restriction for billing start date. 'NONE' = no restriction, 'START_MONTH' = first day of month only, 'START_NEXT_MONTH' = first day of the following month only.

SN_ACCOUNTTO_RESTRICTION   string     

Restriction for billing end date. 'NONE' = no restriction, 'END_MONTH' = last day of month only, 'END_NEXT_MONTH' = last day of the following month only.

SN_ACCOUNTCHANGE_RESTRICTION   string     

Restriction for billing change date (price, payment, period). 'NONE' = no restriction, 'START_MONTH' = first day of month only, 'START_NEXT_MONTH' = first day of the following month only.

SWITCH_TYPE   integer     

Separate activation and provisioning flag. 0 = activation and provisioning happen together, 1 = separate steps.

SN_PROVISIONING   integer     

Provisioning flag. Controls whether automatic reminding and blocking is enabled for this service.

SN_TRANSFER_SPLITTED   integer     

Split transfer flag. 1 = provisioning is performed as a separate step during service transfer.

SN_MOVE_SPLITTED   integer     

Split move flag. 0 = the move operation is done at once, 1 = the move is initiated and completed as separate steps.

SN_FORCE_MOVE_ON_TRANSFER   integer     

Force move on transfer flag (relevant for dependent services only). 1 = this dependent service is always moved to the new base service during transfer.

SN_DISABLED   integer     

Disabled flag. 1 = service definition is no longer available in the current offer.

SN_PENALTY   integer     

Penalty flag. Controls early termination penalty for this service.

SN_UNIT_PACK   integer     

Packaging unit quantity (for products).

SN_BARCODE   integer     

Barcode number (EAN) for the product.

SN_WARRANTY_PERIOD   integer     

Warranty period in months (for products).

SN_TRANSPORT   integer     

Transport/shipping requirement flag. 1 = transport expedition is required for this service/product.

SN_DELIVERY   integer     

Delivery option flag.

SN_WAREHOUSE   integer     

Warehouse flag. Links this product to warehouse/stock management.

SN_CACHE_WAREHOUSE_AVAILABLE   integer     

Cached count of available products in the sales warehouse (warehouse_item_count minus warehouse_item_blocked).

SN_UNICREDIT_ASSIGN   string     

UniCredit assignment policy on activation. 'never' = cannot assign, 'default_yes' = can assign (default: yes), 'default_no' = can assign (default: no), 'always' = always assign.

Must be one of:
  • never
  • default_yes
  • default_no
  • always
SN_UNICREDIT_TYPE   string     

UniCredit type. 'finance' = financial credit, 'points' = loyalty points.

Must be one of:
  • finance
  • points
SN_POINTS_DISCOUNT   number     

Points discount price with VAT.

SN_POINTS_DISCOUNT_VAT   number     

Points discount VAT amount.

SN_POINTS_DISCOUNT_WO_VAT   number     

Points discount price without VAT.

SN_POINTS_PRICE   integer     

Price in loyalty points.

SN_POINTS_REWARD   integer     

Loyalty points reward for purchasing this service.

SN_WEB_ENABLE   integer     

Web visibility flag. 1 = service is visible on the external web price list.

SN_SC_AVAIL_TYPE   string     

SelfCare availability type. 'none' = not available, 'all' = available to all, 'user_group' = available to a specific customer group, 'user' = available to a specific customer.

Must be one of:
  • none
  • all
  • user_group
  • user
SN_SC_AVAIL_TO   integer     

SelfCare availability target ID. References a customer (USER_ID) or customer group (GROUP_ID) depending on SN_SC_AVAIL_TYPE.

SN_PREMISE_AVAIL_TYPE   string     

Premise availability type. 'all' = available at all premises, 'selected' = available only at selected premises.

Must be one of:
  • all
  • selected
SN_VAR_SYMBOL_TMPL   string     

Template for generating a variable symbol (payment identifier) upon service activation.

SN_NAME_PART   integer     

Name part flag. 1 = this service's name is used for naming the customer's overall service assembly.

SN_WORK   integer     

Work tracking flag. 1 = this service definition is used for time tracking / work management.

NOTE   string     

Note / remark for the service definition.

SN_CREATED   string     

Datetime when this service definition was created.

SN_CREATED_L_ID   integer     

Login ID of the user who created this service definition.

SN_CHANGED   string     

Datetime when this service definition was last modified.

SN_CHANGED_L_ID   integer     

Login ID of the user who last modified this service definition.

SN_LAST_CHANGE   string     

Datetime of the last change (auto-updated).

params   object[]     

Service definition parameters (configuration values). Array of ServiceDefinitionParam objects.
ID   integer     

Parameter record ID (primary key).

SERVICES_NAME_ID   integer     

Parent service definition ID. See GET /v3/service-definitions/{id}.

CLASS_PAR_NAME   string     

Parameter name. Identifies the service-class parameter (e.g. 'fup_enabled', 'transport_service').

SNC_PAR_INDEX   integer     

Parameter index. Used when the same parameter name has multiple indexed values (e.g. FUP levels).

CLASS_PAR_VALUE   string     

Parameter value. The configured value for this parameter on the service definition.

SNC_DOMAIN   string     

Domain (allowed values) for operator use. Comma-separated list of permitted values for this parameter.

SNC_DOMAIN_EU   string     

Domain (allowed values) for end-user (SelfCare) use. Comma-separated list of permitted values visible to customers.

SNC_VALID_FROM   string     

Validity start date (Y-m-d). Parameter is active from this date.

SNC_VALID_TO   string     

Validity end date (Y-m-d). Parameter is active until this date.

SNC_EU_VISIBLE   integer     

End-user visibility flag. 1 = parameter is visible on the SelfCare portal, 0 = hidden from end-users.

Service Groups

List Service Groups

requires authentication 

Returns a paginated list of service groups.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/service-groups?ids=1%2C2%2C3&active=true&type=SELFCARE%2CACCESS&search=internet" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/service-groups"
);

const params = {
    "ids": "1,2,3",
    "active": "true",
    "type": "SELFCARE,ACCESS",
    "search": "internet",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "SGD_ID": 126932,
            "SGD_NAME": "aut adipisci",
            "SGD_CP_ID": 33,
            "SGD_NOTE": null,
            "SGD_TYPE": "TREENODE",
            "SGD_PRIORITY": 50,
            "SGD_CREATED": null,
            "SGD_ACTIVE": 1,
            "SGD_CREATOR": null,
            "SGD_PARENT_ID": null,
            "SGD_ORDER": 100,
            "SGD_FIRSTCLASS": 1,
            "SGD_COLLECT": 0,
            "SGD_MINPRICE_EXCLUDE": 0,
            "SGD_CODE": null,
            "SGD_INFO": "",
            "SGD_PB_HIDE": 0,
            "SGD_LAST_CHANGE": null
        },
        {
            "SGD_ID": 126933,
            "SGD_NAME": "incidunt iure",
            "SGD_CP_ID": null,
            "SGD_NOTE": "Modi ipsum nostrum omnis autem et.",
            "SGD_TYPE": "SELFCARE",
            "SGD_PRIORITY": 50,
            "SGD_CREATED": null,
            "SGD_ACTIVE": 1,
            "SGD_CREATOR": null,
            "SGD_PARENT_ID": null,
            "SGD_ORDER": 100,
            "SGD_FIRSTCLASS": 1,
            "SGD_COLLECT": 0,
            "SGD_MINPRICE_EXCLUDE": 0,
            "SGD_CODE": null,
            "SGD_INFO": "",
            "SGD_PB_HIDE": 0,
            "SGD_LAST_CHANGE": null
        }
    ]
}

Request      

GET api/v3/service-groups

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

ids   string  optional    

Filter by comma-separated IDs Example: 1,2,3

active   string  optional    

Filter by active status (true/false). Default: only active groups are returned. Example: true

type   string  optional    

Filter by comma-separated SGD_TYPE values (OTHER, NODE_AVAIL, SELFCARE, ACCESS, DELIVERY_SCHEDULE, STATISTICS) Example: SELFCARE,ACCESS

search   string  optional    

Search by group name (partial match) Example: internet

Response

Response Fields

data   object     
SGD_ID   integer     

Service group ID.

SGD_NAME   string     

Service group name.

SGD_CODE   string     

Short code identifier for the group.

SGD_NOTE   string     

Group description or note.

SGD_TYPE   string     

Group type. Possible values: "OTHER" = general group, "NODE_AVAIL" = node availability, "SELFCARE" = self-care portal, "ACCESS" = access, "TREENODE" = tree node (product board category), "ESHOP_ACTION" = e-shop promotion, "DELIVERY_SCHEDULE" = delivery schedule, "COUPON" = coupon, "STATISTICS" = statistics.

Must be one of:
  • OTHER
  • NODE_AVAIL
  • SELFCARE
  • ACCESS
  • TREENODE
  • ESHOP_ACTION
  • DELIVERY_SCHEDULE
  • COUPON
  • STATISTICS
SGD_CP_ID   integer     

CIBS partner ID. References the partner (operator) this group belongs to.

SGD_PARENT_ID   integer     

Parent group ID for tree hierarchy. Null for root-level groups.

SGD_ORDER   integer     

Sort order within the tree level. Lower values appear first. Default: 100.

SGD_PRIORITY   integer     

Priority for selecting one group per service (0–100, higher = more preferred). Default: 50.

SGD_FIRSTCLASS   integer     

Whether to display this group with priority (first-class). 1 = yes, 0 = no.

SGD_COLLECT   integer     

Whether to collect services from subcategories. 1 = yes, 0 = no.

SGD_MINPRICE_EXCLUDE   integer     

Whether to exclude this group from minimum price calculation. 1 = exclude, 0 = include.

SGD_PB_HIDE   integer     

Whether to hide this group on the product board. 1 = hidden, 0 = visible.

SGD_INFO   string     

Information text displayed to the customer (e.g. on the product board).

SGD_ACTIVE   integer     

Whether the group is active. 1 = active, 0 = inactive.

SGD_CREATED   string     

Timestamp when the group was created.

SGD_CREATOR   integer     

ID of the user who created this group.

SGD_LAST_CHANGE   string     

Timestamp of the last modification.

Get Service Group

requires authentication 

Returns a single service group by ID.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/service-groups/4" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/service-groups/4"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "SGD_ID": 126934,
        "SGD_NAME": "quidem nostrum",
        "SGD_CP_ID": null,
        "SGD_NOTE": "Iure odit et et modi ipsum nostrum omnis.",
        "SGD_TYPE": "NODE_AVAIL",
        "SGD_PRIORITY": 50,
        "SGD_CREATED": null,
        "SGD_ACTIVE": 1,
        "SGD_CREATOR": null,
        "SGD_PARENT_ID": null,
        "SGD_ORDER": 100,
        "SGD_FIRSTCLASS": 1,
        "SGD_COLLECT": 0,
        "SGD_MINPRICE_EXCLUDE": 0,
        "SGD_CODE": null,
        "SGD_INFO": "",
        "SGD_PB_HIDE": 0,
        "SGD_LAST_CHANGE": null
    }
}

Request      

GET api/v3/service-groups/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   integer     

The ID of the service group. Example: 4

Response

Response Fields

data   object     
SGD_ID   integer     

Service group ID.

SGD_NAME   string     

Service group name.

SGD_CODE   string     

Short code identifier for the group.

SGD_NOTE   string     

Group description or note.

SGD_TYPE   string     

Group type. Possible values: "OTHER" = general group, "NODE_AVAIL" = node availability, "SELFCARE" = self-care portal, "ACCESS" = access, "TREENODE" = tree node (product board category), "ESHOP_ACTION" = e-shop promotion, "DELIVERY_SCHEDULE" = delivery schedule, "COUPON" = coupon, "STATISTICS" = statistics.

Must be one of:
  • OTHER
  • NODE_AVAIL
  • SELFCARE
  • ACCESS
  • TREENODE
  • ESHOP_ACTION
  • DELIVERY_SCHEDULE
  • COUPON
  • STATISTICS
SGD_CP_ID   integer     

CIBS partner ID. References the partner (operator) this group belongs to.

SGD_PARENT_ID   integer     

Parent group ID for tree hierarchy. Null for root-level groups.

SGD_ORDER   integer     

Sort order within the tree level. Lower values appear first. Default: 100.

SGD_PRIORITY   integer     

Priority for selecting one group per service (0–100, higher = more preferred). Default: 50.

SGD_FIRSTCLASS   integer     

Whether to display this group with priority (first-class). 1 = yes, 0 = no.

SGD_COLLECT   integer     

Whether to collect services from subcategories. 1 = yes, 0 = no.

SGD_MINPRICE_EXCLUDE   integer     

Whether to exclude this group from minimum price calculation. 1 = exclude, 0 = include.

SGD_PB_HIDE   integer     

Whether to hide this group on the product board. 1 = hidden, 0 = visible.

SGD_INFO   string     

Information text displayed to the customer (e.g. on the product board).

SGD_ACTIVE   integer     

Whether the group is active. 1 = active, 0 = inactive.

SGD_CREATED   string     

Timestamp when the group was created.

SGD_CREATOR   integer     

ID of the user who created this group.

SGD_LAST_CHANGE   string     

Timestamp of the last modification.

Service Periods

List Service Periods

requires authentication 

Returns a paginated list of billing periods (monthly, quarterly, annual, etc.)
with their location availability and default maturity settings.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/service-periods?ids=month%2Ccyear&active=true" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/service-periods"
);

const params = {
    "ids": "month,cyear",
    "active": "true",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "ID": "chalfyear",
            "NAME": "pololetí",
            "PP_FLOATING": 0,
            "PP_MONTHS": 6,
            "PP_ACTIVE": 1,
            "PP_DISCOUNT": "halfyear",
            "PP_NUMBER": 2,
            "locations": [
                {
                    "PPL_ID": 1,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 1
                },
                {
                    "PPL_ID": 9,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 3
                },
                {
                    "PPL_ID": 17,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 4
                },
                {
                    "PPL_ID": 25,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 5
                },
                {
                    "PPL_ID": 33,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 6
                },
                {
                    "PPL_ID": 41,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 7
                },
                {
                    "PPL_ID": 49,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 10
                },
                {
                    "PPL_ID": 57,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 13
                },
                {
                    "PPL_ID": 65,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 15
                },
                {
                    "PPL_ID": 73,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 39
                },
                {
                    "PPL_ID": 81,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 45
                },
                {
                    "PPL_ID": 89,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 46
                },
                {
                    "PPL_ID": 97,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 58
                },
                {
                    "PPL_ID": 105,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 59
                },
                {
                    "PPL_ID": 113,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 63
                },
                {
                    "PPL_ID": 121,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 65
                },
                {
                    "PPL_ID": 129,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 66
                },
                {
                    "PPL_ID": 137,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 67
                },
                {
                    "PPL_ID": 145,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 69
                },
                {
                    "PPL_ID": 153,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 70
                },
                {
                    "PPL_ID": 161,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 71
                },
                {
                    "PPL_ID": 169,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 72
                },
                {
                    "PPL_ID": 177,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 73
                },
                {
                    "PPL_ID": 185,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 75
                },
                {
                    "PPL_ID": 193,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 78
                },
                {
                    "PPL_ID": 201,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 82
                },
                {
                    "PPL_ID": 209,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 90
                },
                {
                    "PPL_ID": 217,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 98
                },
                {
                    "PPL_ID": 225,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 100
                },
                {
                    "PPL_ID": 233,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 105
                },
                {
                    "PPL_ID": 241,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 107
                },
                {
                    "PPL_ID": 249,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 108
                },
                {
                    "PPL_ID": 257,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 110
                },
                {
                    "PPL_ID": 265,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 111
                },
                {
                    "PPL_ID": 273,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 112
                },
                {
                    "PPL_ID": 281,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 113
                },
                {
                    "PPL_ID": 289,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 114
                },
                {
                    "PPL_ID": 297,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 119
                },
                {
                    "PPL_ID": 305,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 122
                },
                {
                    "PPL_ID": 313,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 123
                },
                {
                    "PPL_ID": 321,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 126
                },
                {
                    "PPL_ID": 329,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 129
                },
                {
                    "PPL_ID": 337,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 131
                },
                {
                    "PPL_ID": 345,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 133
                },
                {
                    "PPL_ID": 353,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 134
                },
                {
                    "PPL_ID": 361,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 139
                },
                {
                    "PPL_ID": 369,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 140
                },
                {
                    "PPL_ID": 377,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 141
                },
                {
                    "PPL_ID": 385,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 142
                },
                {
                    "PPL_ID": 393,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 145
                },
                {
                    "PPL_ID": 401,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 146
                },
                {
                    "PPL_ID": 409,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 147
                },
                {
                    "PPL_ID": 417,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 148
                },
                {
                    "PPL_ID": 425,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 151
                },
                {
                    "PPL_ID": 433,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 152
                },
                {
                    "PPL_ID": 524,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 156
                },
                {
                    "PPL_ID": 530,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 157
                },
                {
                    "PPL_ID": 551,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 179
                },
                {
                    "PPL_ID": 569,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 182
                },
                {
                    "PPL_ID": 617,
                    "PPL_PP_ID": "chalfyear",
                    "PPL_CT": null,
                    "PPL_CP": 188
                }
            ],
            "maturity_defaults": [
                {
                    "PMD_ID": "chalfyear",
                    "PMD_MATURITY": 45,
                    "PMD_CT": 27
                }
            ]
        },
        {
            "ID": "cyears3",
            "NAME": "tři roky",
            "PP_FLOATING": 0,
            "PP_MONTHS": 36,
            "PP_ACTIVE": 1,
            "PP_DISCOUNT": "years3",
            "PP_NUMBER": 1,
            "locations": [],
            "maturity_defaults": []
        }
    ]
}

Request      

GET api/v3/service-periods

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

ids   string  optional    

Filter by comma-separated period IDs (string enum values, e.g. "month,cyear"). Example: month,cyear

active   string  optional    

Filter by active status. Pass "true" for active only, "false" for inactive only. Default: no filtering (return all). Example: true

Response

Response Fields

data   object     
ID   string     

Period identifier (enum string, e.g. "month", "cyear", "vquarter").

NAME   string     

Czech name of the period.

PP_FLOATING   integer     

Whether this is a floating (variable start date) period. 0 = calendar-fixed, 1 = floating.

PP_MONTHS   integer     

Duration of the period in months.

PP_ACTIVE   integer     

Whether this period is currently active. 1 = active, 0 = inactive.

PP_DISCOUNT   string     

Discount category identifier for price lookups.

PP_NUMBER   integer     

Number of billing cycles per year for this period.

locations   object[]     

Location availability records (CT/CIBS partner mappings).

maturity_defaults   object[]     

Default maturity day settings per location.

Service States

List Service States

requires authentication 

Returns a paginated list of service lifecycle states.
This is a small static codelist (4 rows): blocked, active, cancelled, not connected.
Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/service-states?ids=1%2C2" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/service-states"
);

const params = {
    "ids": "1,2",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "ID": 80,
            "NAME": "adipisci",
            "SS_EU_NAME": "quidem"
        },
        {
            "ID": 32,
            "NAME": "qui",
            "SS_EU_NAME": "commodi"
        }
    ]
}

Request      

GET api/v3/service-states

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

ids   string  optional    

Filter by comma-separated IDs. Example: 1,2

Response

Response Fields

data   object     
ID   integer     

Service state ID (zero-padded in DB, cast to integer).

NAME   string     

Internal Czech name of the state.

SS_EU_NAME   string     

End-user portal name of the state.

Text Templates

List Text Templates

requires authentication

Returns a paginated list of text templates. The template body (TT_TEMPLATE) is excluded from the list response for performance. Use the detail endpoint to retrieve the full body.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/templates?per_page=10&page=1&ids=1%2C2%2C3&cts=1%2C2%2C3&type=1%2C2&content_type=html&search=invoice" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/templates"
);

const params = {
    "per_page": "10",
    "page": "1",
    "ids": "1,2,3",
    "cts": "1,2,3",
    "type": "1,2",
    "content_type": "html",
    "search": "invoice",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "TT_ID": 13748,
            "TT_CT": 49,
            "TT_NAME": "TMPL_WPWLVQWR",
            "TT_TEMPLATE": "Modi ipsum nostrum omnis autem et. Aut dolores enim non facere tempora ex voluptatem. Praesentium quis adipisci molestias fugit. Distinctio eum doloremque id aut libero aliquam veniam corporis.",
            "TT_DESCRIPTION": "Alias tenetur ratione nemo voluptate accusamus.",
            "TT_CONTENT_TYPE": "text",
            "TT_TTT_ID": 77,
            "TT_FORMAT": null,
            "params": [
                {
                    "TTP_ID": 183041,
                    "TTP_TT_ID": 13748,
                    "TTP_NAME": "AB",
                    "TTP_VALUE": "17"
                }
            ],
            "type": {
                "TTT_ID": 77,
                "TTT_TYPE": "recusandae",
                "TTT_TITLE": "Rerum ex repellendus.",
                "TTT_CONTENT_TYPE": "text",
                "TTT_USER_EDITABLE": 1,
                "TTT_VAR_PREFIX": "{",
                "TTT_VAR_SUFFIX": "}",
                "TTT_AUTOSELECT": "DISABLE"
            }
        },
        {
            "TT_ID": 13749,
            "TT_CT": 8,
            "TT_NAME": "TMPL_TWBKMKFT",
            "TT_TEMPLATE": "Doloribus repellat officiis corporis nesciunt ut ratione iure. Molestiae ut rem est esse. Aut molestiae sunt suscipit doloribus fugiat. Aut deserunt et error neque recusandae et. Dolorem et ut dicta.",
            "TT_DESCRIPTION": "Id a consectetur assumenda eaque neque.",
            "TT_CONTENT_TYPE": "text",
            "TT_TTT_ID": 78,
            "TT_FORMAT": null,
            "params": [
                {
                    "TTP_ID": 183042,
                    "TTP_TT_ID": 13749,
                    "TTP_NAME": "DOLOREM",
                    "TTP_VALUE": "33"
                }
            ],
            "type": {
                "TTT_ID": 78,
                "TTT_TYPE": "sunt",
                "TTT_TITLE": "Accusantium odit.",
                "TTT_CONTENT_TYPE": "html",
                "TTT_USER_EDITABLE": 0,
                "TTT_VAR_PREFIX": "{",
                "TTT_VAR_SUFFIX": "}",
                "TTT_AUTOSELECT": "DISABLE"
            }
        }
    ]
}

Request      

GET api/v3/templates

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

per_page   integer  optional    

Number of templates to return per page (optional) Example: 10

page   integer  optional    

Page number to return (optional) Example: 1

ids   string  optional    

Filter by comma-separated template IDs Example: 1,2,3

cts   string  optional    

Filter by comma-separated location (installation) IDs. Overrides X-CT header default. Example: 1,2,3

type   string  optional    

Filter by comma-separated template type IDs Example: 1,2

content_type   string  optional    

Filter by content type Example: html

search   string  optional    

Search in template name and description Example: invoice

Response

Response Fields

data   object     
TT_ID   integer     

Unique template identifier (primary key).

TT_CT   integer     

Location (installation) identifier. 0 = global/system template.

TT_NAME   string     

Template name (internal identifier, max 40 chars).

TT_TEMPLATE   string     

Template body content (longtext). Only included in the detail endpoint, excluded from list for performance.

TT_DESCRIPTION   string     

Human-readable template description.

TT_CONTENT_TYPE   string     

Output content type of the template.

Must be one of:
  • text
  • html
  • pdf
TT_TTT_ID   integer     

Template type ID. See the nested type relation.

TT_FORMAT   string     

Template format specification (e.g. paper size).

params   object[]     

Template parameters — configuration key-value pairs (e.g. margins, header height).
TTP_ID   integer     

Unique parameter record ID.

TTP_TT_ID   integer     

Parent template ID.

TTP_NAME   string     

Parameter name (e.g. MARGIN_TOP, HEADER_HEIGHT).

TTP_VALUE   string     

Parameter value.

type   object     

Template type definition — classifies the template purpose and rendering rules.
TTT_ID   integer     

Template type ID.

TTT_TYPE   string     

Type code (e.g. invoice, reminder, agreement).

TTT_TITLE   string     

Human-readable type title.

TTT_CONTENT_TYPE   string     

Supported content types for this type (SET: text, html, pdf).

TTT_USER_EDITABLE   integer     

Whether templates of this type can be edited by users. 1 = editable.

TTT_VAR_PREFIX   string     

Variable placeholder prefix character (default: "{").

TTT_VAR_SUFFIX   string     

Variable placeholder suffix character (default: "}").

TTT_AUTOSELECT   string     

Autoselect behavior for this template type.

Must be one of:
  • DISABLE
  • ENABLE
  • ALWAYS

Get Text Template

requires authentication

Returns a single text template by ID, including the full template body (TT_TEMPLATE).

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/templates/architecto" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/templates/architecto"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "TT_ID": 13750,
        "TT_CT": 49,
        "TT_NAME": "TMPL_SITCPSCQ",
        "TT_TEMPLATE": "Dolores enim non facere tempora. Voluptatem laboriosam praesentium quis adipisci. Fugit deleniti distinctio eum doloremque id aut libero. Veniam corporis dolorem mollitia.",
        "TT_DESCRIPTION": "Modi rerum ex repellendus assumenda.",
        "TT_CONTENT_TYPE": "text",
        "TT_TTT_ID": 79,
        "TT_FORMAT": null,
        "params": [
            {
                "TTP_ID": 183043,
                "TTP_TT_ID": 13750,
                "TTP_NAME": "DOLORES",
                "TTP_VALUE": "44"
            }
        ],
        "type": {
            "TTT_ID": 79,
            "TTT_TYPE": "tenetur",
            "TTT_TITLE": "Reiciendis quia perspiciatis deserunt.",
            "TTT_CONTENT_TYPE": "text,html,pdf",
            "TTT_USER_EDITABLE": 0,
            "TTT_VAR_PREFIX": "{",
            "TTT_VAR_SUFFIX": "}",
            "TTT_AUTOSELECT": "ENABLE"
        }
    }
}

Request      

GET api/v3/templates/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   string     

The ID of the template. Example: architecto

Response

Response Fields

data   object     
TT_ID   integer     

Unique template identifier (primary key).

TT_CT   integer     

Location (installation) identifier. 0 = global/system template.

TT_NAME   string     

Template name (internal identifier, max 40 chars).

TT_TEMPLATE   string     

Template body content (longtext). Only included in the detail endpoint, excluded from list for performance.

TT_DESCRIPTION   string     

Human-readable template description.

TT_CONTENT_TYPE   string     

Output content type of the template.

Must be one of:
  • text
  • html
  • pdf
TT_TTT_ID   integer     

Template type ID. See the nested type relation.

TT_FORMAT   string     

Template format specification (e.g. paper size).

params   object[]     

Template parameters — configuration key-value pairs (e.g. margins, header height).
TTP_ID   integer     

Unique parameter record ID.

TTP_TT_ID   integer     

Parent template ID.

TTP_NAME   string     

Parameter name (e.g. MARGIN_TOP, HEADER_HEIGHT).

TTP_VALUE   string     

Parameter value.

type   object     

Template type definition — classifies the template purpose and rendering rules.
TTT_ID   integer     

Template type ID.

TTT_TYPE   string     

Type code (e.g. invoice, reminder, agreement).

TTT_TITLE   string     

Human-readable type title.

TTT_CONTENT_TYPE   string     

Supported content types for this type (SET: text, html, pdf).

TTT_USER_EDITABLE   integer     

Whether templates of this type can be edited by users. 1 = editable.

TTT_VAR_PREFIX   string     

Variable placeholder prefix character (default: "{").

TTT_VAR_SUFFIX   string     

Variable placeholder suffix character (default: "}").

TTT_AUTOSELECT   string     

Autoselect behavior for this template type.

Must be one of:
  • DISABLE
  • ENABLE
  • ALWAYS

Time Tracking

List Time Tracking Works

requires authentication

This endpoint gets a list of time tracking works. The list can be filtered and sorted.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/time-tracking/works?ids=1%2C2%2C3&customer_id=10&process_id=5&activity_id=100&state=ACTIVE&created_from=2024-01-01&created_to=2024-12-31" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/time-tracking/works"
);

const params = {
    "ids": "1,2,3",
    "customer_id": "10",
    "process_id": "5",
    "activity_id": "100",
    "state": "ACTIVE",
    "created_from": "2024-01-01",
    "created_to": "2024-12-31",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "TTW_ID": 32137,
            "TTW_NAME": "et et modi",
            "TTW_MINUTES_PLANNED_ORIGIN": 431,
            "TTW_MINUTES_PLANNED": null,
            "TTW_LIMIT_PLANNED": null,
            "TTW_REAL_MINUTES_PLANNED": 0,
            "TTW_START": null,
            "TTW_FINISH": null,
            "TTW_L_ID": 776,
            "TTW_SG_ID": null,
            "TTW_L_MAINTENANCE": "NONE",
            "TTW_ACTIVE": "CLOSED",
            "TTW_TYPE": "NORMAL",
            "TTW_PRICE": "2307.6926",
            "TTW_CP": null,
            "TTW_TTC_ID": null,
            "TTW_EXTRA_WORK": 0,
            "TTW_EXTRA_WORK_DETAIL": 0,
            "TTW_COUNT_STRATEGY": "MINS",
            "TTW_SN_ID": null,
            "TTW_VALID": 1,
            "TTW_VALID_NOTE": null,
            "TTW_CREATOR_ID": null,
            "TTW_CACHE_FULLNAME": null,
            "TTW_MANDATORY_DESC": null,
            "bound_objects": [
                {
                    "TTWBO_ID": 34099,
                    "TTWBO_TTW_ID": 32137,
                    "TTWBO_OBJECT_ID": 2327,
                    "TTWBO_OBJECT_TYPE": "maintenance_job"
                }
            ]
        },
        {
            "TTW_ID": 32138,
            "TTW_NAME": "ex voluptatem laboriosam",
            "TTW_MINUTES_PLANNED_ORIGIN": 217,
            "TTW_MINUTES_PLANNED": 388,
            "TTW_LIMIT_PLANNED": null,
            "TTW_REAL_MINUTES_PLANNED": 0,
            "TTW_START": null,
            "TTW_FINISH": null,
            "TTW_L_ID": 132,
            "TTW_SG_ID": null,
            "TTW_L_MAINTENANCE": "NONE",
            "TTW_ACTIVE": "FINISHED",
            "TTW_TYPE": "PRIVATE",
            "TTW_PRICE": null,
            "TTW_CP": null,
            "TTW_TTC_ID": null,
            "TTW_EXTRA_WORK": 0,
            "TTW_EXTRA_WORK_DETAIL": 0,
            "TTW_COUNT_STRATEGY": "MINS",
            "TTW_SN_ID": null,
            "TTW_VALID": 1,
            "TTW_VALID_NOTE": null,
            "TTW_CREATOR_ID": null,
            "TTW_CACHE_FULLNAME": null,
            "TTW_MANDATORY_DESC": null,
            "bound_objects": [
                {
                    "TTWBO_ID": 34100,
                    "TTWBO_TTW_ID": 32138,
                    "TTWBO_OBJECT_ID": 4781,
                    "TTWBO_OBJECT_TYPE": "users"
                }
            ]
        }
    ]
}

Request      

GET api/v3/time-tracking/works

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

ids   string  optional    

Filter by comma-separated IDs Example: 1,2,3

customer_id   integer  optional    

Filter by bound customer (user) ID Example: 10

process_id   integer  optional    

Filter by bound process (maintenance) ID Example: 5

activity_id   integer  optional    

Filter by activity ID (reverse lookup via time_tracking_activities) Example: 100

state   string  optional    

Filter by work status: ACTIVE, CLOSED, FINISHED Example: ACTIVE

created_from   string  optional    

Filter works with TTW_START >= this date (YYYY-MM-DD) Example: 2024-01-01

created_to   string  optional    

Filter works with TTW_START <= this date (YYYY-MM-DD) Example: 2024-12-31

Response

Response Fields

data   object     
TTW_ID   integer     

Work ID (primary key).

TTW_NAME   string     

Base work name.

name   string     

Computed full work name including category and bound objects.

TTW_CACHE_FULLNAME   string     

Cached full work name (raw, including category and bound objects).

TTW_MINUTES_PLANNED_ORIGIN   integer     

Originally planned work volume in minutes.

TTW_MINUTES_PLANNED   integer     

Total planned work volume in minutes (including plan adjustments).

TTW_LIMIT_PLANNED   integer     

Planned volume limit in minutes.

TTW_REAL_MINUTES_PLANNED   integer     

Real (estimated) total work volume in minutes.

TTW_START   string     

Work creation datetime.

TTW_FINISH   string     

Planned completion datetime.

TTW_L_ID   integer     

Assigned login (operator) ID.

TTW_SG_ID   integer     

Assigned service group ID.

TTW_L_MAINTENANCE   string     

Assignment mode. 'EDIT' = assigned via maintenance (customer), 'NONE' = assigned directly to a login or group.

Must be one of:
  • EDIT
  • NONE
TTW_CREATOR_ID   integer     

Login ID of the user who created this work.

TTW_CP   integer     

Company (installation) ID this work belongs to.

TTW_ACTIVE   string     

Work status. 'ACTIVE' = active, 'CLOSED' = closed (unconfirmed activities remain), 'FINISHED' = finished.

Must be one of:
  • ACTIVE
  • CLOSED
  • FINISHED
TTW_TYPE   string     

Work type. Determines how the work counts toward the working time fund. 'NORMAL' = regular (counts toward working hours), 'SPECIAL' = extraordinary (does not count), 'PRIVATE' = private (does not count).

Must be one of:
  • NORMAL
  • SPECIAL
  • PRIVATE
TTW_TTC_ID   integer     

Time tracking category ID (references time_tracking_categories).

TTW_PRICE   number     

Hourly price (excluding VAT).

TTW_SN_ID   integer     

Linked product (service definition) ID (references services_name).

TTW_EXTRA_WORK   integer     

Extra work allowed flag. 1 = completed work is automatically added to the order.

TTW_EXTRA_WORK_DETAIL   integer     

Detailed extra work billing flag. 1 = creates a separate order item for each activity.

TTW_COUNT_STRATEGY   string     

Rounding strategy for worked hours. 'MINS' = exact minutes, 'COMM_15/30/60' = commenced quarter/half/full hours, 'ROUND_15/30/60' = rounded quarter/half/full hours.

Must be one of:
  • MINS
  • COMM_15
  • COMM_30
  • COMM_60
  • ROUND_15
  • ROUND_30
  • ROUND_60
TTW_VALID   integer     

Validity flag. 1 = valid, 0 = invalid.

TTW_VALID_NOTE   string     

Validation note explaining invalidity reason.

TTW_MANDATORY_DESC   integer     

Mandatory activity description flag. 1 = all activities for this work must have a description.

bound_objects   object[]     

Bound objects linked to this work (e.g. maintenances, users, orders). Array of TimeTrackingWorkBoundObject objects.
TTWBO_ID   integer     

Bound object record ID.

TTWBO_TTW_ID   integer     

Parent time tracking work ID. See GET /v3/time-tracking/works/{id}.

TTWBO_OBJECT_ID   integer     

ID of the linked entity. The referenced table depends on TTWBO_OBJECT_TYPE.

TTWBO_OBJECT_TYPE   string     

Type of the linked entity. Possible values: "maintenance" = process (ticket), "tmp_maintenance" = unsaved process, "users" = customer, "orders_items" = order item, "orders" = order, "maintenance_job" = job within a process.

Must be one of:
  • maintenance
  • tmp_maintenance
  • users
  • orders_items
  • orders
  • maintenance_job

Create Time Tracking Work

requires authentication

This endpoint creates a new time tracking work.

Example request:
curl --request POST \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/time-tracking/works" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"name\": \"Server maintenance\",
    \"minutes_planned_origin\": 120,
    \"minutes_planned\": 120,
    \"limit_planned\": 0,
    \"real_minutes_planned\": 120,
    \"start\": \"2024-01-15 08:00:00\",
    \"finish\": \"2024-01-15 16:00:00\",
    \"l_id\": 294,
    \"sg_id\": 1,
    \"l_maintenance\": \"NONE\",
    \"active\": 1,
    \"type\": \"NORMAL\",
    \"price\": 500,
    \"cp\": 0,
    \"ttc_id\": 1,
    \"extra_work\": 0,
    \"extra_work_detail\": 0,
    \"count_strategy\": \"MINS\",
    \"sn_id\": 16,
    \"mandatory_desc\": 0,
    \"maintenances\": [
        16
    ],
    \"users\": [
        16
    ],
    \"orders_items\": [
        16
    ],
    \"orders\": [
        16
    ],
    \"maintenance_jobs\": [
        16
    ]
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/time-tracking/works"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "name": "Server maintenance",
    "minutes_planned_origin": 120,
    "minutes_planned": 120,
    "limit_planned": 0,
    "real_minutes_planned": 120,
    "start": "2024-01-15 08:00:00",
    "finish": "2024-01-15 16:00:00",
    "l_id": 294,
    "sg_id": 1,
    "l_maintenance": "NONE",
    "active": 1,
    "type": "NORMAL",
    "price": 500,
    "cp": 0,
    "ttc_id": 1,
    "extra_work": 0,
    "extra_work_detail": 0,
    "count_strategy": "MINS",
    "sn_id": 16,
    "mandatory_desc": 0,
    "maintenances": [
        16
    ],
    "users": [
        16
    ],
    "orders_items": [
        16
    ],
    "orders": [
        16
    ],
    "maintenance_jobs": [
        16
    ]
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "data": {
        "TTW_ID": 32139,
        "TTW_NAME": "eius et animi",
        "TTW_MINUTES_PLANNED_ORIGIN": 298,
        "TTW_MINUTES_PLANNED": null,
        "TTW_LIMIT_PLANNED": null,
        "TTW_REAL_MINUTES_PLANNED": 0,
        "TTW_START": "2026-02-22 23:30:33",
        "TTW_FINISH": null,
        "TTW_L_ID": null,
        "TTW_SG_ID": null,
        "TTW_L_MAINTENANCE": "NONE",
        "TTW_ACTIVE": "ACTIVE",
        "TTW_TYPE": "NORMAL",
        "TTW_PRICE": "5528.7323",
        "TTW_CP": null,
        "TTW_TTC_ID": null,
        "TTW_EXTRA_WORK": 0,
        "TTW_EXTRA_WORK_DETAIL": 0,
        "TTW_COUNT_STRATEGY": "MINS",
        "TTW_SN_ID": null,
        "TTW_VALID": 1,
        "TTW_VALID_NOTE": null,
        "TTW_CREATOR_ID": null,
        "TTW_CACHE_FULLNAME": null,
        "TTW_MANDATORY_DESC": null,
        "bound_objects": [
            {
                "TTWBO_ID": 34101,
                "TTWBO_TTW_ID": 32139,
                "TTWBO_OBJECT_ID": 9199,
                "TTWBO_OBJECT_TYPE": "orders_items"
            }
        ]
    }
}

Request      

POST api/v3/time-tracking/works

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Body Parameters

name   string     

Work name/title Example: Server maintenance

minutes_planned_origin   integer  optional    

Original planned minutes Example: 120

minutes_planned   integer  optional    

Current planned minutes Example: 120

limit_planned   integer  optional    

Limit strategy (0=no limit, 1=warn, 2=update order, 3=block) Example: 0

real_minutes_planned   integer  optional    

Real/actual planned minutes Example: 120

start   string  optional    

Work start time (YYYY-MM-DD HH:MM:SS) Example: 2024-01-15 08:00:00

finish   string  optional    

Work finish time (YYYY-MM-DD HH:MM:SS) Example: 2024-01-15 16:00:00

l_id   integer  optional    

Operator (login) ID Example: 294

sg_id   integer  optional    

Service group ID Example: 1

l_maintenance   string  optional    

Maintenance editing mode: EDIT or NONE Example: NONE

active   integer  optional    

Work status (tinyint for SP) Example: 1

type   string  optional    

Work type: NORMAL, SPECIAL, PRIVATE Example: NORMAL

price   number  optional    

Price/rate Example: 500

cp   integer  optional    

Cost position Example: 0

ttc_id   integer  optional    

Time tracking category ID Example: 1

extra_work   integer  optional    

Allow extra work/overtime (0 or 1) Example: 0

extra_work_detail   integer  optional    

Detailed extra work accounting (0 or 1) Example: 0

count_strategy   string  optional    

Time rounding strategy Example: MINS

sn_id   integer  optional    

Service name ID Example: 16

mandatory_desc   integer  optional    

Description mandatory for activities (0 or 1) Example: 0

maintenances   integer[]  optional    

Bound process IDs

users   integer[]  optional    

Bound customer IDs

orders_items   integer[]  optional    

Bound order item IDs

orders   integer[]  optional    

Bound order IDs

maintenance_jobs   integer[]  optional    

Bound job IDs

Response

Response Fields

data   object     
TTW_ID   integer     

Work ID (primary key).

TTW_NAME   string     

Base work name.

name   string     

Computed full work name including category and bound objects.

TTW_CACHE_FULLNAME   string     

Cached full work name (raw, including category and bound objects).

TTW_MINUTES_PLANNED_ORIGIN   integer     

Originally planned work volume in minutes.

TTW_MINUTES_PLANNED   integer     

Total planned work volume in minutes (including plan adjustments).

TTW_LIMIT_PLANNED   integer     

Planned volume limit in minutes.

TTW_REAL_MINUTES_PLANNED   integer     

Real (estimated) total work volume in minutes.

TTW_START   string     

Work creation datetime.

TTW_FINISH   string     

Planned completion datetime.

TTW_L_ID   integer     

Assigned login (operator) ID.

TTW_SG_ID   integer     

Assigned service group ID.

TTW_L_MAINTENANCE   string     

Assignment mode. 'EDIT' = assigned via maintenance (customer), 'NONE' = assigned directly to a login or group.

Must be one of:
  • EDIT
  • NONE
TTW_CREATOR_ID   integer     

Login ID of the user who created this work.

TTW_CP   integer     

Company (installation) ID this work belongs to.

TTW_ACTIVE   string     

Work status. 'ACTIVE' = active, 'CLOSED' = closed (unconfirmed activities remain), 'FINISHED' = finished.

Must be one of:
  • ACTIVE
  • CLOSED
  • FINISHED
TTW_TYPE   string     

Work type. Determines how the work counts toward the working time fund. 'NORMAL' = regular (counts toward working hours), 'SPECIAL' = extraordinary (does not count), 'PRIVATE' = private (does not count).

Must be one of:
  • NORMAL
  • SPECIAL
  • PRIVATE
TTW_TTC_ID   integer     

Time tracking category ID (references time_tracking_categories).

TTW_PRICE   number     

Hourly price (excluding VAT).

TTW_SN_ID   integer     

Linked product (service definition) ID (references services_name).

TTW_EXTRA_WORK   integer     

Extra work allowed flag. 1 = completed work is automatically added to the order.

TTW_EXTRA_WORK_DETAIL   integer     

Detailed extra work billing flag. 1 = creates a separate order item for each activity.

TTW_COUNT_STRATEGY   string     

Rounding strategy for worked hours. 'MINS' = exact minutes, 'COMM_15/30/60' = commenced quarter/half/full hours, 'ROUND_15/30/60' = rounded quarter/half/full hours.

Must be one of:
  • MINS
  • COMM_15
  • COMM_30
  • COMM_60
  • ROUND_15
  • ROUND_30
  • ROUND_60
TTW_VALID   integer     

Validity flag. 1 = valid, 0 = invalid.

TTW_VALID_NOTE   string     

Validation note explaining invalidity reason.

TTW_MANDATORY_DESC   integer     

Mandatory activity description flag. 1 = all activities for this work must have a description.

bound_objects   object[]     

Bound objects linked to this work (e.g. maintenances, users, orders). Array of TimeTrackingWorkBoundObject objects.
TTWBO_ID   integer     

Bound object record ID.

TTWBO_TTW_ID   integer     

Parent time tracking work ID. See GET /v3/time-tracking/works/{id}.

TTWBO_OBJECT_ID   integer     

ID of the linked entity. The referenced table depends on TTWBO_OBJECT_TYPE.

TTWBO_OBJECT_TYPE   string     

Type of the linked entity. Possible values: "maintenance" = process (ticket), "tmp_maintenance" = unsaved process, "users" = customer, "orders_items" = order item, "orders" = order, "maintenance_job" = job within a process.

Must be one of:
  • maintenance
  • tmp_maintenance
  • users
  • orders_items
  • orders
  • maintenance_job

Get Time Tracking Work

requires authentication

This endpoint retrieves a specific time tracking work by ID.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/time-tracking/works/architecto" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/time-tracking/works/architecto"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "TTW_ID": 32140,
        "TTW_NAME": "ipsum nostrum omnis",
        "TTW_MINUTES_PLANNED_ORIGIN": 340,
        "TTW_MINUTES_PLANNED": null,
        "TTW_LIMIT_PLANNED": null,
        "TTW_REAL_MINUTES_PLANNED": 0,
        "TTW_START": null,
        "TTW_FINISH": null,
        "TTW_L_ID": null,
        "TTW_SG_ID": null,
        "TTW_L_MAINTENANCE": "NONE",
        "TTW_ACTIVE": "ACTIVE",
        "TTW_TYPE": "SPECIAL",
        "TTW_PRICE": null,
        "TTW_CP": null,
        "TTW_TTC_ID": null,
        "TTW_EXTRA_WORK": 0,
        "TTW_EXTRA_WORK_DETAIL": 0,
        "TTW_COUNT_STRATEGY": "MINS",
        "TTW_SN_ID": null,
        "TTW_VALID": 1,
        "TTW_VALID_NOTE": null,
        "TTW_CREATOR_ID": null,
        "TTW_CACHE_FULLNAME": null,
        "TTW_MANDATORY_DESC": null,
        "bound_objects": [
            {
                "TTWBO_ID": 34102,
                "TTWBO_TTW_ID": 32140,
                "TTWBO_OBJECT_ID": 5040,
                "TTWBO_OBJECT_TYPE": "orders"
            }
        ]
    }
}

Request      

GET api/v3/time-tracking/works/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   string     

The ID of the work. Example: architecto

Response

Response Fields

data   object     
TTW_ID   integer     

Work ID (primary key).

TTW_NAME   string     

Base work name.

name   string     

Computed full work name including category and bound objects.

TTW_CACHE_FULLNAME   string     

Cached full work name (raw, including category and bound objects).

TTW_MINUTES_PLANNED_ORIGIN   integer     

Originally planned work volume in minutes.

TTW_MINUTES_PLANNED   integer     

Total planned work volume in minutes (including plan adjustments).

TTW_LIMIT_PLANNED   integer     

Planned volume limit in minutes.

TTW_REAL_MINUTES_PLANNED   integer     

Real (estimated) total work volume in minutes.

TTW_START   string     

Work creation datetime.

TTW_FINISH   string     

Planned completion datetime.

TTW_L_ID   integer     

Assigned login (operator) ID.

TTW_SG_ID   integer     

Assigned service group ID.

TTW_L_MAINTENANCE   string     

Assignment mode. 'EDIT' = assigned via maintenance (customer), 'NONE' = assigned directly to a login or group.

Must be one of:
  • EDIT
  • NONE
TTW_CREATOR_ID   integer     

Login ID of the user who created this work.

TTW_CP   integer     

Company (installation) ID this work belongs to.

TTW_ACTIVE   string     

Work status. 'ACTIVE' = active, 'CLOSED' = closed (unconfirmed activities remain), 'FINISHED' = finished.

Must be one of:
  • ACTIVE
  • CLOSED
  • FINISHED
TTW_TYPE   string     

Work type. Determines how the work counts toward the working time fund. 'NORMAL' = regular (counts toward working hours), 'SPECIAL' = extraordinary (does not count), 'PRIVATE' = private (does not count).

Must be one of:
  • NORMAL
  • SPECIAL
  • PRIVATE
TTW_TTC_ID   integer     

Time tracking category ID (references time_tracking_categories).

TTW_PRICE   number     

Hourly price (excluding VAT).

TTW_SN_ID   integer     

Linked product (service definition) ID (references services_name).

TTW_EXTRA_WORK   integer     

Extra work allowed flag. 1 = completed work is automatically added to the order.

TTW_EXTRA_WORK_DETAIL   integer     

Detailed extra work billing flag. 1 = creates a separate order item for each activity.

TTW_COUNT_STRATEGY   string     

Rounding strategy for worked hours. 'MINS' = exact minutes, 'COMM_15/30/60' = commenced quarter/half/full hours, 'ROUND_15/30/60' = rounded quarter/half/full hours.

Must be one of:
  • MINS
  • COMM_15
  • COMM_30
  • COMM_60
  • ROUND_15
  • ROUND_30
  • ROUND_60
TTW_VALID   integer     

Validity flag. 1 = valid, 0 = invalid.

TTW_VALID_NOTE   string     

Validation note explaining invalidity reason.

TTW_MANDATORY_DESC   integer     

Mandatory activity description flag. 1 = all activities for this work must have a description.

bound_objects   object[]     

Bound objects linked to this work (e.g. maintenances, users, orders). Array of TimeTrackingWorkBoundObject objects.
TTWBO_ID   integer     

Bound object record ID.

TTWBO_TTW_ID   integer     

Parent time tracking work ID. See GET /v3/time-tracking/works/{id}.

TTWBO_OBJECT_ID   integer     

ID of the linked entity. The referenced table depends on TTWBO_OBJECT_TYPE.

TTWBO_OBJECT_TYPE   string     

Type of the linked entity. Possible values: "maintenance" = process (ticket), "tmp_maintenance" = unsaved process, "users" = customer, "orders_items" = order item, "orders" = order, "maintenance_job" = job within a process.

Must be one of:
  • maintenance
  • tmp_maintenance
  • users
  • orders_items
  • orders
  • maintenance_job

Update Time Tracking Work

requires authentication

This endpoint updates an existing time tracking work.

Example request:
curl --request PUT \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/time-tracking/works/architecto" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"name\": \"Server maintenance\",
    \"minutes_planned_origin\": 120,
    \"minutes_planned\": 120,
    \"limit_planned\": 0,
    \"real_minutes_planned\": 120,
    \"start\": \"2024-01-15 08:00:00\",
    \"finish\": \"2024-01-15 16:00:00\",
    \"l_id\": 294,
    \"sg_id\": 1,
    \"l_maintenance\": \"NONE\",
    \"active\": 1,
    \"type\": \"NORMAL\",
    \"price\": 500,
    \"cp\": 0,
    \"ttc_id\": 1,
    \"extra_work\": 0,
    \"extra_work_detail\": 0,
    \"count_strategy\": \"MINS\",
    \"sn_id\": 16,
    \"mandatory_desc\": 0,
    \"maintenances\": [
        16
    ],
    \"users\": [
        16
    ],
    \"orders_items\": [
        16
    ],
    \"orders\": [
        16
    ],
    \"maintenance_jobs\": [
        16
    ]
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/time-tracking/works/architecto"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "name": "Server maintenance",
    "minutes_planned_origin": 120,
    "minutes_planned": 120,
    "limit_planned": 0,
    "real_minutes_planned": 120,
    "start": "2024-01-15 08:00:00",
    "finish": "2024-01-15 16:00:00",
    "l_id": 294,
    "sg_id": 1,
    "l_maintenance": "NONE",
    "active": 1,
    "type": "NORMAL",
    "price": 500,
    "cp": 0,
    "ttc_id": 1,
    "extra_work": 0,
    "extra_work_detail": 0,
    "count_strategy": "MINS",
    "sn_id": 16,
    "mandatory_desc": 0,
    "maintenances": [
        16
    ],
    "users": [
        16
    ],
    "orders_items": [
        16
    ],
    "orders": [
        16
    ],
    "maintenance_jobs": [
        16
    ]
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "data": {
        "TTW_ID": 32141,
        "TTW_NAME": "quos velit et",
        "TTW_MINUTES_PLANNED_ORIGIN": 203,
        "TTW_MINUTES_PLANNED": null,
        "TTW_LIMIT_PLANNED": null,
        "TTW_REAL_MINUTES_PLANNED": 0,
        "TTW_START": "2026-02-24 10:58:15",
        "TTW_FINISH": null,
        "TTW_L_ID": 548,
        "TTW_SG_ID": null,
        "TTW_L_MAINTENANCE": "NONE",
        "TTW_ACTIVE": "CLOSED",
        "TTW_TYPE": "NORMAL",
        "TTW_PRICE": "9161.8708",
        "TTW_CP": null,
        "TTW_TTC_ID": null,
        "TTW_EXTRA_WORK": 0,
        "TTW_EXTRA_WORK_DETAIL": 0,
        "TTW_COUNT_STRATEGY": "MINS",
        "TTW_SN_ID": null,
        "TTW_VALID": 1,
        "TTW_VALID_NOTE": null,
        "TTW_CREATOR_ID": null,
        "TTW_CACHE_FULLNAME": null,
        "TTW_MANDATORY_DESC": null,
        "bound_objects": [
            {
                "TTWBO_ID": 34103,
                "TTWBO_TTW_ID": 32141,
                "TTWBO_OBJECT_ID": 8290,
                "TTWBO_OBJECT_TYPE": "orders_items"
            }
        ]
    }
}

Request      

PUT api/v3/time-tracking/works/{id}

PATCH api/v3/time-tracking/works/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   string     

The ID of the work. Example: architecto

Body Parameters

name   string  optional    

Work name/title Example: Server maintenance

minutes_planned_origin   integer  optional    

Original planned minutes Example: 120

minutes_planned   integer  optional    

Current planned minutes Example: 120

limit_planned   integer  optional    

Limit strategy (0=no limit, 1=warn, 2=update order, 3=block) Example: 0

real_minutes_planned   integer  optional    

Real/actual planned minutes Example: 120

start   string  optional    

Work start time (YYYY-MM-DD HH:MM:SS) Example: 2024-01-15 08:00:00

finish   string  optional    

Work finish time (YYYY-MM-DD HH:MM:SS) Example: 2024-01-15 16:00:00

l_id   integer  optional    

Operator (login) ID Example: 294

sg_id   integer  optional    

Service group ID Example: 1

l_maintenance   string  optional    

Maintenance editing mode: EDIT or NONE Example: NONE

active   integer  optional    

Work status (tinyint for SP) Example: 1

type   string  optional    

Work type: NORMAL, SPECIAL, PRIVATE Example: NORMAL

price   number  optional    

Price/rate Example: 500

cp   integer  optional    

Cost position Example: 0

ttc_id   integer  optional    

Time tracking category ID Example: 1

extra_work   integer  optional    

Allow extra work/overtime (0 or 1) Example: 0

extra_work_detail   integer  optional    

Detailed extra work accounting (0 or 1) Example: 0

count_strategy   string  optional    

Time rounding strategy Example: MINS

sn_id   integer  optional    

Service name ID Example: 16

mandatory_desc   integer  optional    

Description mandatory for activities (0 or 1) Example: 0

maintenances   integer[]  optional    

Bound process IDs

users   integer[]  optional    

Bound customer IDs

orders_items   integer[]  optional    

Bound order item IDs

orders   integer[]  optional    

Bound order IDs

maintenance_jobs   integer[]  optional    

Bound job IDs

Response

Response Fields

data   object     
TTW_ID   integer     

Work ID (primary key).

TTW_NAME   string     

Base work name.

name   string     

Computed full work name including category and bound objects.

TTW_CACHE_FULLNAME   string     

Cached full work name (raw, including category and bound objects).

TTW_MINUTES_PLANNED_ORIGIN   integer     

Originally planned work volume in minutes.

TTW_MINUTES_PLANNED   integer     

Total planned work volume in minutes (including plan adjustments).

TTW_LIMIT_PLANNED   integer     

Planned volume limit in minutes.

TTW_REAL_MINUTES_PLANNED   integer     

Real (estimated) total work volume in minutes.

TTW_START   string     

Work creation datetime.

TTW_FINISH   string     

Planned completion datetime.

TTW_L_ID   integer     

Assigned login (operator) ID.

TTW_SG_ID   integer     

Assigned service group ID.

TTW_L_MAINTENANCE   string     

Assignment mode. 'EDIT' = assigned via maintenance (customer), 'NONE' = assigned directly to a login or group.

Must be one of:
  • EDIT
  • NONE
TTW_CREATOR_ID   integer     

Login ID of the user who created this work.

TTW_CP   integer     

Company (installation) ID this work belongs to.

TTW_ACTIVE   string     

Work status. 'ACTIVE' = active, 'CLOSED' = closed (unconfirmed activities remain), 'FINISHED' = finished.

Must be one of:
  • ACTIVE
  • CLOSED
  • FINISHED
TTW_TYPE   string     

Work type. Determines how the work counts toward the working time fund. 'NORMAL' = regular (counts toward working hours), 'SPECIAL' = extraordinary (does not count), 'PRIVATE' = private (does not count).

Must be one of:
  • NORMAL
  • SPECIAL
  • PRIVATE
TTW_TTC_ID   integer     

Time tracking category ID (references time_tracking_categories).

TTW_PRICE   number     

Hourly price (excluding VAT).

TTW_SN_ID   integer     

Linked product (service definition) ID (references services_name).

TTW_EXTRA_WORK   integer     

Extra work allowed flag. 1 = completed work is automatically added to the order.

TTW_EXTRA_WORK_DETAIL   integer     

Detailed extra work billing flag. 1 = creates a separate order item for each activity.

TTW_COUNT_STRATEGY   string     

Rounding strategy for worked hours. 'MINS' = exact minutes, 'COMM_15/30/60' = commenced quarter/half/full hours, 'ROUND_15/30/60' = rounded quarter/half/full hours.

Must be one of:
  • MINS
  • COMM_15
  • COMM_30
  • COMM_60
  • ROUND_15
  • ROUND_30
  • ROUND_60
TTW_VALID   integer     

Validity flag. 1 = valid, 0 = invalid.

TTW_VALID_NOTE   string     

Validation note explaining invalidity reason.

TTW_MANDATORY_DESC   integer     

Mandatory activity description flag. 1 = all activities for this work must have a description.

bound_objects   object[]     

Bound objects linked to this work (e.g. maintenances, users, orders). Array of TimeTrackingWorkBoundObject objects.
TTWBO_ID   integer     

Bound object record ID.

TTWBO_TTW_ID   integer     

Parent time tracking work ID. See GET /v3/time-tracking/works/{id}.

TTWBO_OBJECT_ID   integer     

ID of the linked entity. The referenced table depends on TTWBO_OBJECT_TYPE.

TTWBO_OBJECT_TYPE   string     

Type of the linked entity. Possible values: "maintenance" = process (ticket), "tmp_maintenance" = unsaved process, "users" = customer, "orders_items" = order item, "orders" = order, "maintenance_job" = job within a process.

Must be one of:
  • maintenance
  • tmp_maintenance
  • users
  • orders_items
  • orders
  • maintenance_job

Delete Time Tracking Work

requires authentication

This endpoint deletes a time tracking work.

Example request:
curl --request DELETE \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/time-tracking/works/architecto" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/time-tracking/works/architecto"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

Example response (204):

Empty response

Request      

DELETE api/v3/time-tracking/works/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   string     

The ID of the work. Example: architecto

List Time Tracking Activities

requires authentication

This endpoint gets a list of time tracking activities. The list can be filtered and sorted.

Business rules (enforced by stored procedures):

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/time-tracking/activities?ids=1%2C2%2C3&worker_id=294&work_id=10" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/time-tracking/activities"
);

const params = {
    "ids": "1,2,3",
    "worker_id": "294",
    "work_id": "10",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "TTA_ID": 632516,
            "TTA_TTW_ID": 592,
            "TTA_L_ID": 751,
            "TTA_DATE": "2006-09-25",
            "TTA_TIME_FROM": "20:47:12",
            "TTA_TIME_TO": "23:42:49",
            "TTA_TIME_TOTAL_MINS": 160,
            "TTA_APPROVED": 0,
            "TTA_DESCRIPTION": null,
            "TTA_TIME_ACCOUNTED_MINS": null
        },
        {
            "TTA_ID": 632517,
            "TTA_TTW_ID": 765,
            "TTA_L_ID": 633,
            "TTA_DATE": "1973-12-17",
            "TTA_TIME_FROM": "10:24:12",
            "TTA_TIME_TO": "18:42:45",
            "TTA_TIME_TOTAL_MINS": 259,
            "TTA_APPROVED": 0,
            "TTA_DESCRIPTION": null,
            "TTA_TIME_ACCOUNTED_MINS": null
        }
    ]
}

Request      

GET api/v3/time-tracking/activities

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Query Parameters

ids   string  optional    

Filter by comma-separated IDs Example: 1,2,3

worker_id   integer  optional    

Filter by worker/operator login ID Example: 294

work_id   integer  optional    

Filter by parent work ID Example: 10

Response

Response Fields

data   object     
TTA_ID   integer     

Time tracking activity ID (primary key).

TTA_TTW_ID   integer     

Work ID (references time_tracking_works). Identifies which work item this activity belongs to.

TTA_L_ID   integer     

Login (resource/worker) ID (references logins). The user who performed this activity.

TTA_DATE   string     

Activity date (format: YYYY-MM-DD).

TTA_TIME_FROM   string     

Activity start time (format: HH:MM:SS).

TTA_TIME_TO   string     

Activity end time (format: HH:MM:SS). NULL indicates a currently running activity.

TTA_TIME_TOTAL_MINS   integer     

Total tracked time in minutes. Computed from time_from/time_to when not set explicitly.

TTA_TIME_ACCOUNTED_MINS   integer     

Accounted (billable) time in minutes. May differ from total time for billing purposes.

TTA_APPROVED   integer     

Confirmed/approved flag. 1 = activity has been confirmed, 0 = not yet confirmed.

TTA_DESCRIPTION   string     

Activity description. May be mandatory depending on the parent work's settings.

work   object     

Related time tracking work item (TimeTrackingWork). Loaded when the relation is requested.

Create Time Tracking Activity

requires authentication

This endpoint creates a new time tracking activity.

Time input: provide either time_from + time_to OR time_total. Minimum 1 minute. Description is required if the parent work has mandatory description enabled.

Example request:
curl --request POST \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/time-tracking/activities" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"ttw_id\": 10,
    \"l_id\": 294,
    \"date\": \"2024-06-15\",
    \"time_from\": \"08:00:00\",
    \"time_to\": \"10:30:00\",
    \"time_total\": \"02:30:00\",
    \"approved\": false,
    \"description\": \"Server maintenance work\",
    \"time_accounted\": \"02:30:00\"
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/time-tracking/activities"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "ttw_id": 10,
    "l_id": 294,
    "date": "2024-06-15",
    "time_from": "08:00:00",
    "time_to": "10:30:00",
    "time_total": "02:30:00",
    "approved": false,
    "description": "Server maintenance work",
    "time_accounted": "02:30:00"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "data": {
        "TTA_ID": 632518,
        "TTA_TTW_ID": 899,
        "TTA_L_ID": 778,
        "TTA_DATE": "2007-02-06",
        "TTA_TIME_FROM": "04:54:01",
        "TTA_TIME_TO": "02:42:34",
        "TTA_TIME_TOTAL_MINS": 383,
        "TTA_APPROVED": 1,
        "TTA_DESCRIPTION": "Provident perspiciatis quo omnis nostrum aut adipisci quidem.",
        "TTA_TIME_ACCOUNTED_MINS": 362
    }
}

Request      

POST api/v3/time-tracking/activities

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Body Parameters

ttw_id   integer     

Parent work ID Example: 10

l_id   integer     

Worker/operator login ID Example: 294

date   string     

Activity date (YYYY-MM-DD). No future dates allowed. Example: 2024-06-15

time_from   string  optional    

Activity start time (HH:MM:SS). Provide with time_to, or use time_total instead. Example: 08:00:00

time_to   string  optional    

Activity end time (HH:MM:SS). Provide with time_from, or use time_total instead. Example: 10:30:00

time_total   string  optional    

Total time (HH:MM:SS). Alternative to time_from + time_to. Minimum 00:01:00. Example: 02:30:00

approved   boolean  optional    

Approved/confirmed flag (false=draft, true=confirmed) Example: false

description   string  optional    

Activity description (max 255 chars). Required if parent work has mandatory description. Example: Server maintenance work

time_accounted   string  optional    

Accounted time for billing (HH:MM:SS). May differ from total due to rounding rules. Example: 02:30:00

Response

Response Fields

data   object     
TTA_ID   integer     

Time tracking activity ID (primary key).

TTA_TTW_ID   integer     

Work ID (references time_tracking_works). Identifies which work item this activity belongs to.

TTA_L_ID   integer     

Login (resource/worker) ID (references logins). The user who performed this activity.

TTA_DATE   string     

Activity date (format: YYYY-MM-DD).

TTA_TIME_FROM   string     

Activity start time (format: HH:MM:SS).

TTA_TIME_TO   string     

Activity end time (format: HH:MM:SS). NULL indicates a currently running activity.

TTA_TIME_TOTAL_MINS   integer     

Total tracked time in minutes. Computed from time_from/time_to when not set explicitly.

TTA_TIME_ACCOUNTED_MINS   integer     

Accounted (billable) time in minutes. May differ from total time for billing purposes.

TTA_APPROVED   integer     

Confirmed/approved flag. 1 = activity has been confirmed, 0 = not yet confirmed.

TTA_DESCRIPTION   string     

Activity description. May be mandatory depending on the parent work's settings.

work   object     

Related time tracking work item (TimeTrackingWork). Loaded when the relation is requested.

Get Time Tracking Activity

requires authentication

This endpoint retrieves a specific time tracking activity by ID.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/time-tracking/activities/architecto" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/time-tracking/activities/architecto"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": {
        "TTA_ID": 632519,
        "TTA_TTW_ID": 592,
        "TTA_L_ID": 751,
        "TTA_DATE": "2006-09-25",
        "TTA_TIME_FROM": "20:47:12",
        "TTA_TIME_TO": "23:42:48",
        "TTA_TIME_TOTAL_MINS": 160,
        "TTA_APPROVED": 0,
        "TTA_DESCRIPTION": null,
        "TTA_TIME_ACCOUNTED_MINS": null
    }
}

Request      

GET api/v3/time-tracking/activities/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   string     

The ID of the activity. Example: architecto

Response

Response Fields

data   object     
TTA_ID   integer     

Time tracking activity ID (primary key).

TTA_TTW_ID   integer     

Work ID (references time_tracking_works). Identifies which work item this activity belongs to.

TTA_L_ID   integer     

Login (resource/worker) ID (references logins). The user who performed this activity.

TTA_DATE   string     

Activity date (format: YYYY-MM-DD).

TTA_TIME_FROM   string     

Activity start time (format: HH:MM:SS).

TTA_TIME_TO   string     

Activity end time (format: HH:MM:SS). NULL indicates a currently running activity.

TTA_TIME_TOTAL_MINS   integer     

Total tracked time in minutes. Computed from time_from/time_to when not set explicitly.

TTA_TIME_ACCOUNTED_MINS   integer     

Accounted (billable) time in minutes. May differ from total time for billing purposes.

TTA_APPROVED   integer     

Confirmed/approved flag. 1 = activity has been confirmed, 0 = not yet confirmed.

TTA_DESCRIPTION   string     

Activity description. May be mandatory depending on the parent work's settings.

work   object     

Related time tracking work item (TimeTrackingWork). Loaded when the relation is requested.

Update Time Tracking Activity

requires authentication

This endpoint updates an existing time tracking activity.

Only the activity owner can edit unless the user has TIMETRACKING.EDIT_OTHERS_ACTIVITIES right.

Example request:
curl --request PUT \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/time-tracking/activities/architecto" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"ttw_id\": 10,
    \"l_id\": 294,
    \"date\": \"2024-06-15\",
    \"time_from\": \"08:00:00\",
    \"time_to\": \"10:30:00\",
    \"time_total\": \"02:30:00\",
    \"approved\": false,
    \"description\": \"Updated description\",
    \"time_accounted\": \"02:30:00\"
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/time-tracking/activities/architecto"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "ttw_id": 10,
    "l_id": 294,
    "date": "2024-06-15",
    "time_from": "08:00:00",
    "time_to": "10:30:00",
    "time_total": "02:30:00",
    "approved": false,
    "description": "Updated description",
    "time_accounted": "02:30:00"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "data": {
        "TTA_ID": 632520,
        "TTA_TTW_ID": 899,
        "TTA_L_ID": 778,
        "TTA_DATE": "2007-02-06",
        "TTA_TIME_FROM": "04:54:01",
        "TTA_TIME_TO": "02:42:34",
        "TTA_TIME_TOTAL_MINS": 383,
        "TTA_APPROVED": 1,
        "TTA_DESCRIPTION": "Provident perspiciatis quo omnis nostrum aut adipisci quidem.",
        "TTA_TIME_ACCOUNTED_MINS": 362
    }
}

Request      

PUT api/v3/time-tracking/activities/{id}

PATCH api/v3/time-tracking/activities/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   string     

The ID of the activity. Example: architecto

Body Parameters

ttw_id   integer  optional    

Parent work ID Example: 10

l_id   integer  optional    

Worker/operator login ID Example: 294

date   string  optional    

Activity date (YYYY-MM-DD). No future dates allowed. Example: 2024-06-15

time_from   string  optional    

Activity start time (HH:MM:SS) Example: 08:00:00

time_to   string  optional    

Activity end time (HH:MM:SS) Example: 10:30:00

time_total   string  optional    

Total time (HH:MM:SS). Alternative to time_from + time_to. Example: 02:30:00

approved   boolean  optional    

Approved/confirmed flag Example: false

description   string  optional    

Activity description (max 255 chars) Example: Updated description

time_accounted   string  optional    

Accounted time for billing (HH:MM:SS) Example: 02:30:00

Response

Response Fields

data   object     
TTA_ID   integer     

Time tracking activity ID (primary key).

TTA_TTW_ID   integer     

Work ID (references time_tracking_works). Identifies which work item this activity belongs to.

TTA_L_ID   integer     

Login (resource/worker) ID (references logins). The user who performed this activity.

TTA_DATE   string     

Activity date (format: YYYY-MM-DD).

TTA_TIME_FROM   string     

Activity start time (format: HH:MM:SS).

TTA_TIME_TO   string     

Activity end time (format: HH:MM:SS). NULL indicates a currently running activity.

TTA_TIME_TOTAL_MINS   integer     

Total tracked time in minutes. Computed from time_from/time_to when not set explicitly.

TTA_TIME_ACCOUNTED_MINS   integer     

Accounted (billable) time in minutes. May differ from total time for billing purposes.

TTA_APPROVED   integer     

Confirmed/approved flag. 1 = activity has been confirmed, 0 = not yet confirmed.

TTA_DESCRIPTION   string     

Activity description. May be mandatory depending on the parent work's settings.

work   object     

Related time tracking work item (TimeTrackingWork). Loaded when the relation is requested.

Delete Time Tracking Activity

requires authentication

This endpoint deletes a time tracking activity.

Only the activity owner can delete unless the user has TIMETRACKING.EDIT_OTHERS_ACTIVITIES right.

Example request:
curl --request DELETE \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/time-tracking/activities/architecto" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/time-tracking/activities/architecto"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

Example response (204):

Empty response

Request      

DELETE api/v3/time-tracking/activities/{id}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

id   string     

The ID of the activity. Example: architecto

Token Management

List Location Tokens

requires authentication

Returns location tokens visible to the current login within allowed CT scope.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/locations/tokens" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/locations/tokens"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200, List of location personal access tokens):


{
    "data": [
        {
            "id": 32,
            "name": "aut",
            "abilities": [
                "all"
            ],
            "last_used_at": null,
            "expires_at": null,
            "created_at": "2026-04-15T14:55:08.000000Z",
            "tokenable_type": "App\\Models\\Login",
            "tokenable": {
                "ID": 5552,
                "FIRST_NAME": "Noah",
                "SURNAME": "Cronin",
                "LOGIN": "emelie.baumbach",
                "PASSWORD": "random_password",
                "L_LEVEL": 10,
                "MAIL": "[email protected]",
                "PHONE": null,
                "NOTE": "Aut dolores enim non facere tempora ex voluptatem. Praesentium quis adipisci molestias fugit. Distinctio eum doloremque id aut libero aliquam veniam corporis. Mollitia deleniti nemo odit quia officia.",
                "SALESMAN": 0,
                "L_SMS_ENABLE": 0,
                "L_PIN": null,
                "LOG_LEVEL": "INFO",
                "L_CP_ID": "0484",
                "L_CREATED": "2026-03-03 05:14:19",
                "L_L_ID": 82,
                "L_ACTIVE": 0,
                "L_PASS_EXPIRE": -19,
                "L_PASS_CHANGE": null,
                "L_TYPE": "COOPERATION",
                "L_SIGNATURE": "Aut quis ut dolores omnis et earum. Asperiores est vel id aut officiis eos. Et qui unde et.",
                "L_SELFCARE": 1,
                "L_PASS_CODE": "847820",
                "L_PASS_CODE_CREATED": null,
                "L_CACHE_INITIALS": "ew",
                "L_INITIALS": null,
                "L_STATISTICS_ENABLE": 1
            }
        },
        {
            "id": 33,
            "name": "molestiae",
            "abilities": [
                "all"
            ],
            "last_used_at": null,
            "expires_at": null,
            "created_at": "2026-04-15T14:55:08.000000Z",
            "tokenable_type": "App\\Models\\Login",
            "tokenable": {
                "ID": 5553,
                "FIRST_NAME": "Nina",
                "SURNAME": "Wisoky",
                "LOGIN": "jazmyne.heathcote",
                "PASSWORD": "random_password",
                "L_LEVEL": 3,
                "MAIL": "[email protected]",
                "PHONE": null,
                "NOTE": null,
                "SALESMAN": 1,
                "L_SMS_ENABLE": 1,
                "L_PIN": "3735",
                "LOG_LEVEL": "INFO",
                "L_CP_ID": null,
                "L_CREATED": "2026-04-10 14:43:30",
                "L_L_ID": 95,
                "L_ACTIVE": 1,
                "L_PASS_EXPIRE": null,
                "L_PASS_CHANGE": null,
                "L_TYPE": "COOPERATION",
                "L_SIGNATURE": null,
                "L_SELFCARE": 0,
                "L_PASS_CODE": null,
                "L_PASS_CODE_CREATED": "2026-01-30 07:43:25",
                "L_CACHE_INITIALS": "ix",
                "L_INITIALS": null,
                "L_STATISTICS_ENABLE": 1
            }
        }
    ]
}

Request      

GET api/v3/locations/tokens

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Response

Response Fields

data   object     
id   integer     

Unique token identifier.

name   string     

Token display name.

abilities   string[]     

List of token abilities/scopes.

last_used_at   string     

Timestamp when token was last used.

expires_at   string     

Token expiration timestamp.

created_at   string     

Token creation timestamp.

tokenable_type   string     

Type of the tokenable model.

tokenable   object     

Tokenable model instance.

Create Location Token

requires authentication

Creates a personal access token for a specific location. This operation is allowed only for administrator logins (L_CP_ID is null).

Example request:
curl --request POST \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/locations/001/tokens" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"name\": \"Mobile app token\",
    \"abilities\": [
        \"all\"
    ],
    \"expires_at\": \"2026-12-31T23:59:59Z\"
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/locations/001/tokens"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "name": "Mobile app token",
    "abilities": [
        "all"
    ],
    "expires_at": "2026-12-31T23:59:59Z"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (201, Location token created successfully):


{
    "data": {
        "plain_text_token": null,
        "token": null
    }
}

Request      

POST api/v3/locations/{location_ID}/tokens

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

location_ID   string     

Example: 001

Body Parameters

name   string     

Token name. Example: Mobile app token

abilities   string[]  optional    

Token abilities.

expires_at   string  optional    

Token expiration timestamp (ISO 8601). Example: 2026-12-31T23:59:59Z

Response

Response Fields

data   object     
plain_text_token   string     

Plain text token value shown only once after token creation.

token   object     

Created token metadata.

Revoke Location Token

requires authentication

Revokes a personal access token for a specific location within current scope.

Example request:
curl --request DELETE \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/locations/001/tokens/architecto" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/locations/001/tokens/architecto"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

Example response (204):

Empty response

Request      

DELETE api/v3/locations/{location_ID}/tokens/{tokenId}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

location_ID   string     

Example: 001

tokenId   string     

Example: architecto

List Login Tokens

requires authentication

Returns personal access tokens for the currently authenticated login. Tokens created through the login endpoint are excluded from this list.

Example request:
curl --request GET \
    --get "https://apiv3-test.devel.ogsoftdev.com/api/v3/tokens/login" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/tokens/login"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200, List of login personal access tokens):


{
    "data": [
        {
            "id": 34,
            "name": "adipisci",
            "abilities": [
                "all"
            ],
            "last_used_at": null,
            "expires_at": null,
            "created_at": "2026-04-15T14:55:08.000000Z",
            "tokenable_type": "App\\Models\\Login",
            "tokenable": {
                "ID": 5554,
                "FIRST_NAME": "Amber",
                "SURNAME": "Dare",
                "LOGIN": "wleuschke",
                "PASSWORD": "random_password",
                "L_LEVEL": 10,
                "MAIL": "[email protected]",
                "PHONE": 6431064321,
                "NOTE": "Voluptatem laboriosam praesentium quis adipisci. Fugit deleniti distinctio eum doloremque id aut libero. Veniam corporis dolorem mollitia.",
                "SALESMAN": 1,
                "L_SMS_ENABLE": 0,
                "L_PIN": "5182",
                "LOG_LEVEL": "INFO",
                "L_CP_ID": null,
                "L_CREATED": "2026-04-11 05:41:21",
                "L_L_ID": 39,
                "L_ACTIVE": 1,
                "L_PASS_EXPIRE": null,
                "L_PASS_CHANGE": null,
                "L_TYPE": "PERSON",
                "L_SIGNATURE": null,
                "L_SELFCARE": 1,
                "L_PASS_CODE": null,
                "L_PASS_CODE_CREATED": null,
                "L_CACHE_INITIALS": "kf",
                "L_INITIALS": null,
                "L_STATISTICS_ENABLE": 0
            }
        },
        {
            "id": 35,
            "name": "odit",
            "abilities": [
                "all"
            ],
            "last_used_at": null,
            "expires_at": null,
            "created_at": "2026-04-15T14:55:08.000000Z",
            "tokenable_type": "App\\Models\\Login",
            "tokenable": {
                "ID": 5555,
                "FIRST_NAME": "Walker",
                "SURNAME": "Bernhard",
                "LOGIN": "nkreiger",
                "PASSWORD": "random_password",
                "L_LEVEL": 2,
                "MAIL": "[email protected]",
                "PHONE": null,
                "NOTE": "Molestiae sunt suscipit doloribus fugiat ut aut. Et error neque recusandae et. Dolorem et ut dicta. Consequatur ut et sunt quisquam sit repellendus ut. Alias ratione dolores sed rem. Ut aut deserunt sint quis in quod id aspernatur.",
                "SALESMAN": 0,
                "L_SMS_ENABLE": 0,
                "L_PIN": "5425",
                "LOG_LEVEL": "INFO",
                "L_CP_ID": "0436",
                "L_CREATED": "2026-04-07 06:02:09",
                "L_L_ID": 2,
                "L_ACTIVE": 0,
                "L_PASS_EXPIRE": -273,
                "L_PASS_CHANGE": "2026-01-23 18:19:27",
                "L_TYPE": "COOPERATION",
                "L_SIGNATURE": "Aut ex quo iure eos explicabo accusamus. Et qui ipsa itaque autem mollitia.",
                "L_SELFCARE": 0,
                "L_PASS_CODE": null,
                "L_PASS_CODE_CREATED": null,
                "L_CACHE_INITIALS": "kz",
                "L_INITIALS": "aw",
                "L_STATISTICS_ENABLE": 0
            }
        }
    ]
}

Request      

GET api/v3/tokens/login

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Response

Response Fields

data   object     
id   integer     

Unique token identifier.

name   string     

Token display name.

abilities   string[]     

List of token abilities/scopes.

last_used_at   string     

Timestamp when token was last used.

expires_at   string     

Token expiration timestamp.

created_at   string     

Token creation timestamp.

tokenable_type   string     

Type of the tokenable model.

tokenable   object     

Tokenable model instance.

Create Login Token

requires authentication

Creates a new personal access token for the currently authenticated login. The plain text token is returned only once in the response.

Example request:
curl --request POST \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/tokens/login" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}" \
    --data "{
    \"name\": \"Mobile app token\",
    \"abilities\": [
        \"all\"
    ],
    \"expires_at\": \"2026-12-31T23:59:59Z\"
}"

const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/tokens/login"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};

let body = {
    "name": "Mobile app token",
    "abilities": [
        "all"
    ],
    "expires_at": "2026-12-31T23:59:59Z"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (201, Login token created successfully):


{
    "data": {
        "plain_text_token": null,
        "token": null
    }
}

Request      

POST api/v3/tokens/login

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

Body Parameters

name   string     

Token name. Example: Mobile app token

abilities   string[]  optional    

Token abilities.

expires_at   string  optional    

Token expiration timestamp (ISO 8601). Example: 2026-12-31T23:59:59Z

Response

Response Fields

data   object     
plain_text_token   string     

Plain text token value shown only once after token creation.

token   object     

Created token metadata.

Revoke Login Token

requires authentication

Revokes a personal access token owned by the currently authenticated login.

Example request:
curl --request DELETE \
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/tokens/login/0" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --header "X-CT: {{ct}}" \
    --header "X-Login-Id: {{loginId}}"
const url = new URL(
    "https://apiv3-test.devel.ogsoftdev.com/api/v3/tokens/login/0"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-CT": "{{ct}}",
    "X-Login-Id": "{{loginId}}",
};


fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

Example response (204):

Empty response

Request      

DELETE api/v3/tokens/login/{tokenId}

Headers

Authorization        

Example: Bearer {YOUR_AUTH_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

X-CT        

Example: {{ct}}

X-Login-Id        

Example: {{loginId}}

URL Parameters

tokenId   integer     

Example: 0