--- title: "Onboard an individual" method: POST path: "/onboarding/v2/individuals" --- # Onboard an individual `POST /onboarding/v2/individuals` 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 - `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. - `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 - `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.net/fonoa/apis/fonoa-api.md) · [All operations](https://skmtc.net/fonoa/apis/fonoa-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fonoa/fonoa-api/versions/cf0ebc843a3f/schema)