GetbeelDocs

Record a fee subject to withholding

A fee not received through SDI (paper invoice, notula of occasional work). withheld_amount is computed when left out. Live keys only (403 livemode_required). Free.

POST
/withholdings

A fee not received through SDI (paper invoice, notula of occasional work). withheld_amount is computed when left out. Live keys only (403 livemode_required). Free.

Authorization

apiKey
headerAuthorizationBearer <token>

API key: gb_test_… or gb_live_…

Header Parameters

Idempotency-Key?string

Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.

Lengthlength <= 255
Getbeel-Company?string

Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.

Formatuuid

Request Body

application/json
  1. body
recipient*

The percipiente: the professional or agent the fee is paid to

document?

The invoice, parcella or notula (receipt for occasional work) the fee is billed on

invoice_id?string

The received invoice (GET /received-invoices) it pays

Length1 <= length <= 100
type*string

RT01 natural person, RT02 company or other entity

Default"RT01"
Value in"RT01""RT02"
causale*string

CU causale (punto 1): A lavoro autonomo abituale, M occasionale, Q/R provvigioni agente mono/plurimandatario, … (CU 2026 instructions)

Default"A"
Value in"A""B""C""D""E""F""G""H""I""J""K""L""L1""M""M1""M2""N""O""O1""P""Q""R""S""T""U""V""V1""V2""W""X""Y""Z""ZO"
rate*unknown

Decimal string (or number)

gross_amount*unknown

Ammontare lordo (CU punto 4): the fee net of VAT, without the contributo integrativo of the professional funds

not_subject_amount?unknown

Sums not subject to the ritenuta (CU punto 7), e.g. expenses advanced for you, the 50% of provvigioni. Default 0

withheld_amount?unknown

Ritenuta withheld (CU punto 9). Omit to compute (gross − not subject) × rate

paid_on?|

The day the fee was paid: the ritenuta is made then (art. 25 DPR 600/1973) and paid with F24 1040 by the 16th of the next month

notes?string

Free-text note, up to 500 characters

Lengthlength <= 500

Response Body

OK

application/json
  1. response
id*string
object*string
source*string

sdi: read from the DatiRitenuta of an invoice received from SDI; manual: typed in

Value in"sdi""manual"
invoice_id*string|null
recipient*
document*
type*string
Value in"RT01""RT02"
causale*string
rate*string

Decimal amount as a string

Match^-?\d+\.\d{2}$
gross_amount*string

CU punto 4

Match^-?\d+\.\d{2}$
not_subject_amount*string

CU punto 7

Match^-?\d+\.\d{2}$
taxable_amount*string

CU punto 8

Match^-?\d+\.\d{2}$
withheld_amount*string

CU punto 9

Match^-?\d+\.\d{2}$
tax_code*string
paid_on*|null
period*|

Month the ritenuta was made (the month of paid_on)

status*string
Value in"unpaid""withheld""remitted"
due_date*|

F24 deadline: the 16th of the next month, moved off holidays

overdue*boolean
filing_id*|

The withholdings F24 that paid it (status remitted)

needs_review*boolean

Read from an invoice whose figures need a check (notes says why)

notes*string|null
created_at*string
Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Formatdate-time
updated_at*string
Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Formatdate-time
Example Request
curl -X POST 'https://www.getbeel.com/api/v1/withholdings' \  -H 'Content-Type: application/json' \  -d '{  "recipient": {    "name": "Mario Rossi"  },  "type": "RT01",  "causale": "A",  "rate": "20",  "gross_amount": "1000.00"}'
Example Response
{  "id": "wht_3f2a…",  "object": "withholding",  "source": "sdi",  "invoice_id": "string",  "recipient": {    "name": "string",    "fiscal_code": "string",    "vat": "string"  },  "document": {    "number": "string",    "date": "2026-10-29"  },  "type": "RT01",  "causale": "string",  "rate": "122.00",  "gross_amount": "122.00",  "not_subject_amount": "122.00",  "taxable_amount": "122.00",  "withheld_amount": "122.00",  "tax_code": "1040",  "paid_on": "2026-10-29",  "period": "string",  "status": "unpaid",  "due_date": "2026-10-29",  "overdue": true,  "filing_id": "string",  "needs_review": true,  "notes": "string",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}