The Organizations service enables callers to manage (create, update, delete) organizations that belong to the same tenant. In the SBS entity model, an organization is an entity typically identified by a unique Tax Identification Number (TIN).
You typically create an organization in order to support submissions to the Romanian National Fiscal Authority (ANAF), such as tax declarations, e-Transport declarations, or electronic invoices (E-Factura). If there are multiple organizations in the same tenant for which you would like to submit data, then you can create them through this service.
You also need an organization if you intend to use the Tax Declarations Service for SAF-T reporting to Bulgarian National Fiscal Authority.
Access info
|
|
| Endpoint |
https://organizations-api.socrate.io/graphql |
| Required access keys |
Tenant-level service access key |
| Pricing |
Check the available purchase options. |
| Notes |
To call the service, the access key must be provided in the x-api-key header of the HTTP request. If you are using the GraphQL console, you can view the service’s documentation and schema only after entering an access key. Make sure that the scope of the key allows access to the queries and mutations that you require. For example, to grant the key access to all queries and mutations, the key’s scope must be set to organizations-api:query:* organizations-api:mutation:*. |
Queries
organization
Returns an organization given the organization ID.
Arguments
| Argument |
Type |
Description |
| id |
ID! |
Mandatory. The ID of the organization to be retrieved. |
Result
The result is a object of type Organization.
organizations
Returns a list of organizations defined for the given tenant, optionally filtered by specific organization IDs.
Arguments
| Argument |
Type |
Description |
| filter |
OrganizationsFilter |
Optional. Provides the ability to filter results by organization ID. |
| Attribute |
Type |
Description |
| active |
Boolean |
Optional. Set this filter to true to retrieve only organizations marked as active, false otherwise. |
Result
The result is an array of Organization.
Organization type
| Attribute |
Type |
Description |
| id |
ID! |
Specifies the organization’s unique identifier. |
| validFrom |
Date |
Specifies the date when the organization was registered, in YYYY-MM-DD format. |
| name |
String |
Specifies the organization’s name. |
| tin |
String |
Specifies the organization’s tax identification number (TIN) (in Romanian, CIF - cod de identificare fiscală) issued by ANAF (in Romanian, ANAF - Agenția Națională de Administrare Fiscală). |
| regNo |
String |
Specifies the organization’s registration number issued by the National Trade Registration Office (in Romanian, ONRC - Oficiul National al Registrului Comerțului). |
| caenNo |
String |
Specifies the organization’s number registered in the CAEN nomenclature (in Romanian, CAEN - Clasificarea activităților din economia națională). |
| taxType |
String |
Identifies the type of tax regime to which this entry applies. Valid values originate in the nomenclature Nomenclator_Regim_fiscal and are as follows: 100010 - Taxable person registered for VAT purposes, 100020 - Taxable person applying the special exemption scheme for small enterprises, 100030 - Taxable person who has the VAT code canceled ex officio, based on Law 227/2015 on the Fiscal Code, art. 316 para. (11), 100040 - Taxable person registered for VAT purposes, who applies the VAT system on collection, 100050 - Non-taxable person. |
| country |
CountryCode |
Enum value that identifies the ISO 3166-2 two-letter country code. |
| region |
String |
Identifies the regions/counties/provinces within the tax authority. Preferably described according to ISO 3166-1A2 - RO Dept Codes. Example: RO-AB for Alba county in Romania. |
| streetAddress |
Address |
Specifies the organization’s street address. |
| postalAddress |
Address |
Specifies the organization’s postal address. |
| billingAddress |
Address |
Specifies the organization’s billing address. |
| shipToAddress |
Address |
Specifies the organization’s “ship to” address. |
| shipFromAddress |
Address |
Specifies the organization’s “ship from” address. |
| email |
EmailAddress |
Specifies the organization’s email. |
| phone |
String |
Specifies the organization’s phone number. |
| bankAccounts |
[BankAccount] |
The list of organization’s bank accounts. |
| taxAccountingBasis |
TaxAccountingBasis |
The organization’s tax accounting basis. For valid values, see Appendix 1: Tax Accounting Basis. |
| createdAt |
DateTime |
The date and time when the organization record was created in SBS. |
| active |
Boolean! |
A Boolean flag that marks organization as not active if set to false. Inactive organizations do not appear in the graphical user interface of the SBS Portal. This flag may also be used for other purposes in your application. Note that it does not affect processing organizations in SBS as such (for example, it is still possible to generate a tax declaration even if the organization is not active). |
| ownershipStructureBG |
ownershipStructureBG |
Applicable only if the organization is used in Bulgarian SAF-T reporting. Defines the ownership structure of the organization for Bulgarian tax reporting purposes. |
Address type
| Attribute |
Type |
Description |
| streetName |
String |
The street name. |
| number |
String |
The street number. |
| additionalAddressDetails |
String |
Any additional address details that don’t fit elsewhere. |
| building |
String |
The building identifier, if applicable. |
| city |
String |
The city. |
| postalCode |
String |
The postal code. |
| region |
String |
The region/county/province. |
| country |
CountryCode |
Enum value that identifies the ISO 3166-2 two-letter country code. |
BankAccount type
| Attribute |
Type |
Description |
| ibanNumber |
String |
The international bank account number (IBAN). |
| bankAccountNumber |
String |
The bank account number. |
| bankAccountName |
String |
The bank account name. |
| sortCode |
String |
The bank sorting code. |
OwnershipStructureBG type
| Attribute |
Type |
Description |
| groupMembership |
GroupMembershipBG |
Applicable only if the organization is used in Bulgarian SAF-T reporting. |
| beneficialOwners |
BeneficialOwnerBG |
Applicable only if the organization is used in Bulgarian SAF-T reporting. |
| ultimateOwners |
UltimateOwnerBG |
Applicable only if the organization is used in Bulgarian SAF-T reporting. |
BeneficialOwnerBG type
| Attribute |
Type |
Description |
| nameCyrillicBG |
String |
Applicable only if the organization is used in Bulgarian SAF-T reporting. For the definition, see Structures > Ownership Structure > BeneficialOwnerNameCyrillicBG in the Bulgarian SAF-T Schema. |
| egn |
String |
Applicable only if the organization is used in Bulgarian SAF-T reporting. For the definition, see Structures > Ownership Structure > BeneficialOwnerEGN in the Bulgarian SAF-T Schema. |
| nameLatinForeign |
String |
Applicable only if the organization is used in Bulgarian SAF-T reporting. For the definition, see Structures > Ownership Structure > BeneficialOwnerNameLatinForeign in the Bulgarian SAF-T Schema. |
| countryForeign |
CountryCode |
Applicable only if the organization is used in Bulgarian SAF-T reporting. For the definition, see Structures > Ownership Structure > BeneficialCountryForeign in the Bulgarian SAF-T Schema. Valid values are any of the ISO 3166-2 two-letter country codes. |
| countryForeignCode |
CountryCode |
Applicable only if the organization is used in Bulgarian SAF-T reporting. For the definition, see Structures > Ownership Structure > BeneficialCountryForeignCode in the Bulgarian SAF-T Schema. Valid values are any of the ISO 3166-2 two-letter country codes. |
UltimateOwnerBG type
| Attribute |
Type |
Description |
| nameCyrillicBG |
String |
Applicable only if the organization is used in Bulgarian SAF-T reporting. For the definition, see Structures > Ownership Structure > UltimateOwnerNameCyrillicBG in the Bulgarian SAF-T Schema. |
| uicBG |
String |
Applicable only if the organization is used in Bulgarian SAF-T reporting. For the definition, see Structures > Ownership Structure > UltimateOwnerUICBG in the Bulgarian SAF-T Schema. |
| nameCyrillicForeign |
String |
Applicable only if the organization is used in Bulgarian SAF-T reporting. For the definition, see Structures > Ownership Structure > UltimateOwnerNameCyrillicForeign in the Bulgarian SAF-T Schema. |
| nameLatinForeign |
String |
Applicable only if the organization is used in Bulgarian SAF-T reporting. For the definition, see Structures > Ownership Structure > UltimateOwnerNameLatinForeign in the Bulgarian SAF-T Schema. |
| countryForeign |
CountryCode |
Applicable only if the organization is used in Bulgarian SAF-T reporting. For the definition, see Structures > Ownership Structure > CountryForeign in the Bulgarian SAF-T Schema. Valid values are any of the ISO 3166-2 two-letter country codes. |
version
Returns the API version.
Mutations
createOrganization
Creates an organization. Once an organization is created, it can be referenced multiple times by different declarations.
Arguments
| Argument |
Type |
Description |
| input |
CreateOrganizationInput! |
Mandatory. Used to provide the organization’s details as input. |
| Attribute |
Type |
Description |
| validFrom |
Date |
Optional. Specifies the date when the organization was registered, in YYYY-MM-DD format. |
| name |
String! |
Mandatory. Specifies the organization’s name. |
| tin |
String |
Optional. Specifies the organization’s tax identification number (TIN) (in Romanian, CIF - cod de identificare fiscală) issued by ANAF (in Romanian, ANAF - Agenția Națională de Administrare Fiscală). |
| regNo |
String! |
Mandatory. Specifies the organization’s registration number issued by the National Trade Registration Office (in Romanian, ONRC - Oficiul National al Registrului Comerțului). |
| caenNo |
String |
Optional. Specifies the organization’s number registered in the CAEN nomenclature (in Romanian, CAEN - Clasificarea activităților din economia națională). |
| taxType |
String |
Optional. Identifies the type of tax regime to which this entry applies. Valid values originate in the nomenclature Nomenclator_Regim_fiscal and are as follows: 100010 - Taxable person registered for VAT purposes, 100020 - Taxable person applying the special exemption scheme for small enterprises, 100030 - Taxable person who has the VAT code canceled ex officio, based on Law 227/2015 on the Fiscal Code, art. 316 para. (11), 100040 - Taxable person registered for VAT purposes, who applies the VAT system on collection, 100050 - Non-taxable person. |
| country |
CountryCode! |
Mandatory. Enum value that identifies the ISO 3166-2 two-letter country code. |
| region |
String |
Optional. Identifies the regions/counties/provinces within the tax authority. Preferably described according to ISO 3166-1A2 - RO Dept Codes. Example: RO-AB for Alba county in Romania. |
| streetAddress |
Address |
Optional. Specifies the organization’s street address. |
| postalAddress |
Address |
Optional. Specifies the organization’s postal address. |
| billingAddress |
Address |
Optional. Specifies the organization’s billing address. |
| shipToAddress |
Address |
Optional. Specifies the organization’s “ship to” address. |
| shipFromAddress |
Address |
Optional. Specifies the organization’s “ship from” address. |
| email |
EmailAddress |
Optional. Specifies the organization’s email. |
| phone |
String |
Optional. Specifies the organization’s phone number. |
| bankAccounts |
[BankAccount] |
Optional. The list of organization’s bank accounts. |
| taxAccountingBasis |
TaxAccountingBasis |
Optional. The organization’s tax accounting basis. For valid values, see Appendix 1: Tax Accounting Basis. |
| ownershipStructureBG |
OwnershipStructureBGInput |
Mandatory if the organization is used in Bulgarian SAF-T reporting; optional otherwise. This field defines the ownership structure of the organization for tax reporting purposes. |
| Attribute |
Type |
Description |
| groupMembership |
GroupMembershipBG |
As defined in Structures > Ownership Structure > IsPartOfGroup in the Bulgarian SAF-T Schema. Valid values: ParentLocalGroup - Централа на местна група, ParentMultinationalGroup - Централа на мултинационална група, SubsidiaryLocalGroup - Част от местна група, SubsidiaryMultinationalGroup - Част от мултинационална група, None - Не. |
| beneficialOwners |
[BeneficialOwnerBGInput] |
An array of beneficial owners. |
| ultimateOwners |
[UltimateOwnerBGInput] |
An array of ultimate owners. |
| Attribute |
Type |
Description |
| nameCyrillicBG |
String |
As defined in Structures > Ownership Structure > BeneficialOwnerNameCyrillicBG in the Bulgarian SAF-T Schema. |
| egn |
String |
As defined in Structures > Ownership Structure > BeneficialOwnerEGN in the Bulgarian SAF-T Schema. |
| nameLatinForeign |
String |
As defined in Structures > Ownership Structure > BeneficialOwnerNameLatinForeign in the Bulgarian SAF-T Schema. |
| countryForeign |
CountryCode |
As defined in Structures > Ownership Structure > BeneficialCountryForeign in the Bulgarian SAF-T Schema. Valid values are any of the ISO 3166-2 two-letter country codes. |
| countryForeignCode |
CountryCode |
As defined in Structures > Ownership Structure > BeneficialCountryForeignCode in the Bulgarian SAF-T Schema. Valid values are any of the ISO 3166-2 two-letter country codes. |
| Attribute |
Type |
Description |
| nameCyrillicBG |
String |
As defined in Structures > Ownership Structure > UltimateOwnerNameCyrillicBG in the Bulgarian SAF-T Schema. |
| uicBG |
String |
As defined in Structures > Ownership Structure > UltimateOwnerUICBG in the Bulgarian SAF-T Schema. |
| nameCyrillicForeign |
String |
As defined in Structures > Ownership Structure > UltimateOwnerNameCyrillicForeign in the Bulgarian SAF-T Schema. |
| nameLatinForeign |
String |
As defined in Structures > Ownership Structure > UltimateOwnerNameLatinForeign in the Bulgarian SAF-T Schema. |
| countryForeign |
CountryCode |
As defined in Structures > Ownership Structure > CountryForeign in the Bulgarian SAF-T Schema. Valid values are any of the ISO 3166-2 two-letter country codes. |
Result
See the Organization type.
deleteOrganization
Deletes an organization.
Arguments
| Argument |
Type |
Description |
| id |
ID! |
Mandatory. The ID of the organization that is to be deleted. |
Result
See the Organization type.
updateOrganization
Updates an organization.
Arguments
| Argument |
Type |
Description |
| id |
ID! |
Mandatory. Used to provide the ID of the organization that is to be updated. |
| input |
UpdateOrganizationInput! |
Mandatory. Used to provide the organization’s details as input. |
| Attribute |
Type |
Description |
| validFrom |
Date |
Specifies the date when the organization was registered. |
| name |
String |
Specifies the organization’s name. |
| tin |
String |
Specifies the organization’s tax identification number (TIN) (in Romanian, CIF - cod de identificare fiscală) issued by ANAF (in Romanian, ANAF - Agenția Națională de Administrare Fiscală). |
| regNo |
String! |
Specifies the organization’s registration number issued by the National Trade Registration Office (in Romanian, ONRC - Oficiul National al Registrului Comerțului). |
| caenNo |
String |
Specifies the organization’s number registered in the CAEN nomenclature (in Romanian, CAEN - Clasificarea activităților din economia națională). |
| taxType |
String |
Identifies the type of tax regime to which this entry applies. Valid values originate in the nomenclature Nomenclator_Regim_fiscal and are as follows: 100010 - Taxable person registered for VAT purposes, 100020 - Taxable person applying the special exemption scheme for small enterprises, 100030 - Taxable person who has the VAT code canceled ex officio, based on Law 227/2015 on the Fiscal Code, art. 316 para. (11), 100040 - Taxable person registered for VAT purposes, who applies the VAT system on collection, 100050 - Non-taxable person. |
| country |
CountryCode |
Enum value that identifies the ISO 3166-2 two-letter country code. |
| region |
String |
Identifies the regions/counties/provinces within the tax authority. Preferably described according to ISO 3166-1A2 - RO Dept Codes. Example: RO-AB for Alba county in Romania. |
| streetAddress |
Address |
Specifies the organization’s street address. |
| postalAddress |
Address |
Specifies the organization’s postal address. |
| billingAddress |
Address |
Specifies the organization’s billing address. |
| shipToAddress |
Address |
Specifies the organization’s “ship to” address. |
| shipFromAddress |
Address |
Specifies the organization’s “ship from” address. |
| email |
EmailAddress |
Specifies the organization’s email. |
| phone |
String |
Specifies the organization’s phone number. |
| bankAccounts |
[BankAccount] |
The list of organization’s bank accounts. |
| taxAccountingBasis |
TaxAccountingBasis |
The organization’s tax accounting basis. For valid values, see Appendix 1: Tax Accounting Basis. |
| active |
Boolean |
A Boolean flag that marks organization as not active if set to false. Inactive organizations do not appear in the graphical user interface of the SBS Portal. This flag may also be used for other purposes in your application. Note that it does not affect processing organizations in SBS as such (for example, it is still possible to generate a tax declaration even if the organization is not active). |
| ownershipStructureBG |
OwnershipStructureBGInput |
Optional. This input structure should be provided only if the organization is used in Bulgarian SAF-T reporting. |
Result
See the Organization type.
Appendices
Appendix 1: Tax Accounting Basis
| Code |
Description |
| A |
Accounting for general commercial companies which apply double-entry bookkeeping and the general business chart of accounts. |
| BANK |
Credit institutions and non-bank financial institutions that apply apply double-entry bookkeeping and chart of accounts for banks and financial-monetary institutions. |
| I |
Invoice Accounting (Non-Residents). |
| IFN |
Non-banking financial institutions in Romania that use the account plan according to the BNR Regulation no. 17/2015. |
| IFRS |
General commercial companies that apply double-entry taxability at the same time as the provisions of OMFP 2844/2016 (IFRS chart of accounts). |
| INSURANCE |
Insurance companies applying applies double entry taxation and chart of accounts for insurance companies. |
| NORMA14 |
Private pension companies which use the account plan according to the regulation no. 14/2015 of the Authority for Financial Supervision (ASF). |
| NORMA36 |
Insurance and/or reinsurance brokerage companies which use the account plan according to the regulation no. 36/2015 of the Authority for Financial Supervision (ASF). |
| NORMA39 |
Leasing and financial companies which use the IFRS account plan according the Reg no. 39/2015 of the Authority for Financial Supervision (ASF). |
| ONG |
Companies without patrimonial purpose (non-government organizations) according to the OMFP no. 3103/2017. |
| ONGE |
Non-profit legal entities (NGOs) according to OMFP no. 3103/2017 - legal entities with a VAT code for economic activity. |
| P |
Public entities (public utilities, public transport, public health services, etc). Applicable for Bulgaria only. |