Sign in

v1

latestOpenAPI 3.0.02026-07-2436163302.7 KB

Onboard a company

Each transaction consists of at least two parties: Supplier and Customer. In most cases, the Supplier will be a company. On the other side of the transaction, the Customer can be an individual (B2C transaction) or a company (B2B transaction).

  • Supplier — Usually a business.
  • Customer — Can be an individual (B2C transaction) or a company (B2B transaction).

This Company onboarding endpoint allows you to onboard Supplier and Customer companies into the Fonoa system. If the Customer is an individual (i.e., B2C transaction) and its details need to be reported to the tax authority, you should use the individual onboarding endpoint.

When you are the Supplier and are using Fonoa to generate invoices or report transactions for your own company, you can use this endpoint to give us your company information. If you are a marketplace with multiple Suppliers, you can use this endpoint to onboard each active Supplier.

To report invoices in real-time to a tax authority, you need to onboard the Supplier, and in some scenarios the Customer too, that participate in the transaction.

post/onboarding/v2/companies

Request body

company_numberstring required

Company’s local identification number, usually identical to TIN.

Validations:

  • Required property
  • Length between 1 and 50
establishment_datestring

The date when the company was established or business activity started. Establishment Date should be in ISO8601 standard.

legal_formstring

Legal form of the company, complementing legal_name. e.g. SARL AU CAPITAL DE 50 000 EUROS.

Validations:

  • This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
legal_namestring required

The company's legal name.

Validations:

  • Required property
  • Length between 1 and 450
logostring

url of the logo to be used in invoice documents for this company

registration_placestring

Official register and place where the company is recorded, e.g. RCS Paris (FR), Amtsgericht München (DE).

Validations:

  • This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard.
representative_emailstring
representative_namestring
trade_namestring

Validations:

  • Length between 0 and 450

Example request

{
  "address": {
    "address_line_1": "123 Main Street",
    "address_line_2": "Suite 400",
    "canton": "Zürich",
    "city": "San Francisco",
    "city_code": "SF123",
    "country_code": "US",
    "district": "Financial District",
    "neighbourhood": "Downtown",
    "number": "123",
    "postal_code": "94105",
    "prefix": "North",
    "province": "Ontario",
    "region": "Midwest",
    "state": "California",
    "suffix": "Avenue"
  },
  "company_number": "123456789",
  "contact_details": {
    "certified_email": "certified@company.com",
    "email": "contact@company.com",
    "phone_number": "+1-800-123-4567",
    "website": "https://www.company.com"
  },
  "legal_name": "Fonoa Inc.",
  "tax_credentials": {
    "certificate_base64": "MIIDdzCCAl+gAwIBAgIEbFJ...",
    "certificate_password": "securePassword123",
    "certificate_private_key_base64": "MIIEvQIBADANBgkqhkiG9w0B...",
    "certificate_type": "pkcs12",
    "password": "Pa$$w0rdSecure!",
    "pin": "1234",
    "username": "tax_user_001"
  },
  "tax_information": {
    "activity_code": "ACT-200",
    "additional_tax_numbers": [
      {
        "country_code": "US",
        "country_subdivision_code": "CA",
        "tax_number": "123456789"
      }
    ],
    "authorization_code": "AUTH-987654",
    "billing_file_number": "BFN-00123",
    "device_id": "DEVICE-456789",
    "document_type": "INVOICE",
    "eac_code": "6201",
    "point_of_sale": "POS-1001",
    "regime": "VAT",
    "tax_code": "TX-001",
    "tax_number": "123456789"
  }
}

Response

Accepted - company was successfully onboarded.

messagestring
statusstring

Example response

{
  "data": {
    "job_id": "fad3e91a0a46489cbcb82db1693df05b"
  },
  "errors": [
    {
      "type": "validation"
    }
  ],
  "status": "success"
}