> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tilta.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Request a credit facility
> Trigger Tilta automated underwriting to request a credit facility for a buyer. Approval is based on credit bureau data and delivered via webhook event.
A credit facility is the credit line that enables a buyer to pay on deferred terms through your platform. Requesting one triggers Tilta's automated underwriting engine, which evaluates the buyer's creditworthiness using third-party credit bureau data alongside the business information stored in the buyer record. A buyer can hold only one active credit facility at a time. The underwriting result is returned synchronously where possible; a `202` response means the decision is still pending and arrives via webhook.
## Webhook events
When underwriting cannot complete synchronously, Tilta delivers the result via webhook. Subscribe to the following events in your webhook configuration:
| Event | Description |
| ----------------------------- | ---------------------------------------------------------------- |
| `FACILITY.CREATION.ACCEPTED` | The credit facility was approved and is ready to use. |
| `FACILITY.CREATION.REJECTED` | The credit facility request was rejected. |
| `FACILITY.CREATION.IN_REVIEW` | Underwriting requires additional review and is not yet complete. |
To request a credit facility, the buyer must have completed the Tilta onboarding flow. If they have not, create a [buyer
Onboarding Session](/api-reference/buyers/buyer-onboarding-session) first.
Each buyer can hold only one active credit facility at a time. Requesting a new facility for a buyer who already has one
returns a `409 Conflict`. To raise an existing limit, use [Request Increase](/api-reference/facilities/request-increase)
instead.
## OpenAPI
````yaml POST /v1/buyers/{external_id}/facility
openapi: 3.0.0
info:
version: 0.0.1
title: Tilta API
description: Tilta API documentation
servers:
- url: https://api.tilta.io
description: Tilta Production API
- url: https://api.tilta-sandbox.io
description: Tilta Sandbox API
security: []
paths:
/v1/buyers/{external_id}/facility:
post:
tags:
- Credit Facilities
summary: Create a credit facility
description: |-
Creates a credit facility for a buyer.
A credit facility can only be requested for eligible buyers.
A buyer can have only one active credit facility.
parameters:
- schema:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
description: Unique identifier of a buyer.
required: true
description: Unique identifier of a buyer.
name: external_id
in: path
- schema:
type: string
enum:
- 'true'
- 'false'
description: Indicates if the operation should be performed asynchronously.
required: false
name: async_execution
in: header
requestBody:
content:
application/json:
schema:
type: object
nullable: true
properties:
requested_amount:
type: integer
nullable: true
minimum: 1
description: >-
Requested amount. As minimum currency unit (e.g
cents/pence).
is_existing_buyer:
type: boolean
nullable: true
description: >-
Indicates that the platform has at least two closed orders
with this buyer.
requested_currency:
type: string
enum:
- EUR
- GBP
- USD
- CHF
- PLN
- CZK
- RON
- BGN
- DKK
- HUF
- SEK
- NOK
- JPY
- AUD
- NZD
- CAD
responses:
'201':
description: ''
content:
application/json:
schema:
type: object
properties:
buyer_external_id:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
description: Unique identifier for buyer.
example: 5f6374a46a5e8e0104aa5cd4
pending_orders_amount:
type: integer
description: >-
Blocked by pending deferred orders portion of the Credit
Limit. As minimum currency unit (e.g cents/pence).
example: 2500
risk_band:
type: string
enum:
- REJECT
- A1
- A2
- B1
- B2
- C1
- C2
- D1
- D2
created_at:
type: number
description: >-
Timestamp indicating when the facility was created (unix
time in seconds).
example: 1582896122
updated_at:
type: number
description: >-
Timestamp indicating the last time the facility was
updated (unix time in seconds).
example: 1582896122
pending_actions:
type: array
nullable: true
items:
type: object
properties:
type:
type: string
enum:
- CREATION
- RENEWAL
- INCREASE
description: Type of the pending action.
created_at:
type: number
description: >-
Timestamp indicating when the pending action was
created (unix time in seconds).
example: 1582896122
required:
- type
- created_at
description: List of pending actions for the facility.
status:
type: string
enum:
- ACTIVE
- PENDING
- FROZEN
- EXPIRED
description: Status of the Active facility
example: ACTIVE
reviewed_at:
type: number
nullable: true
description: Review Date of the Active facility
currency:
type: string
enum:
- EUR
- GBP
- USD
- CHF
- PLN
- CZK
- RON
- BGN
- DKK
- HUF
- SEK
- NOK
- JPY
- AUD
- NZD
- CAD
description: ISO 4217 three-letter currency code.
total_amount:
type: integer
description: >-
Total credit limit available to the Buyer. As minimum
currency unit (e.g cents/pence).
example: 10000
available_amount:
type: integer
description: >-
Available portion of the Credit Limit. As minimum currency
unit (e.g cents/pence).
example: 5200
used_amount:
type: integer
description: >-
Credit Limit portion currently in use (not repaid). As
minimum currency unit (e.g cents/pence).
example: 4800
required:
- buyer_external_id
- pending_orders_amount
- risk_band
- created_at
- updated_at
- pending_actions
- status
- reviewed_at
- currency
- total_amount
- available_amount
- used_amount
additionalProperties: false
description: A credit facility has been successfully created for a buyer.
'202':
description: ''
content:
application/json:
schema:
type: object
properties:
buyer_external_id:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
description: Unique identifier for buyer.
example: 5f6374a46a5e8e0104aa5cd4
status:
type: string
enum:
- PENDING
description: Status of the Pending facility
required:
- buyer_external_id
- status
description: The creation of a credit facility is pending.
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/badRequestSchema'
'401':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unauthorizedRequestSchema'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/buyerNotFoundSchema'
'409':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/createFacilityConflictSchema'
'424':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/createFacilityFailedDependencySchema'
security:
- bearerAuth: []
components:
schemas:
badRequestSchema:
type: object
properties:
code:
type: string
description: Error code
example: BAD_REQUEST
error:
type: string
description: Error message for debugging purposes
example: Request validation failed. 1 issue found.
issues:
type: array
items:
type: object
properties:
code:
type: string
description: Issue code
example: INVALID_TYPE
path:
type: string
description: Issue path starting with body, params, querystring, or headers
example: body.registered_at
message:
type: string
description: Issue message for debugging purposes
example: Invalid type
required:
- code
- path
- message
description: List of issues
example:
- code: INVALID_TYPE
path: body.registered_at
message: Invalid type
required:
- code
- error
- issues
description: Bad Request, see error message for details.
example:
code: BAD_REQUEST
error: Request validation failed. 1 issue found.
issues:
- code: INVALID_TYPE
path: body.registered_at
message: Invalid type
unauthorizedRequestSchema:
type: object
properties:
error:
type: string
description: Error details.
example: Unauthorized
code:
type: string
description: Error code.
example: UNAUTHORIZED
required:
- error
- code
description: Unauthorized Request.
example:
error: Unauthorized
code: UNAUTHORIZED
buyerNotFoundSchema:
type: object
properties:
error:
type: string
description: Error details.
example: No Entity found
code:
type: string
description: Error code.
example: NOT_FOUND
required:
- error
- code
description: Buyer not found
example:
error: No Entity found
code: NOT_FOUND
createFacilityConflictSchema:
type: object
properties:
error:
type: string
description: Error details.
example: Buyer already has an active Facility
code:
type: string
description: Error code.
example: CONFLICT
required:
- error
- code
description: Buyer already has an active Facility
example:
error: Buyer already has an active Facility
code: CONFLICT
createFacilityFailedDependencySchema:
type: object
properties:
error:
type: string
description: Error details.
example: Facility could not be created
code:
type: string
description: Error code.
example: RISK_DECISION_ERROR
required:
- error
- code
description: Could not create facility due to buyer risk
example:
error: Facility could not be created
code: RISK_DECISION_ERROR
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Your Tilta API key, sent as `Bearer `.
````