HowToRomania Validation API

The Validation API from HowToRomania — 2 operation(s) for validation.

GitHub OpenAPI

Operations 2

POST /v1/validate Check extracted company data (2 credits) #
POST /v1/validate/format Free format check (no key) #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/howtoromania-io:howtoromania-io-validation-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

howtoromania-io-validation-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: HowToRomania Validation API
  version: 0.5.0
  description: 'Data from Romanian public registries for AI agents. €5 = 1,000 credits (€0.005/credit) · €20 = 5,000 · €100 = 30,000. 100 free credits per key. Errors, not-found and source outages (e.g. ANAF unreachable) are not billed; a risk report with some sections unavailable is billed in full. Demo key: htr_demo (limited daily calls per IP; company.lookup, court.case, efactura.validate, efactura.parse, legislation.search, legislation.article, legislation.new).'
  contact:
    email: hello@howtoromania.io
    url: https://howtoromania.io
servers:
- url: https://api.howtoromania.io
security:
- apiKey: []
- bearer: []
tags:
- name: Validation
paths:
  /v1/validate:
    post:
      operationId: validate_extracted_company_data
      summary: Check extracted company data (2 credits)
      description: Checks CUI, name, registration number, VAT status, company status, address, IBAN and (optional) legal representative an AI extracted from an invoice or contract against ANAF and ONRC; verdict per field and a confidence score (pass / review / reject). +5 credits with legalRepresentative, +1 with an invoice block
      tags:
      - Validation
      x-credits: 2
      responses:
        '200':
          description: OK
          headers:
            x-credits-used:
              description: Credits charged for this call. 0 when the call was not billed
              schema:
                type: integer
                description: Credits charged
            x-credits-remaining:
              description: Credit balance after this call. Omitted for an admin key
              schema:
                type: integer
                description: Credits left
          content:
            application/json:
              schema:
                description: JSON body
                type: object
                properties:
                  data:
                    description: Registry check of extracted company data
                    type: object
                    properties:
                      overall:
                        description: Combined verdict
                        type: object
                        properties:
                          verdict:
                            description: pass, review, or reject
                            type: string
                          confidence:
                            description: 0 to 1. At least 0.90 is pass, 0.60 to 0.89 is review, below 0.60 is reject
                            type: number
                      fields:
                        description: Checked fields, keyed by name (cui, name, registrationNumber, vatRegistered, status, address, iban, legalRepresentative)
                        type: object
                        properties: {}
                        additionalProperties:
                          description: Result for one checked field
                          type: object
                          properties:
                            verdict:
                              description: valid, corrected, partial, invalid, not_found, or unverifiable
                              type: string
                            input:
                              description: Value that was sent
                              type: string
                            value:
                              description: Registered or normalized value, when known
                              type: string
                            reason:
                              description: Why the field failed or could not be checked
                              type: string
                            similarity:
                              description: Name similarity from 0 to 1, when names were compared
                              type: number
                            vatId:
                              description: RO-prefixed VAT id when the company is VAT-registered
                              type: string
                            since:
                              description: Date the status started, YYYY-MM-DD
                              type: string
                            cashAccounting:
                              description: True when cash-accounting VAT applies
                              type: boolean
                            asOf:
                              description: Date used for this field, YYYY-MM-DD
                              type: string
                            bankCode:
                              description: Romanian bank code from the IBAN, e.g. BTRL
                              type: string
                            bank:
                              description: Bank name decoded from a Romanian IBAN, or null
                              type: string
                            country:
                              description: IBAN country code
                              type: string
                            treasury:
                              description: True when the IBAN is a Treasury account
                              type: boolean
                            normalized:
                              description: Company name after legal-form normalization
                              type: string
                            parsed:
                              description: Parsed trade-register number
                              type: object
                              properties:
                                letter:
                                  description: J, F, or C
                                  type: string
                                year:
                                  description: Registration year
                                  type: integer
                                number:
                                  description: Sequence number
                                  type: integer
                                county:
                                  description: County code, or null when the number is not county-specific
                                  type: integer
                                format:
                                  description: old (J40/123/2020) or new (J2020000123400)
                                  type: string
                                checkDigit:
                                  description: Trailing digit of the new format. Not verified
                                  type: integer
                            issues:
                              description: Problems found. Empty when the check passed
                              type: array
                              items:
                                description: One problem
                                type: string
                      invoice:
                        description: Result for one checked field
                        type: object
                        properties:
                          verdict:
                            description: valid, corrected, partial, invalid, not_found, or unverifiable
                            type: string
                          input:
                            description: Value that was sent
                            type: string
                          value:
                            description: Registered or normalized value, when known
                            type: string
                          reason:
                            description: Why the field failed or could not be checked
                            type: string
                          similarity:
                            description: Name similarity from 0 to 1, when names were compared
                            type: number
                          vatId:
                            description: RO-prefixed VAT id when the company is VAT-registered
                            type: string
                          since:
                            description: Date the status started, YYYY-MM-DD
                            type: string
                          cashAccounting:
                            description: True when cash-accounting VAT applies
                            type: boolean
                          asOf:
                            description: Date used for this field, YYYY-MM-DD
                            type: string
                          bankCode:
                            description: Romanian bank code from the IBAN, e.g. BTRL
                            type: string
                          bank:
                            description: Bank name decoded from a Romanian IBAN, or null
                            type: string
                          country:
                            description: IBAN country code
                            type: string
                          treasury:
                            description: True when the IBAN is a Treasury account
                            type: boolean
                          normalized:
                            description: Company name after legal-form normalization
                            type: string
                          parsed:
                            description: Parsed trade-register number
                            type: object
                            properties:
                              letter:
                                description: J, F, or C
                                type: string
                              year:
                                description: Registration year
                                type: integer
                              number:
                                description: Sequence number
                                type: integer
                              county:
                                description: County code, or null when the number is not county-specific
                                type: integer
                              format:
                                description: old (J40/123/2020) or new (J2020000123400)
                                type: string
                              checkDigit:
                                description: Trailing digit of the new format. Not verified
                                type: integer
                          issues:
                            description: Problems found. Empty when the check passed
                            type: array
                            items:
                              description: One problem
                              type: string
                      warnings:
                        description: Warnings to show a reviewer
                        type: array
                        items:
                          description: One warning
                          type: string
                      sources:
                        description: Public sources that were queried
                        type: array
                        items:
                          description: One source
                          type: object
                          properties:
                            name:
                              description: Source name
                              type: string
                            queriedForDate:
                              description: Date asked of ANAF, YYYY-MM-DD
                              type: string
                            fetchedAt:
                              description: ISO timestamp of the read
                              type: string
                      asOf:
                        description: Date used for the check, YYYY-MM-DD
                        type: string
                      scoringVersion:
                        description: Scoring-rules version
                        type: string
                      disclaimer:
                        description: Checked against public sources and checksums. Not a KYC/AML check. A structurally valid IBAN does not prove the account belongs to the company
                        type: string
                  billing:
                    description: Credits charged for this call
                    type: object
                    properties:
                      creditsUsed:
                        description: Credits charged. 0 when the call was free or not billed
                        type: integer
                      creditsRemaining:
                        description: Balance after this call. Null for an admin key
                        type: integer
                      note:
                        description: Why part or all of the charge was not billed, when that happened
                        type: string
        '400':
          description: Invalid input (not billed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Out of credits; body explains how to buy a pack
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRequired'
        '403':
          description: Endpoint not included in the demo key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found (not billed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Demo key limit reached for this IP. Rate-limited per IP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '451':
          description: Court case closed more than 3 years ago, withheld for data protection (code unavailable_data_protection, not billed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: Upstream error (not billed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Extracted company data to check against ANAF and ONRC
              required:
              - party
              properties:
                party:
                  description: Company data extracted from a document. Only cui is required
                  type: object
                  properties:
                    cui:
                      description: Romanian CUI, e.g. 12345674 or RO12345674
                      type: string
                    name:
                      description: Company name as extracted, e.g. FIRMA S.R.L. Max 300 characters
                      type: string
                    registrationNumber:
                      description: Trade register number, old J40/123/2020 or new J2020000123400. Max 300 characters
                      type: string
                    vatRegistered:
                      description: Whether the document claims the company is VAT-registered
                      type: boolean
                    address:
                      description: Address as printed. Max 300 characters
                      type: string
                    iban:
                      description: IBAN as printed, spaces optional, e.g. RO49AAAA1B31007593840000
                      type: string
                    legalRepresentative:
                      description: Name of the person who signed. Adds 5 credits. Never stored; only match or no match is returned
                      type: string
                  required:
                  - cui
                invoice:
                  description: Invoice amounts to check. total should equal net + VAT
                  type: object
                  properties:
                    number:
                      description: Invoice number as printed, e.g. FCT-1
                      type: string
                    date:
                      description: Invoice date, YYYY-MM-DD
                      type: string
                      format: date
                    currency:
                      description: ISO 4217 code, e.g. RON or EUR
                      type: string
                    net:
                      description: Net amount before VAT
                      type: number
                    vat:
                      description: VAT amount
                      type: number
                    total:
                      description: Gross total
                      type: number
                    vatRates:
                      description: VAT percents on the invoice, e.g. 21 or 11
                      type: array
                      items:
                        description: One VAT percent
                        type: number
                asOfDate:
                  type: string
                  format: date
                  description: Date the document claims, YYYY-MM-DD. Default today (Europe/Bucharest)
            example:
              party:
                cui: RO12345674
                name: FIRMA S.R.L.
                registrationNumber: J40/1234/2020
                vatRegistered: true
                address: Bucuresti, Sector 1, Str. Exemplu nr. 1
                iban: RO49AAAA1B31007593840000
              invoice:
                date: '2026-10-20'
                net: 100
                vat: 21
                total: 121
                vatRates:
                - 21
  /v1/validate/format:
    post:
      operationId: check_identifier_format
      summary: Free format check (no key)
      description: 'Free, no key: POST /v1/validate/format {cui?, iban?, registrationNumber?, name?, invoice?} · MCP check_identifier_format · local checks only (CUI and IBAN checksums, trade register number format, name normalization, invoice arithmetic). Does not check that the company exists; the last digit of new-format trade register numbers is not verified. Rate-limited per IP.'
      tags:
      - Validation
      security: []
      x-credits: 0
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: At least one of cui, iban, registrationNumber, name or invoice
              properties:
                cui:
                  type: string
                  description: Romanian CUI to checksum, e.g. 12345674 or RO12345674. Does not check that the company exists
                iban:
                  type: string
                  description: IBAN to checksum, spaces optional, e.g. RO49AAAA1B31007593840000
                registrationNumber:
                  type: string
                  description: Trade register number, old J40/123/2020 or new J2020000123400. The last digit of the new format is not verified
                name:
                  type: string
                  description: Company name to normalize, e.g. FIRMA S.R.L. Max 300 characters
                invoice:
                  description: Invoice amounts to check. total should equal net + VAT
                  type: object
                  properties:
                    number:
                      description: Invoice number as printed, e.g. FCT-1
                      type: string
                    date:
                      description: Invoice date, YYYY-MM-DD
                      type: string
                      format: date
                    currency:
                      description: ISO 4217 code, e.g. RON or EUR
                      type: string
                    net:
                      description: Net amount before VAT
                      type: number
                    vat:
                      description: VAT amount
                      type: number
                    total:
                      description: Gross total
                      type: number
                    vatRates:
                      description: VAT percents on the invoice, e.g. 21 or 11
                      type: array
                      items:
                        description: One VAT percent
                        type: number
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: Format-check result
                properties:
                  data:
                    description: Local format check. No registry lookup
                    type: object
                    properties:
                      fields:
                        description: One entry per field you sent
                        type: object
                        properties: {}
                        additionalProperties:
                          description: Result for one checked field
                          type: object
                          properties:
                            verdict:
                              description: valid, corrected, partial, invalid, not_found, or unverifiable
                              type: string
                            input:
                              description: Value that was sent
                              type: string
                            value:
                              description: Registered or normalized value, when known
                              type: string
                            reason:
                              description: Why the field failed or could not be checked
                              type: string
                            similarity:
                              description: Name similarity from 0 to 1, when names were compared
                              type: number
                            vatId:
                              description: RO-prefixed VAT id when the company is VAT-registered
                              type: string
                            since:
                              description: Date the status started, YYYY-MM-DD
                              type: string
                            cashAccounting:
                              description: True when cash-accounting VAT applies
                              type: boolean
                            asOf:
                              description: Date used for this field, YYYY-MM-DD
                              type: string
                            bankCode:
                              description: Romanian bank code from the IBAN, e.g. BTRL
                              type: string
                            bank:
                              description: Bank name decoded from a Romanian IBAN, or null
                              type: string
                            country:
                              description: IBAN country code
                              type: string
                            treasury:
                              description: True when the IBAN is a Treasury account
                              type: boolean
                            normalized:
                              description: Company name after legal-form normalization
                              type: string
                            parsed:
                              description: Parsed trade-register number
                              type: object
                              properties:
                                letter:
                                  description: J, F, or C
                                  type: string
                                year:
                                  description: Registration year
                                  type: integer
                                number:
                                  description: Sequence number
                                  type: integer
                                county:
                                  description: County code, or null when the number is not county-specific
                                  type: integer
                                format:
                                  description: old (J40/123/2020) or new (J2020000123400)
                                  type: string
                                checkDigit:
                                  description: Trailing digit of the new format. Not verified
                                  type: integer
                            issues:
                              description: Problems found. Empty when the check passed
                              type: array
                              items:
                                description: One problem
                                type: string
                      checks:
                        description: 'Always local only: checksums, formats, normalization and arithmetic'
                        type: string
                      scoringVersion:
                        description: Rules version
                        type: string
                  billing:
                    description: Credits charged for this call
                    type: object
                    properties:
                      creditsUsed:
                        description: Credits charged. 0 when the call was free or not billed
                        type: integer
                      creditsRemaining:
                        description: Balance after this call. Null for an admin key
                        type: integer
                      note:
                        description: Why part or all of the charge was not billed, when that happened
                        type: string
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Free format-check limit reached. Rate-limited per IP
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      description: Error body
      type: object
      properties:
        error:
          description: What went wrong
          type: object
          properties:
            code:
              description: Stable code, e.g. invalid_input, not_found, unauthorized, rate_limited, insufficient_credits
              type: string
            message:
              description: What went wrong, and whether the call was billed
              type: string
            retryAfterSeconds:
              description: Seconds to wait, on some rate-limit responses
              type: integer
            balance:
              description: Credit balance, on some billing errors
              type: integer
          additionalProperties: true
    PaymentRequired:
      description: Out of credits
      type: object
      properties:
        error:
          description: insufficient_credits
          type: object
          properties:
            code:
              description: Always insufficient_credits
              type: string
              const: insufficient_credits
            message:
              description: Out-of-credits explanation and how to buy a pack
              type: string
        balance:
          description: Credits remaining
          type: integer
        topup:
          description: How to buy credits
          type: object
          properties:
            howTo:
              description: Next step. When purchases are paused this says so, without a checkout link
              type: string
            purchasesPaused:
              description: True when checkout is closed
              type: boolean
            packs:
              description: Credit packs
              type: array
              items:
                description: One credit pack
                type: object
                properties:
                  id:
                    description: starter, pro, or scale
                    type: string
                  credits:
                    description: Credits in the pack
                    type: integer
                  price:
                    description: Price including VAT, e.g. 5.00 EUR
                    type: string
                  checkout:
                    description: Checkout URL. Present when purchases are open
                    type: string
                    format: uri
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API key, or the public demo key on the endpoints that accept it
    bearer:
      type: http
      scheme: bearer
      description: 'Same API key as a bearer token: Authorization: Bearer <key>'
externalDocs:
  url: https://api.howtoromania.io/docs
x-mcp:
  url: https://api.howtoromania.io/mcp
  transport: streamable-http