Defacto Onboarding API
The Onboarding API from Defacto — 9 operation(s) for onboarding.
OpenAPI Specification
openapi: 3.0.0
info:
title: Defacto Accounting Onboarding API
version: v1.0.0
description: Defacto provides instant, embedded financing for SMBs across Europe. This REST API lets partners onboard borrowers, test eligibility and credit limits, upload business/bank data, create invoices, request and manage loans, handle repayments and recollection, issue and manage credit cards, bill fees, and subscribe to webhooks. Reconstructed by API Evangelist from the per-operation OpenAPI fragments published on Defacto's ReadMe developer portal (developers.getdefacto.com/llms.txt). operationId values are the provider's ReadMe reference slugs; summaries are the reference page titles.
contact:
email: contact@getdefacto.com
url: https://developers.getdefacto.com/
servers:
- url: https://api.getdefacto.com
description: Production
- url: https://api-sandbox.getdefacto.com
description: Sandbox
security:
- Bearer: []
tags:
- name: Onboarding
paths:
/borrower/{borrower_id}/repayment-methods:
get:
description: '
<div>
<h3>List available repayment methods for borrower.</h3>
</div>
'
parameters:
- in: path
name: borrower_id
required: true
schema:
type: string
responses:
'200':
description: ''
content:
'*/*':
schema:
$ref: '#/components/schemas/TypedApiPage13'
security:
- Bearer: []
tags:
- Onboarding
operationId: get_borrower-borrower-id-repayment-methods
summary: /borrower/{borrower_id}/repayment-methods
post:
description: '
<div>
<h3>Add and/or choose the repayment method for borrower.</h3>
<p>If payment method is "DIRECT_DEBIT" then the `account` parameter must not be null.</p>
<p>
If `is_default_repayment_method` is true, then the repayment method becomes the borrower''s default
repayment method so that upcmoing loan requests will use this payment method and account as a default.
<br/>
<br/>
<i>
Please note: that the account defined in the `loan_to` attribute of created loans is left
unchanged. If you want to change the destination account of a loan, you must cancel it and
request a new loan.
</i>
</p>
<p>
If `apply_to_all_active_loans` is true, then the repayment method is used for upcoming payments of
all loans that are in TO_REPAY or TO_REPAY_FEES statuses.
</p>
</div>
'
parameters:
- in: path
name: borrower_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ApiPostRepaymentMethod'
responses:
'200':
description: ''
content:
'*/*':
schema:
$ref: '#/components/schemas/APIRepaymentMethodDetails'
security:
- Bearer: []
tags:
- Onboarding
operationId: post_borrower-borrower-id-repayment-methods
summary: /borrower/{borrower_id}/repayment-methods
/borrower/{borrower_id}:
get:
description: Retrieve the full profile of a borrower by ID. Returns the borrower's status, business information, accounts, compliance checks, and next actions required.
parameters:
- in: path
name: borrower_id
required: true
schema:
type: string
responses:
'200':
description: ''
content:
'*/*':
schema:
$ref: '#/components/schemas/APIBorrower'
security:
- Bearer: []
tags:
- Onboarding
operationId: get_borrower-borrower-id
summary: /borrower/{borrower_id}
/borrowers:
get:
description: List all borrowers enrolled on Defacto for your account. Borrowers are companies that have been registered and can request loans through the Defacto platform. Returns a paginated list with their status, business info, accounts, and compliance data.
parameters:
- description: UUID(s) of the borrower(s) in Defacto API.
in: query
name: borrower_id
required: false
explode: true
schema:
type: array
items:
format: uuid
type: string
- description: Legal identifier of the business, such as its SIREN in France.
in: query
name: borrower_identifier
required: false
x-nullable: true
schema:
type: string
default: null
- description: Pagination cursor from the previous response's next_page field. Omit to get the first page.
in: query
name: cursor
required: false
x-nullable: true
schema:
type: string
default: null
- description: Filter borrowers who signed their contract on or after this datetime.
in: query
name: from_signed_at
required: false
x-nullable: true
schema:
type: string
format: date-time
default: null
- description: Maximum number of items to return per page.
in: query
name: page_size
required: false
schema:
type: integer
default: 100
- description: Filter borrowers who signed their contract on or before this datetime.
in: query
name: to_signed_at
required: false
x-nullable: true
schema:
type: string
format: date-time
default: null
responses:
'200':
description: ''
content:
'*/*':
schema:
$ref: '#/components/schemas/TypedApiPage12'
security:
- Bearer: []
tags:
- Onboarding
operationId: get_borrowers
summary: /borrowers
post:
description: "\n<div>\n<h3>Enroll a new borrower on Defacto.</h3>\n<p>\nThis API will create a borrower and a credit line for this borrower. More information\nin the <b>behavior</b> section below.\n</p>\n<p>\n<strong>Timeout:</strong> 30 seconds (status code will be 504 in such a case)\n</p>\n<br/>\n<h4>Required data</h4>\n<p>\nBorrower must be a commercial company -> eg. in France needs to be registered at an RCS.\n</p>\n<p>\n<b>If the borrower repays by direct debit, the following information are mandatory:</b>\n</p>\n<ul>\n<li> the director’s personal information: Name, birth date, nationality, email address and country of\nresidence of the managing director</li>\n<li>The IBAN of the borrower (please make sure that the borrower is aware\nthat direct debit is used as the repayment method).</li>\n</ul>\n<p>\nWe strongly recommend that you fill up all the information when you can, even on the sandbox.\nFor French borrowers, we manage to pull most of the director information automatically,\nhowever for other countries, this might not be the case.\nFor the borrowers that Defacto is not able to fetch the mandatory data, you need to provide them\nto ensure borrower creation. Otherwise the API will return a 400 error and list the values that it could\nnot obtain.\n</p>\n<h4>Behavior</h4>\n<p>\nThis API endpoint creates a borrower in our system,\nconfigures our system to get the repayment of the loan,\nevaluates the maximum amount of money we can lend to this company and creates a credit line for this\nborrower.\nAfter the credit line is created for this borrower, you can get it with\n<code>GET /credit-lines?borrower=<THE_COMPANY_NUMBER_OF_THE_BORROWER></code>. <br/>\n<b>Synchronous and asynchronous behaviors are offered.</b> </br>\n</p>\n<p>Synchronous behavior:</br></p>\n<ul>\n<li>Set <code>'wait_for_ready': true</code> to activate it</li>\n<li>\n<b>You can <code>GET /credit-lines?borrower=<THE_COMPANY_NUMBER_OF_THE_BORROWER></code>\nand request a loan right after you received the answer from this API endpoint</b>\n</li>\n<li>Response takes from 4 to 8 seconds</li>\n<li>\nThe API answers after the solvency of the company is evaluated and the credit line is created,\nor returns an error.\n</li>\n</ul>\n<br/>\n<p>Asynchronous behavior (default one):</p>\n<ul>\n<li>Set <code>'wait_for_ready': false</code> to activate it</li>\n</li>\n<li>\nOur system will evaluate the solvency of the company and create its credit line after answering\nthe API call.\n<li>\nSo, a loan cannot be requested right after this endpoint answers. You must wait for the creation\nof the credit line. To discover it, you can either subscribe to the CreditLine.CREATED webhook or\nregularly fetch <code>GET /credit-lines?borrower=<THE_COMPANY_NUMBER_OF_THE_BORROWER></code>.\n</li>\n <li>Response takes between 0.3 and 1.5 second.</li>\n</ul>\n<blockquote class=\"callout callout_warn\" theme=\"\U0001F6A7\">\n<h3 class=\"callout-heading\">\n<span class=\"callout-icon\">\U0001F6A7</span>\n<p>Careful if you subscribe to the CreditLine.CREATED webhook!</p>\n</h3>\n<p>\nIf you subscribe to the webhook, please note that there is an inconsistency in the API at the\nmoment. The webhook sends a <code>borrower_id</code> that does not correspond to the borrower id that\nyou received with this endpoint (it's rather a business_id in our DB, that you cannot fetch).\n</p>\n<p>\nSo at the moment we recommend you to\n<code>GET /credit-lines?borrower=<THE_COMPANY_NUMBER_OF_THE_BORROWER></code> for all borrowers waiting\nfor a credit line when you receive the webhook event.\n</p>\n</blockquote>\n</div>\n"
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/APIPostBorrower'
responses:
'201':
description: ''
content:
'*/*':
schema:
$ref: '#/components/schemas/APIBorrower'
security:
- Bearer: []
tags:
- Onboarding
operationId: post_borrowers
summary: /borrowers
/business/public-data:
get:
description: Search for borrower business information from various sources. This endpoint lets you find the right business identifier to use when onboarding a borrower or counterparty.
parameters:
- in: query
name: city
required: false
x-nullable: true
schema:
type: string
default: null
- in: query
name: country
required: false
x-nullable: true
schema:
type: string
default: null
- in: query
name: identifier
required: true
schema:
type: string
- in: query
name: identifier_type
required: false
schema:
type: string
enum:
- hr_nummer
default: hr_nummer
- in: query
name: name
required: false
x-nullable: true
schema:
type: string
default: null
- in: query
name: postal_code
required: false
x-nullable: true
schema:
type: string
default: null
- in: query
name: street
required: false
x-nullable: true
schema:
type: string
default: null
responses:
'200':
description: ''
content:
'*/*':
schema:
items:
$ref: '#/components/schemas/ApiBusinessDataSearchOutput'
type: array
security:
- Bearer: []
tags:
- Onboarding
operationId: get_business-public-data
summary: /business/public-data
/onboarding/{onboarding_id}:
get:
description: '
## [Partners] Follow the onboarding of a 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.
When your borrower is on our web app, sharing his financial data, you might want to keep track of his onboarding.
This endpoints will let you get access to the onboarding status and details.
You''ll be able to know if the borrower has shared his financial data and is ready to request loans;
how much does defacto proposes to lend him; and more.
'
parameters:
- in: path
name: onboarding_id
required: true
schema:
type: string
responses:
'200':
description: ''
content:
'*/*':
schema:
$ref: '#/components/schemas/APIOnboarding'
security:
- Bearer: []
tags:
- Onboarding
operationId: get_onboarding-onboarding-id
summary: /onboarding/{onboarding_id}
/borrower/{borrower_id}/deactivate:
post:
parameters:
- in: path
name: borrower_id
required: true
schema:
type: string
responses:
'204':
description: ''
content:
'*/*':
schema: {}
security:
- Bearer: []
tags:
- Onboarding
operationId: post_borrower-borrower-id-deactivate
summary: /borrower/{borrower_id}/deactivate
/borrower/{borrower_id}/owner:
post:
description: Create a borrower owner with identity documents
parameters:
- in: path
name: borrower_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/APICreateOwner'
responses:
'201':
description: ''
content:
'*/*':
schema:
$ref: '#/components/schemas/APIOwnerCreatedResponse'
security:
- Bearer: []
tags:
- Onboarding
operationId: post_borrower-borrower-id-owner
summary: /borrower/{borrower_id}/owner
/borrower/{borrower_id}/sign:
post:
description: Register the date a new borrower accepted our T&Cs
parameters:
- in: path
name: borrower_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SignedInput'
responses:
'200':
description: ''
content:
'*/*':
schema:
$ref: '#/components/schemas/APIBorrower'
security:
- Bearer: []
tags:
- Onboarding
operationId: post_borrower-borrower-id-sign
summary: /borrower/{borrower_id}/sign
/onboardings:
post:
description: "\n## [Partners] Start onboarding a new business\n\nIf 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.\n\n**Timeout after**: 30 seconds (status code will be 504 in such a case)\n\nIn order to request loans you will need to have borrowers. In order to test borrower's eligibility, we'll need\nto have access to borrower business' financial data.\n\nThis can be achieved in two ways:\nEither you have this piece of information and you may use the\n[sharing business data](https://developers.getdefacto.com/reference/post_business-data-account-transactions)\nAPI documentation to do so, or you might want to rely on defacto's onboarding process to get this information.\n\nIn the later, you will need to create an onboarding for the business you want to request loans for.\n\n### Behavior\nWhen you send this API request providing business information, your referral and callback url:\nThe system will start an onboarding for you and you will get its id in the response.\n\nThen you must redirect the borrower to the onboarding tunnel so that he can select his financial\ntools and share as much data as he wants to max-out his eligible amount:\n\n- **In the normal case**, redirect him to\n `https://app.getdefacto.com/onboarding/continue/{onboarding_id}`.\n- **When the response contains a `secure_resume_link`**, redirect him to that link *instead* of the\n bare continue URL above. This happens when the business already has a bank-connected onboarding:\n to avoid exposing another party's financial data, that tunnel is gated and can only be reopened by\n a link carrying a short-lived secure token. The `secure_resume_link` is exactly that\n pre-authenticated continue URL. It is valid for **2 hours** — if it expires, POST /onboarding again\n to obtain a fresh one.\n\nOnce borrower has accepted defacto's T&Cs and created his account, he'll be redirected back to the redirect_url\nyou provided and if you subscribed to `CREDIT_LINE.Created` webhook you will receive it shortly.\nRead [webhook](https://developers.getdefacto.com/reference/webhooks-at-defacto) for details.\n\n### Frequently Asked Questions\n\n**How do I get onboarding results?**\nYou can use the GET /onboarding/{onboarding_id} endpoint to retrieve the onboarding results.\n\n**What should I do if the status of the onboarding is expired?**\nOnboardings last for 168 hours;\nafter what you'll have to repeat the POST /onboarding request you just made.\n\n**How do I get the borrower's ID once onboarding is `COMPLETED`?**\nYou can use the GET /onboarding/{onboarding_id} endpoint to retrieve the borrower's ID under the `borrower_id`\nattribute; or you can GET /borrowers/?identifier={business_identifier} to directly get the borrower object.\n"
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/APIOnboardingCreationRequest'
responses:
'200':
description: ''
content:
'*/*':
schema:
$ref: '#/components/schemas/APIOnboarding'
security:
- Bearer: []
tags:
- Onboarding
operationId: post_onboardings
summary: /onboardings
components:
schemas:
PublicApiAccountNumber:
properties:
account_number:
description: The account identifier. Only IBANs are supported at the moment.
type: string
account_number_type:
default: iban
description: The type of account number (e.g. IBAN).
enum:
- iban
type: string
bank_identifier:
default: null
description: The identifier of the bank.
type: string
nullable: true
bank_identifier_type:
default: bic
description: The type of bank identifier (e.g. BIC).
enum:
- bic
type: string
required:
- account_number
type: object
APILightAccount:
properties:
account_name:
default: null
description: A name given to this account. Any name can be given.
type: string
nullable: true
account_number:
description: The account identifier. Only IBANs are supported at the moment.
type: string
account_number_type:
description: The type of account number (e.g. IBAN).
enum:
- account_number
- iban
- internal_id
type: string
bank_identifier:
description: The identifier of the bank.
type: string
bank_identifier_type:
description: The type of bank identifier (e.g. BIC).
enum:
- bic
- name
- routing_number
- undefined
type: string
required:
- account_number
- account_number_type
- bank_identifier
- bank_identifier_type
type: object
APIOnboardingBusiness:
properties:
defacto_segment:
default: null
enum:
- CAT1
- CAT2
- CAT3
- CAT4
- null
type: string
nullable: true
identifier:
type: string
identifier_type:
enum:
- belgium_registration_number
- bsn
- cif
- hr_nummer
- kvk
- name
- nif
- siren
- siret
- steuernummer
- vat_number
type: string
name:
type: string
required:
- identifier
- identifier_type
- name
type: object
UserInput:
properties:
desired_amount_euros:
default: null
type: integer
nullable: true
desired_timeline:
default: null
type: string
nullable: true
frequency:
default: null
enum:
- permanent
- temporary
- null
type: string
nullable: true
immediate_need:
default: null
type: string
nullable: true
integrations_need:
default: null
items:
type: string
type: array
nullable: true
no_enrollment_category:
default: null
type: string
nullable: true
no_enrollment_detail:
default: null
type: string
nullable: true
reason_for_not_connecting_bank_account:
allOf:
- $ref: '#/components/schemas/ReasonForNotConnectingBankAccount'
default: null
nullable: true
user_need:
default: null
type: string
nullable: true
type: object
APIAddress:
properties:
address_line_1:
default: null
type: string
nullable: true
address_line_2:
default: null
type: string
nullable: true
city:
default: null
type: string
nullable: true
country:
default: null
type: string
nullable: true
postal_code:
default: null
maxLength: 10
type: string
nullable: true
state:
default: null
type: string
nullable: true
type: object
BorrowerComplianceChecks:
properties:
status:
enum:
- APPROVED
- PENDING_USER_ACTION
- REJECTED
- REVIEWING
- UNKNOWN
type: string
required:
- status
type: object
APIDirector:
properties:
address:
allOf:
- $ref: '#/components/schemas/APIAddress'
default: null
description: Address of the person.
nullable: true
birth_date:
default: null
description: Birth date of the person. (YYYY-MM-DD)
format: date
type: string
nullable: true
birth_place:
allOf:
- $ref: '#/components/schemas/BirthPlace'
default: null
description: Birth place of the person.
nullable: true
business_email:
default: null
format: email
type: string
nullable: true
business_phone_number:
default: null
description: PhoneNumber
type: string
nullable: true
entity_type:
default: people
enum:
- account
- account_detail_verification
- bill
- borrower
- borrower_financial_product
- business
- business_exposure
- business_financial_product
- contract
- counterparty
- country
- credit_card
- credit_line
- data_request
- deposit
- due_interest
- eligibility_request
- enrollment
- entity_eligibility
- financial_product
- flag
- installment
- invoice
- loan
- loan_log
- mandate
- max_exposure_deployment
- onboarding
- onboarding_financial_product
- payment
- people
- rac
- raw_data
- recollection_document
- revenue_share
- sandbox_invoice
- underwriting_check
type: string
first_name:
default: null
description: The first name of the person.
type: string
nullable: true
id:
default: null
nullable: true
identifier:
default: null
description: Legal identifier of the business, such as its SIRET or SIREN in France. Must not contain spaces.
type: string
nullable: true
identifier_type:
default: null
description: Type of legal business identifier of the business, such as the SIRET in France.
enum:
- belgium_registration_number
- bsn
- cif
- hr_nummer
- kvk
- name
- nif
- siren
- siret
- steuernummer
- vat_number
- null
type: string
nullable: true
last_name:
default: null
description: The first name of the person.
type: string
nullable: true
legal_name:
default: null
description: Legal name of the business.
type: string
nullable: true
nationality:
default: null
description: Nationality of the person. Must be a ISO 3166 alpha-3 country code (e.g. FRA).
type: string
nullable: true
role:
default: DIRECTOR
enum:
- DIRECTOR
- NON_DIRECTOR
type: string
siege_address:
allOf:
- $ref: '#/components/schemas/APIAddress'
default: null
description: Address of the business head quarters.
nullable: true
title:
default: null
description: Title of the person (e.g. M., Dr., etc.)
type: string
nullable: true
type: object
APIPostBorrower:
properties:
account_number:
default: null
description: The account identifier. Only IBANs are supported at the moment.
type: string
nullable: true
address:
allOf:
- $ref: '#/components/schemas/BusinessAddress'
default: null
nullable: true
directors:
default: null
items:
$ref: '#/components/schemas/APICreateDirector'
minItems: 1
type: array
nullable: true
identifier:
description: Legal identifier of the business, such as its SIRET or SIREN in France. Must not contain spaces.
type: string
identifier_type:
default: null
description: Type of legal business identifier of the business, such as the SIRET in France.
enum:
- belgium_registration_number
- bsn
- cif
- hr_nummer
- kvk
- nif
- siren
- siret
- steuernummer
- vat_number
- null
type: string
nullable: true
legal_form:
default: null
description: Legal form of the business.
type: string
nullable: true
metadata:
additionalProperties:
nullable: true
default: null
description: This object is yours, it enables you to add custom data.
type: object
nullable: true
name:
default: null
description: Legal name of the business.
type: string
nullable: true
owner:
allOf:
- $ref: '#/components/schemas/APICreateOwner'
default: null
description: The person requesting subscribing to Defacto on behalf of the borrowers. Must be added as a director too
nullable: true
preferred_language:
default: null
description: 'Preferred language of the borrower in format ISO 639-1 (examples: [fr, en, es, de, nl]).'
type: string
nullable: true
signed_at:
default: null
description: datetime of the borrower's signature. Usually time the borrower clicked on our T&Cs checkbox
format: date-time
type: string
nullable: true
vat_number:
default: null
description: VatNumber
type: string
nullable: true
wait_for_ready:
default: false
description: Wait for the borrower to be ready to request a first loan.Many actions have to run in the background (KYC, scoring, contract generation and so on).We recommend you to subscribe to the CreditLine.CREATED webhook in order to be notified in real time when the credit line is available.
type: boolean
required:
- identifier
type: object
TypedApiPage12:
properties:
count:
type: integer
data:
items:
$ref: '#/components/schemas/APIBorrower'
type: array
next_page:
default: null
type: string
nullable: true
page_size:
type: integer
previous_page:
default: null
type: string
nullable: true
total:
default: null
type: integer
nullable: true
required:
- count
- page_size
type: object
CreateAddress:
properties:
address_line_1:
default: null
type: string
nullable: true
address_line_2:
default: null
type: string
nullable: true
city:
default: null
type: string
nullable: true
country:
default: null
type: string
nullable: true
postal_code:
default: null
maxLength: 10
type: string
nullable: true
state:
default: null
type: string
nullable: true
type: object
APIEnrollment:
properties:
agent_feedback:
default: null
type: string
nullable: true
enrollment_campaign:
type: string
enrollment_name:
type: string
entity_id:
format: uuid
type: string
entity_type:
enum:
- BORROWER
- ONBOARDING
type: string
id:
format: uuid
type: string
recommendations:
default: null
items:
nullable: true
type: array
nullable: true
status:
type: string
submitted_at:
default: null
format: date-time
type: string
nullable: true
required:
- enrollment_campaign
- enrollment_name
- entity_id
- entity_type
- id
- status
type: object
APIBorrower:
properties:
accounts:
description: Bank accounts of the business.
items:
$ref: '#/components/schemas/APILightAccount'
type: array
active_enrollments:
items:
$ref: '#/components/schemas/APIEnrollment'
type: array
address:
allOf:
- $ref: '#/components/schemas/Address'
default: null
nullable: true
can_reonboard:
default: false
type: boolean
nullable: true
compliance_checks:
allOf:
- $ref: '#/components/schemas/BorrowerComplianceChecks'
default: null
description: '[deprecated] Compliance checks state of the borrower. Tells about KYB and KYC procedure progression.'
nullable: true
contract_id:
default: null
format: uuid
type: string
nullable: true
contract_s3_url:
default: null
description: Pre-signed url to download the contract
type: string
nullable: true
directors:
default: null
description: Directors of the business.
items:
$ref: '#/components/schemas/APIDirector'
minItems: 1
type:
# --- truncated at 32 KB (70 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/defacto/refs/heads/main/openapi/defacto-onboarding-api-openapi.yml