--- title: "Onboard an individual" method: POST path: "/onboarding/v2/individuals" tags: ["Onboarding"] --- # Onboard an individual `POST /onboarding/v2/individuals` ## Request - The document declares no server URL. - Auth: API key in header `Ocp-Apim-Subscription-Key` Similar to the Company onboarding, the Individual onboarding endpoint allows you to onboard any individual or physical person who is part of a transaction. In most cases (i.e. B2C transactions), the Customer will be a physical person and you should use this endpoint to onboard them. ## Request body - OnboardingIndividualRequest - `address` OnboardingAddress - `address_line_1` string: The primary street address, including street name and house/building number. Validations: - Length between 0 and 450 - `address_line_2` string: Additional address details, such as apartment, suite, or floor number. Validations: - Length between 0 and 450 - `canton` string: A territorial division, commonly used in countries like Switzerland. Validations: - Length between 0 and 100 - `city` string: The municipality or urban area where the company is located. Validations: - Length between 0 and 100 - `city_code` string: A numerical or alphanumerical code representing the city. Validations: - Length between 0 and 20 - `country_code` string, required: Address country where the entity is registered. Country code must be in ISO 3166-1 two-letter format. Validations: - Required property - Exact length: 2 - `district` string: A smaller administrative unit within a province, state, or region. Validations: - Length between 0 and 100 - `neighbourhood` string: A specific area or locality within a city or town. Validations: - Length between 0 and 100 - `number` string: The specific number of the building or property on the street. Validations: - Length between 0 and 20 - `postal_code` string: The code used by postal services to identify specific delivery areas. Validations: - Length between 0 and 100 - `prefix` string: An optional element that comes before the street name. Validations: - Length between 0 and 20 - `province` string: The administrative division within a country, larger than a region or district. Validations: - Length between 0 and 100 - `region` string: A broader geographical area, often grouping multiple provinces or states. Validations: - Length between 0 and 100 - `state` string: A major administrative division within a country. Validations: - Length between 0 and 100 - `suffix` string: An optional element that comes after the street name. Validations: - Length between 0 and 20 - `contact_details` OnboardingContactDetails - `attention_to` string: The person or department to direct the document to. - `certified_email` string: Certified email address used for official or legal communications, often required in specific jurisdictions. - `email` string: Primary email address for contacting the company. Validations: - Length between 0 and 250 - Must be a valid email address. - `phone_number` string: Primary phone number for reaching the company. Validations: - Length between 0 and 250 - `website` string: Official website URL of the company. Validations: - Length between 0 and 250 - `full_name` string, required: Full name of the individual Validations: - Required property - Length between 1 and 450 - `meta` OnboardingMeta - `country_code` string, required: 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.) Validations: - Required property - Length ({{.actual}}) must be {{.max}} characters long. - Country code must be ISO 3166-1 alpha-2. - `external_id` string: An additional reference identifier you can provide - typically, the identifier used in your own system. Used for idempotency and available in the Fonoa dashboard - `language_code` string: 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.) - `transaction_purposes` string[]: Workflow operations this company may be used for (e.g. ta_notification, document_generation). Validations: - Must contain one or more of: document_generation, ta_notification, data_access, record_to_report - `webhook` string - `operator` boolean - `personal_number` string, required: Specifies a unique personal identifier for a b2c customer. This can be customers’ email address, account number, etc. Used for deduplication purposes. Validations: - Required property - Length between 1 and 50 - `personal_number_type` string: Validations: - Length between 0 and 20 - `tax_information` OnboardingTaxInformation - `activity_code` string: Code representing the business activity of the entity. - `additional_tax_numbers` OnboardingTaxNumberCountrySpecific[]: Additional tax numbers used by the business entity in domestic or foreign operations. Validations: - 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. - `business_model` string[]: Specifies the business model under which the company operates, such as B2B (Business-to-Business) or B2C (Business-to-Consumer). Validations: - Must be empty or contain one or more of the following values: B2B, B2C - `country_code` string, required: ISO 3166-1 two-letter country code representing the country where the tax number is registered. Validations: - Country code must be uppercase ISO 3166-1 alpha-2. - Required property - `country_subdivision_code` string: Code representing a specific subdivision within the country, such as a state or province. Validations: - Exact length: 2 - `tax_number` string, required: The specific tax identification number assigned to the company for the specified country. Validations: - Length between 0 and 50 - Required property - `type` string: Indicates the type of tax number. Currently unsupported for onboarding. Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard. - `authorization_code` string: Code provided by tax authorities to authorize tax-related activities. - `billing_file_number` string: Unique number assigned to the company’s billing file. - `cash_vat_scheme` boolean: Indicates whether the company is under the cash VAT scheme. - `device_id` string: Identifier for the device used in tax reporting or invoicing systems. - `distribution_address` string: Value to be used by the Tax Authority to forward the reported invoice to the customer/buyer Validations: - Maximum length: 256 - `document_type` string: Type of tax-related document issued or managed by the company. - `eac_code` string: Economic Activity Code representing the nature of business activities. - `point_of_sale` string: Code representing the company’s point of sale location or terminal. - `regime` string: The tax regime under which the company operates. Validations: - Length between 0 and 10 - `reporting_mandate` string: Reporting mandate the supplier operates under. For ES: TICKETBAI or SII (empty defaults to SII). Validations: - This field is only supported in specific use cases, refer to country-specific integration guides in the Fonoa dashboard. - `tax_code` string: Tax code that complements the tax number. - `tax_number` string: Tax identification number of the company. Validations: - Length between 0 and 50 ## Response `202` Accepted - individual was successfully onboarded. - ApiResponseWrapperOnboardingAccepted - `data` OnboardingAccepted - `job_id` string: The identifier for the job. - `job_status_location` string: Full job URL that can be used for polling. - `errors` ErrorResponse[]: List of errors for the job. Returns `null` if it is successful. - `code` string: Code describing the error. - `doc_link` string: The link for the error documentation. Follow it to gather more details about the error - `field` string: A validation error can specify the field that generated that error. - `message` string: Detailed message containing information on how to resolve the error. - `type` string: Type of error: validation, tax_authority, warning, general, unknown. - `message` string - `status` string ## Other responses - `400`: Bad customer request - some of the provided information is incorrect or mandatory data is missing. Check the message and errors section of the response for more details. - `401`: Authentication failed - missing or incorrect subscription key. - `409`: Conflict - the individual already exists. - `429`: Too many requests were sent for a short period of time. Try again a bit later. - `5XX`: 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. --- [API](https://skmtc.dev/fonoa/apis/fonoa-e-invoicing.md) - [All operations](https://skmtc.dev/fonoa/apis/fonoa-e-invoicing/llms.txt) - [OpenAPI document](https://skmtc.dev/fonoa/apis/fonoa-e-invoicing/revisions/d38890cb6fcd?raw)