Create a partner

POST

/api/v1/partners

curl --request POST \
  --url https://example.com/api/v1/partners \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "workspace_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "billing_mode": "self_billing", "self_billing_data": { "legal_name": "example", "address": { "street": "example", "city": "example", "region": "example", "postal_code": "example", "country": "example" }, "vat_number": "example", "payment_terms_days": 1, "bank_account": { "beneficiary_name": "example", "iban": "example", "bic": "example" }, "tax_config": { "treatment": "standard", "label": "example", "rate_bps": 1 } } }'

Authorizations

• bearerAuth

Request Body ^required

Media type application/json

object

name

required

Name of the partner to create

string

workspace_id

required

ID of the workspace this partner belongs to

string format: uuid

billing_mode

Billing mode for the partner. Omit to use the default (partner_billing).

string

nullable

Allowed values: self_billing partner_billing

self_billing_data

Required when billing_mode is self_billing. Contains all data needed to generate invoices on behalf of the partner.

object

legal_name

required

Legal entity name of the partner (used on invoices)

string

address

required

Registered business address shown on invoices

object

street

required

Street address including house number

string

city

required

City

string

region

required

State, province, or region

string

postal_code

required

Postal or ZIP code

string

country

required

ISO 3166-1 alpha-2 country code

string

vat_number

required

VAT or tax registration number (e.g. “FR12345678901”)

string

payment_terms_days

required

Number of days after invoice issuance until payment is due

integer

bank_account

required

Bank account to which the settlement amount should be transferred

object

beneficiary_name

required

Name of the bank account beneficiary

string

iban

required

International Bank Account Number

string

bic

required

Bank Identifier Code (SWIFT/BIC)

string

tax_config

required

Tax treatment applied to this partner’s invoices

object

treatment

required

Tax treatment applied to commissions paid to this partner

string

Allowed values: standard reverse_charge exempt

label

required

Tax label printed on invoices (e.g. “VAT”, “TVA”, “MwSt”)

string

rate_bps

Tax rate in basis points (e.g. 2000 = 20%). Required when treatment is standard.

integer

nullable

Responses

201

Partner created successfully

Media type application/json

object

id

required

ID of the newly created partner

string format: uuid

Example ^generated

{
  "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
}

400

Bad request

Media type application/json

object

error_code

required

string

Allowed values: UNAUTHORIZED NOT_FOUND INTERNAL_ERROR BAD_REQUEST FORBIDDEN CONFLICT

message

required

string

Example

{
  "error_code": "UNAUTHORIZED",
  "message": "Authentication credentials were not provided or are invalid."
}

401

Unauthorized

Media type application/json

object

error_code

required

string

Allowed values: UNAUTHORIZED NOT_FOUND INTERNAL_ERROR BAD_REQUEST FORBIDDEN CONFLICT

message

required

string

Example

{
  "error_code": "UNAUTHORIZED",
  "message": "Authentication credentials were not provided or are invalid."
}

500

Internal server error

Media type application/json

object

error_code

required

string

Allowed values: UNAUTHORIZED NOT_FOUND INTERNAL_ERROR BAD_REQUEST FORBIDDEN CONFLICT

message

required

string

Example

{
  "error_code": "UNAUTHORIZED",
  "message": "Authentication credentials were not provided or are invalid."
}