---
title: "POST /onboardings"
method: POST
path: "/onboardings"
tags: ["Onboarding"]
---

# POST /onboardings

`POST /onboardings`

## [Partners] Start onboarding a new business

If you haven't visited the guide: [how to make your first loan?](https://developers.getdefacto.com/reference/make-your-first-loan) we recommend you to visit it first.

**Timeout after**: 30 seconds (status code will be 504 in such a case)

In order to request loans you will need to have borrowers. In order to test borrower's eligibility, we'll need
to have access to borrower business' financial data.

This can be achieved in two ways:
Either you have this piece of information and you may use the
[sharing business data](https://developers.getdefacto.com/reference/post_business-data-account-transactions)
API documentation to do so, or you might want to rely on defacto's onboarding process to get this information.

In the later, you will need to create an onboarding for the business you want to request loans for.

### Behavior
When you send this API request providing business information, your referral and callback url:
The system will start an onboarding for you and you will get its id in the response.

Then you must redirect the borrower to the onboarding tunnel so that he can select his financial
tools and share as much data as he wants to max-out his eligible amount:

- **In the normal case**, redirect him to
  `https://app.getdefacto.com/onboarding/continue/{onboarding_id}`.
- **When the response contains a `secure_resume_link`**, redirect him to that link *instead* of the
  bare continue URL above. This happens when the business already has a bank-connected onboarding:
  to avoid exposing another party's financial data, that tunnel is gated and can only be reopened by
  a link carrying a short-lived secure token. The `secure_resume_link` is exactly that
  pre-authenticated continue URL. It is valid for **2 hours** — if it expires, POST /onboarding again
  to obtain a fresh one.

Once borrower has accepted defacto's T&Cs and created his account, he'll be redirected back to the redirect_url
you provided and if you subscribed to `CREDIT_LINE.Created` webhook you will receive it shortly.
Read [webhook](https://developers.getdefacto.com/reference/webhooks-at-defacto) for details.

### Frequently Asked Questions

**How do I get onboarding results?**
You can use the GET /onboarding/{onboarding_id} endpoint to retrieve the onboarding results.

**What should I do if the status of the onboarding is expired?**
Onboardings last for 168 hours;
after what you'll have to repeat the POST /onboarding request you just made.

**How do I get the borrower's ID once onboarding is `COMPLETED`?**
You can use the GET /onboarding/{onboarding_id} endpoint to retrieve the borrower's ID under the `borrower_id`
attribute; or you can GET /borrowers/?identifier={business_identifier} to directly get the borrower object.

## Request body

- APIOnboardingCreationRequest
  - `business` APIBusinessIdentifier
    - `identifier` string, required — Legal identifier of the business, such as its SIRET or SIREN in France. Must not contain spaces.
    - `identifier_type` 'belgium_registration_number' | 'bsn' | 'cif' | 'hr_nummer' | 'kvk' | 'name' | 'nif' | 'siren' | 'siret' | 'steuernummer' | 'vat_number', required — Type of legal business identifier of the business, such as the SIRET in France.
  - `email` string, email, nullable
  - `phone_number` string, nullable
  - `preferred_language` string, required — Preferred language of the borrower in format ISO 639-1 (examples: [fr, en, es, de, nl]).
  - `redirect_url` string, nullable — URL where to redirect borrower at end of onboarding after borrower signed the contract
  - `referral` string, nullable — Where the user comes from (.e.g Qonto, Google search, etc.).
  - `step` string, nullable — Current step of the onboarding process - usually oriented after the next user action
  - `traceability_payload` object, nullable

## Response `200`

OK

---

[API](https://skmtc.net/getdefacto/apis/api-reference.md) · [All operations](https://skmtc.net/getdefacto/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getdefacto/api-reference/revisions/0a9c1f8784f2/schema)