--- updatedAt: 2026-05-29T11:03:35.000Z agentTools: projectIndex: https://docs.fonoa.com/llms.txt --- # Get a list companies Used to search for successfully onboarded companies. # OpenAPI definition ```json { "components": { "schemas": { "ApiResponseWrapperEmpty": { "properties": { "data": { "type": "string" }, "errors": { "description": "List of errors for request. Returns `null` if it is successful.", "items": { "$ref": "#/components/schemas/ErrorResponse" }, "type": "array" }, "message": { "type": "string" }, "status": { "description": "The status of the request.", "type": "string" } }, "type": "object" }, "ApiResponseWrapperPageResponse": { "properties": { "limit": { "type": "integer" }, "next_cursor": { "type": "string" } }, "type": "object" }, "ApiResponseWrapperSearchCompaniesResponse": { "properties": { "data": { "description": "Validations:\n- Required property", "items": { "$ref": "#/components/schemas/OnboardingCompanyResponse" }, "type": "array" }, "errors": { "description": "List of errors. Returns `null` if it is successful.", "items": { "$ref": "#/components/schemas/ErrorResponse" }, "type": "array" }, "message": { "type": "string" }, "pagination": { "allOf": [ { "$ref": "#/components/schemas/ApiResponseWrapperPageResponse" } ], "type": "object" }, "status": { "example": "success", "type": "string" }, "transactions_summary_totals": { "description": "Summary of transactions processed for all filtered companies within the provided reporting_date period. Available for companies onboarded for the Accounts Payable flow", "items": { "$ref": "#/components/schemas/TransactionsSummary" }, "type": "array" } }, "required": [ "data" ], "type": "object" }, "DocumentsReceptionContext": { "properties": { "reception_enabled": { "description": "Indicates whether document reception is enabled.", "type": "boolean" } }, "type": "object" }, "ErrorResponse": { "properties": { "code": { "description": "Code describing the error.", "type": "string" }, "doc_link": { "description": "The link for the error documentation. Follow it to gather more details about the error", "type": "string" }, "field": { "description": "A validation error can specify the field that generated that error.", "type": "string" }, "message": { "description": "Detailed message containing information on how to resolve the error.", "type": "string" }, "type": { "description": "Type of error: validation, tax_authority, warning, general, unknown.", "example": "validation", "type": "string" } }, "type": "object" }, "OnboardingActivationResponse": { "properties": { "status": { "description": "Represents the current activation status. Valid values include: `ACTIVATION_PENDING`, `ACTIVE`, `DEACTIVATION_PENDING`, and `FAILED`.", "type": "string" }, "transaction_purpose": { "description": "Indicates the purpose of the transaction associated with this activation. Possible values are `ta_notification` and `document_exchange`.", "type": "string" }, "url": { "description": "A direct URL that the user should visit to complete or verify the activation process.", "type": "string" } }, "type": "object" }, "OnboardingAddress": { "properties": { "address_line_1": { "description": "The primary street address, including street name and house/building number.\n\nValidations:\n- Length between 0 and 450", "example": "123 Main Street", "type": "string" }, "address_line_2": { "description": "Additional address details, such as apartment, suite, or floor number.\n\nValidations:\n- Length between 0 and 450", "example": "Suite 400", "type": "string" }, "canton": { "description": "A territorial division, commonly used in countries like Switzerland.\n\nValidations:\n- Length between 0 and 100", "example": "Zürich", "type": "string" }, "city": { "description": "The municipality or urban area where the company is located.\n\nValidations:\n- Length between 0 and 100", "example": "San Francisco", "type": "string" }, "city_code": { "description": "A numerical or alphanumerical code representing the city.\n\nValidations:\n- Length between 0 and 20", "example": "SF123", "type": "string" }, "country_code": { "description": "Address country where the entity is registered. Country code must be in ISO 3166-1 two-letter format.\n\nValidations:\n- Required property\n- Exact length: 2", "example": "US", "type": "string" }, "district": { "description": "A smaller administrative unit within a province, state, or region.\n\nValidations:\n- Length between 0 and 100", "example": "Financial District", "type": "string" }, "neighbourhood": { "description": "A specific area or locality within a city or town.\n\nValidations:\n- Length between 0 and 100", "example": "Downtown", "type": "string" }, "number": { "description": "The specific number of the building or property on the street.\n\nValidations:\n- Length between 0 and 20", "example": "123", "type": "string" }, "postal_code": { "description": "The code used by postal services to identify specific delivery areas.\n\nValidations:\n- Length between 0 and 100", "example": "94105", "type": "string" }, "prefix": { "description": "An optional element that comes before the street name.\n\nValidations:\n- Length between 0 and 20", "example": "North", "type": "string" }, "province": { "description": "The administrative division within a country, larger than a region or district.\n\nValidations:\n- Length between 0 and 100", "example": "Ontario", "type": "string" }, "region": { "description": "A broader geographical area, often grouping multiple provinces or states.\n\nValidations:\n- Length between 0 and 100", "example": "Midwest", "type": "string" }, "state": { "description": "A major administrative division within a country.\n\nValidations:\n- Length between 0 and 100", "example": "California", "type": "string" }, "suffix": { "description": "An optional element that comes after the street name.\n\nValidations:\n- Length between 0 and 20", "example": "Avenue", "type": "string" } }, "required": [ "country_code" ], "type": "object" }, "OnboardingCompanyResponse": { "properties": { "activations": { "items": { "$ref": "#/components/schemas/OnboardingActivationResponse" }, "type": "array" }, "address": { "allOf": [ { "$ref": "#/components/schemas/OnboardingAddress" } ], "type": "object" }, "company_number": { "description": "Company’s local identification number, usually identical to TIN.", "type": "string" }, "contact_details": { "allOf": [ { "$ref": "#/components/schemas/OnboardingContactDetails" } ], "type": "object" }, "created_at": { "description": "The date at which the company was successfully onboarded.", "type": "string" }, "document_template_id": { "description": "Optional supplier-specific custom invoice HTML template id (DocumentTemplate.uid)", "type": "string" }, "documents_reception_context": { "allOf": [ { "$ref": "#/components/schemas/DocumentsReceptionContext" } ], "description": "Document reception context.", "type": "object" }, "establishment_address": { "allOf": [ { "$ref": "#/components/schemas/OnboardingAddress" } ], "description": "The official address of the company's establishment, if different from the legal address.", "type": "object" }, "establishment_date": { "description": "The date when the company was established or business activity started. Establishment Date should be in ISO8601 standard.", "type": "string" }, "id": { "description": "The Fonoa identifier for the company.", "type": "string" }, "legal_form": { "description": "Legal form of the company, complementing legal_name. e.g. SARL AU CAPITAL DE 50 000 EUROS.", "type": "string" }, "legal_name": { "description": "The legal name of the onboarded entity.", "type": "string" }, "logo": { "description": "url of the logo to be used in invoice documents for this company", "type": "string" }, "meta": { "allOf": [ { "$ref": "#/components/schemas/OnboardingMeta" } ], "type": "object" }, "registration_place": { "description": "Official register and place where the company is recorded, e.g. RCS Paris (FR), Amtsgericht München (DE).", "type": "string" }, "representative_email": { "type": "string" }, "representative_name": { "type": "string" }, "tax_credentials": { "allOf": [ { "$ref": "#/components/schemas/OnboardingTaxCredentialsResponse" } ], "type": "object" }, "tax_information": { "allOf": [ { "$ref": "#/components/schemas/OnboardingTaxInformation" } ], "type": "object" }, "template_configuration": { "allOf": [ { "$ref": "#/components/schemas/OnboardingTemplateConfiguration" } ], "description": "Settings related to how your invoicing template will look like - like color, font", "type": "object" }, "trade_name": { "type": "string" }, "transactions_summary_totals": { "description": "Summary of transactions processed for the company within the provided reporting_date period. Available when filtering for Account Payable companies.", "items": { "$ref": "#/components/schemas/TransactionsSummary" }, "type": "array" }, "updated_at": { "description": "The date at which the company was last updated through a PATCH request. Returns `null` if no updates were performed.", "type": "string" } }, "type": "object" }, "OnboardingContactDetails": { "properties": { "attention_to": { "description": "The person or department to direct the document to.", "example": "John Doe", "type": "string" }, "certified_email": { "description": "Certified email address used for official or legal communications, often required in specific jurisdictions.", "example": "certified@company.com", "type": "string" }, "email": { "description": "Primary email address for contacting the company.\n\nValidations:\n- Length between 0 and 250\n- Must be a valid email address.", "example": "contact@company.com", "type": "string" }, "phone_number": { "description": "Primary phone number for reaching the company.\n\nValidations:\n- Length between 0 and 250", "example": "+1-800-123-4567", "type": "string" }, "website": { "description": "Official website URL of the company.\n\nValidations:\n- Length between 0 and 250", "example": "https://www.company.com", "type": "string" } }, "type": "object" }, "OnboardingMeta": { "properties": { "country_code": { "description": "Specifies the country of the entity that needs to be onboarded. Country code must be in ISO 3166-1 two-letter format (e.g, us, de, fr, etc.)\n\nValidations:\n- Required property\n- Length ({{.actual}}) must be {{.max}} characters long.\n- Country code must be ISO 3166-1 alpha-2.", "type": "string" }, "external_id": { "description": "An additional reference identifier you can provide - typically, the identifier used in your own system. Used for idempotency and available in the Fonoa dashboard", "type": "string" }, "language_code": { "description": "Specifies the language of the entity that needs to be onboarded. Language code must be in ISO 639-1 two-letter format (e.g, en, de, fr, etc.)", "type": "string" }, "transaction_purposes": { "description": "Workflow operations this company may be used for (e.g. ta_notification, document_generation).\n\nValidations:\n- Must contain one or more of: document_generation, ta_notification, data_access, record_to_report", "items": { "type": "string" }, "type": "array" }, "webhook": { "type": "string" } }, "required": [ "country_code" ], "type": "object" }, "OnboardingTaxCredentialsResponse": { "properties": { "certificate_type": { "type": "string" }, "issuer": { "type": "string" }, "owner": { "type": "string" }, "username": { "type": "string" }, "valid_from": { "type": "string" }, "valid_to": { "type": "string" }, "verified": { "type": "boolean" } }, "type": "object" }, "OnboardingTaxInformation": { "properties": { "activity_code": { "description": "Code representing the business activity of the entity.", "example": "ACT-200", "type": "string" }, "additional_tax_numbers": { "description": "Additional tax numbers used by the business entity in domestic or foreign operations.\n\nValidations:\n- The provided additional tax number items must not contain conflicting business models for the same country and/or subdivision code. Each business model can only appear once per country or subdivision code.", "items": { "$ref": "#/components/schemas/OnboardingTaxNumberCountrySpecific" }, "type": "array" }, "authorization_code": { "description": "Code provided by tax authorities to authorize tax-related activities.", "example": "AUTH-987654", "type": "string" }, "billing_file_number": { "description": "Unique number assigned to the company’s billing file.", "example": "BFN-00123", "type": "string" }, "cash_vat_scheme": { "description": "Indicates whether the company is under the cash VAT scheme.", "example": "true", "type": "boolean" }, "device_id": { "description": "Identifier for the device used in tax reporting or invoicing systems.", "example": "DEVICE-456789", "type": "string" }, "distribution_address": { "description": "Value to be used by the Tax Authority to forward the reported invoice to the customer/buyer\n\nValidations:\n- Maximum length: 256", "example": "someone@email.com", "type": "string" }, "document_type": { "description": "Type of tax-related document issued or managed by the company.", "example": "INVOICE", "type": "string" }, "eac_code": { "description": "Economic Activity Code representing the nature of business activities.", "example": "6201", "type": "string" }, "point_of_sale": { "description": "Code representing the company’s point of sale location or terminal.", "example": "POS-1001", "type": "string" }, "regime": { "description": "The tax regime under which the company operates.\n\nValidations:\n- Length between 0 and 10", "example": "VAT", "type": "string" }, "reporting_mandate": { "description": "Reporting mandate the supplier operates under. For ES: TICKETBAI or SII (empty defaults to SII).\n\nValidations:\n- This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.", "example": "TICKETBAI", "type": "string" }, "tax_code": { "description": "Tax code that complements the tax number.", "example": "TX-001", "type": "string" }, "tax_number": { "description": "Tax identification number of the company.\n\nValidations:\n- Length between 0 and 50", "example": "123456789", "type": "string" } }, "type": "object" }, "OnboardingTaxNumberCountrySpecific": { "properties": { "business_model": { "description": "Specifies the business model under which the company operates, such as B2B (Business-to-Business) or B2C (Business-to-Consumer).\n\nValidations:\n- Must be empty or contain one or more of the following values: B2B, B2C", "example": "B2B", "items": { "type": "string" }, "type": "array" }, "country_code": { "description": "ISO 3166-1 two-letter country code representing the country where the tax number is registered.\n\nValidations:\n- Country code must be uppercase ISO 3166-1 alpha-2.\n- Required property", "example": "US", "type": "string" }, "country_subdivision_code": { "description": "Code representing a specific subdivision within the country, such as a state or province.\n\nValidations:\n- Exact length: 2", "example": "CA", "type": "string" }, "tax_number": { "description": "The specific tax identification number assigned to the company for the specified country.\n\nValidations:\n- Length between 0 and 50\n- Required property", "example": "123456789", "type": "string" }, "type": { "description": "Indicates the type of tax number. Currently unsupported for onboarding.\n\nValidations:\n- This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.", "type": "string" } }, "required": [ "country_code", "tax_number" ], "type": "object" }, "OnboardingTemplateConfiguration": { "properties": { "color": { "description": "The hexadecimal color value used for the invoice - example: 293d62\n\nValidations:\n- Required property\n- Invalid HEX color format provided.", "type": "string" }, "font": { "description": "The font used for the invoice. Some of the supported fonts include Abhaya Libre, Helvetica World, Hind, Lora, Open Sans, Rubik, among others. If you wish to have your own font please reach out to Fonoa support.\n\nValidations:\n- Required property", "type": "string" }, "logo_placement": { "description": "Where on the invoice your logo will be placed - left or right\n\nValidations:\n- Required property\n- Values allowed are (letter case matters): left, right", "type": "string" } }, "required": [ "color", "font", "logo_placement" ], "type": "object" }, "TransactionsSummary": { "properties": { "count": { "description": "Number of successfully processed transactions.", "type": "integer" }, "currency_code": { "description": "The currency code used for the amounts, in ISO 4217 format (e.g., USD, EUR).", "type": "string" }, "total_amount": { "description": "Represents the invoice total, i.e. the absolute value of the total_net_amount + total_tax_amount", "type": "number" }, "total_net_amount": { "description": "Total amount excl. Tax. Represents the sum of all 'Net Total amounts per item'.", "type": "number" }, "total_tax_amount": { "description": "The absolute value of the Tax amount. Sum of all `tax_breakdown[].amount`", "type": "number" } }, "type": "object" } }, "securitySchemes": { "ApiKeyAuth": { "in": "header", "name": "Ocp-Apim-Subscription-Key", "type": "apiKey" } } }, "info": { "title": "Fonoa E-invoicing", "version": "1.0.0" }, "openapi": "3.0.0", "paths": { "/onboarding/v2/companies": { "get": { "description": "Used to search for successfully onboarded companies.", "parameters": [ { "description": "Search by company number", "in": "query", "name": "company_number", "schema": { "type": "string" } }, { "description": "Search by company country code", "in": "query", "name": "country_code", "schema": { "type": "string" } }, { "description": "Define start company ID - used for pagination", "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "description": "Search by transaction creation date - date from - date and time in UTC in format RFC3339. e.g. 2022-03-31T23:59:59Z", "in": "query", "name": "date_from", "schema": { "type": "string" } }, { "description": "Search by transaction creation date - date to - date and time in UTC in format RFC3339. e.g. 2022-03-31T23:59:59Z", "in": "query", "name": "date_to", "schema": { "type": "string" } }, { "description": "Search by company external unique identifier", "in": "query", "name": "external_id", "schema": { "type": "string" } }, { "description": "Define page size - default 25 - used for pagination", "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "Search by company name", "in": "query", "name": "name", "schema": { "type": "string" } }, { "description": "Reporting date for the transactions summary, it does not filter the companies but the transactions to be included in the summary - reporting date from - date and time in UTC in format RFC3339. e.g. 2022-03-31T23:59:59Z", "in": "query", "name": "reporting_date_from", "schema": { "type": "string" } }, { "description": "Reporting date for the transactions summary, it does not filter the companies but the transactions to be included in the summary - reporting date to - date and time in UTC in format RFC3339. e.g. 2022-03-31T23:59:59Z", "in": "query", "name": "reporting_date_to", "schema": { "type": "string" } }, { "description": "Define sort order - default ascending", "in": "query", "name": "sort", "schema": { "type": "string" } }, { "description": "Search by status of company tax credentials", "in": "query", "name": "tax_credentials_status", "schema": { "type": "string" } }, { "description": "Search by company tax number", "in": "query", "name": "tax_number", "schema": { "type": "string" } }, { "description": "Direction of the transactions generated by the company", "in": "query", "name": "transactions_direction", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseWrapperSearchCompaniesResponse" } } }, "description": "Ok - search finished successfully." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseWrapperEmpty" } } }, "description": "Bad customer request - any of the provided query parameters is incorrect. See the error response for more details." }, "401": { "description": "Authentication failed - missing or incorrect subscription key." }, "429": { "description": "Too many requests were sent for a short period of time. Try again a bit later." }, "5XX": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponseWrapperEmpty" } } }, "description": "Internal server error. Its not you, its us! We are experiencing a rare and unexpected system disruption. Retry again later. The message field of the response will contain more information for the cause. Feel free to contact us." } }, "summary": "Get a list companies", "tags": [ "Onboarding" ] } } }, "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "Onboarding" } ] } ```