> ## 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 service
> Activate financing, insurance, or collection on a captured invoice. Requesting a Service is what triggers the funding flow.
Requesting a Service is what triggers the funding flow: once the Service is active on an invoice, Tilta finances the receivable and initiates payout to the merchant.
Confirm the invoice satisfies every prerequisite with [Service
Requirements](/api-reference/utilities/invoice-service-requirements) before requesting the Service.
Listen for the Service status webhook event to learn when a Service becomes active and funding is in progress, rather than
polling.
## OpenAPI
````yaml POST /v1/services
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/services:
post:
tags:
- Invoice Services
summary: Request a service
description: |-
Requests a service for an invoice.
The request will return a success after the service has been created.
requestBody:
content:
application/json:
schema:
type: object
properties:
external_id:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
description: Unique identifier of the invoice service.
invoice_external_id:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
description: Unique identifier of the invoice.
service_type:
type: string
enum:
- FINANCING
- INSURANCE
- COLLECTION
terms_accepted_at:
type: number
paid_out_at:
type: number
description: >-
Timestamp when the payout should be made (unix time in
seconds).
required:
- external_id
- invoice_external_id
- service_type
- terms_accepted_at
responses:
'201':
description: ''
content:
application/json:
schema:
type: object
properties:
external_id:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
invoice_external_id:
type: string
maxLength: 100
pattern: ^[a-zA-Z0-9-_]+$
service_type:
type: string
enum:
- FINANCING
- INSURANCE
- COLLECTION
status:
type: string
enum:
- IN_REVIEW
- ACCEPTED
- REJECTED
- CANCELLED
- PAID_OUT
- SETTLED
- DEFAULTED
- CLAIM_NOTIFIED
- CLAIM_IN_ASSESSMENT
- CLAIM_PAID
- CLAIM_DENIED
- COVER_EXPIRED
- EARLY_COLLECTION
- LATE_COLLECTION
- COLLECTED
- UNCOLLECTIBLE
created_at:
type: number
updated_at:
type: number
requirements:
type: array
items:
type: object
properties:
code:
type: string
enum:
- INVOICE_INELIGIBLE
- FACILITY_MISSING
- MERCHANT_NOT_ENROLLED
- FACILITY_CURRENCY_CONFLICT
- FACILITY_EXCEEDED_AVAILABLE_AMOUNT
- FACILITY_EXPIRED
- INVOICE_DUE_DATE_BIGGER_FACILITY_EXP_DATE
- FROZEN_FACILITY
- NO_ACTIVE_MANDATE
- INVOICE_CURRENCY_NOT_SUPPORTED
- INVOICE_PAYMENT_TERM_EXCEEDED
- INVOICE_ISSUE_DATE_TOO_OLD
- NO_INVOICE_FILE_FOUND
- BUYER_CONTACT_REQUIRED
- INVOICE_FILE_DATA_MISMATCH
description:
type: string
required:
- code
- description
advance:
type: object
properties:
value:
type: integer
description: >-
Amount actually transferred to the merchant after fee
deduction, in the smallest currency unit (e.g. cents).
required:
- value
description: >-
Advance amount paid out to the merchant for this invoice.
Each invoice receives its own SEPA transfer (or N
transfers when split above 100K), with the invoice number
leading the remittance information for `startsWith`
reconciliation.
fee:
type: object
properties:
gross:
type: integer
net:
type: integer
tax:
type: integer
required:
- gross
- net
- tax
description: >-
Fees applied to this invoice, in the smallest currency
unit. `gross = net + tax`.
required:
- external_id
- invoice_external_id
- service_type
- status
- created_at
- updated_at
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/badRequestSchema'
'401':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unauthorizedRequestSchema'
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
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Your Tilta API key, sent as `Bearer `.
````