Collect seller data

Step 1 of Digital Platform Reporting. Before Taxbit can report a seller's income, it needs the seller's details: legal name, address, tax residences and TINs, date and place of birth, VAT number, business registration, and the financial account associated with them. Each seller is an account owner, and the details live on that account owner.

There are two routes:

• The React SDK, when you want sellers to fill in a Digital Platform Seller (DPS) questionnaire inside your app.
• The API, when you already hold the seller's details and want to send them from your backend.

Taxbit also accepts seller data as CSV files; ask your implementation manager for the template.

By the end of this page you have a seller's details in Taxbit and know how to check their DPS status.

Before you begin

• A bearer token. See Authenticate your tenant.
• The seller's account owner. See Create account owners and accounts.

Collect with the React SDK

Render the SDK's questionnaire with questionnaire="DPS". The seller answers it in your app, and the submission is stored as DPS tax documentation on their account owner. The Questionnaire integration guide covers installing the SDK, requesting the account owner token, and rendering the questionnaire.

Send seller data through the API

Update the seller's account owner with the details you hold. Send only the fields you are setting. Here the seller is an individual resident in Germany:

curl -X PATCH $BASE_URL/v1/account-owners/usr_2e9f4c7a \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lena Hoffmann",
    "birth_date": "1988-04-17",
    "birth_city": "Hamburg",
    "birth_country": "DE",
    "address": {
      "first_line": "Kastanienallee 41",
      "city": "Berlin",
      "postal_code": "10435",
      "country": "DE"
    },
    "tax_residencies": [
      { "country": "DE", "tin": "48036952129", "tin_type": "OTHER" }
    ],
    "vat_id": "298374651",
    "vat_country_code": "DE",
    "financial_account_id": "DE89370400440532013000",
    "financial_account_holder_name": "Lena Hoffmann"
  }'

A 200 returns the updated account owner in data. To send these fields when you create the seller, include them in POST /v1/account-owners instead.

For a seller that is a business, set account_owner_type to ENTITY when you create it, and add business_registration_number and business_registration_country_code.

A seller with no TIN for a country of residence still gets a tax_residencies entry for it, with tin_not_required set to true and a tin_not_required_reason of NOT_ISSUED, NOT_REQUIRED, or OTHER.

Country fields take a two-letter ISO 3166-1 alpha-2 code, such as DE, and aren't validated on this endpoint, so a country name is stored as sent; see Country fields.

Check the DPS status

Read the seller's tax documentation status:

curl $BASE_URL/v1/account-owners/usr_2e9f4c7a/tax-documentation-status \
  -H "Authorization: Bearer $TOKEN"

dps_questionnaire reports on the seller's DPS questionnaire:

• data_collection_status is COMPLETE or INCOMPLETE: whether the required information for the questionnaire has been collected.
• tax_documentation_status is VALID when the most recent DPS submission has passed validation checks, or INVALID when it has issues or missing information to correct before it can be used for reporting.
• issues lists what needs fixing, each with an issue_type and a status of OPEN, IN_REVIEW, or RESOLVED.
• needs_resubmission says whether to prompt the seller to submit a new DPS questionnaire.
• expiration_date is when the questionnaire expires, three years after submission.
• vat_status is the outcome of VAT validation (PENDING, VALID, INVALID, INSUFFICIENT_DATA, NOT_REQUIRED, or NON_EU), and vat_validation_date is when the VAT number was validated.

The response also carries a DAC7_interview object, which the API marks deprecated for SDK versions 1.0 and later.

GET /v1/account-owners/{id}/tax-documentation-data returns the submitted DPS data itself, under dps.

If the request fails

• 400. A field failed validation. The message names the field.
• 401. The bearer token is missing, invalid, or expired. Request a new one and retry.
• 404. No account owner has that id. Create it first, as Create account owners and accounts shows.
• 429. Too many requests. Slow down and retry.

The Errors page has every error shape, the rate limits, and which calls are safe to retry.

Parameters

Only the fields used above. The full schemas are in the Account Owners reference and the Tax Documentation Status reference.

Where to go next

Send income & payment transactions: step 2, each payment from a buyer to a seller.