Platform Businesses Guide

The Platform Business API lets you create and manage businesses on behalf of your platform's users. This is useful when onboarding new businesses programmatically — you create the business entity, attach members by email, and optionally auto-grant your platform access scopes.

Required scopes

business:create, business:read, business:update

How it works

When you create a business via the Platform API, the system:

1. Creates the business entity with the provided name and address
2. Looks up each member by email — if an Oncade account exists, they are attached immediately
3. For members without an account, a placeholder is created so they can claim it later
4. If grantScopes is provided, an automatic permission grant is created for your platform

Creating a business

curl -s -X POST \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Games LLC",
    "address": {
      "line1": "123 Main Street",
      "line2": "Suite 400",
      "city": "Austin",
      "state": "TX",
      "postalCode": "78701",
      "country": "US"
    },
    "members": [
      {
        "email": "owner@acmegames.com",
        "roles": ["ADMIN"],
        "isOwner": true
      },
      {
        "email": "finance@acmegames.com",
        "roles": ["VIEWER"]
      }
    ],
    "grantScopes": [
      "invoice:create",
      "invoice:read",
      "invoice:send",
      "distribution:create",
      "distribution:read"
    ]
  }' \
  https://<host>/api/v1/platform/business

Required fields

Member roles

Set isOwner: true on exactly one member to designate them as the business owner. The owner's payout wallet is used as a fallback when the business does not have a dedicated payout wallet configured.

Address format

The address fields use US-style naming conventions but work for any country or region. Map your local address components to the following fields:

International address example

curl -s -X POST \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tokyo Digital Co",
    "address": {
      "line1": "1-2-3 Shibuya",
      "city": "Tokyo",
      "state": "Tokyo",
      "postalCode": "150-0002",
      "country": "JP"
    },
    "members": [
      { "email": "admin@tokyodigital.co", "roles": ["ADMIN"], "isOwner": true }
    ]
  }' \
  https://<host>/api/v1/platform/business

Optional fields

Auto-granting platform access

When you include grantScopes in the create request, a permission grant is automatically created for your platform on the new business. This eliminates the need for a separate link session or invite flow.

The scopes you request must be a subset of your platform's approved scopes. For example, if your platform has invoice:create and distribution:create approved, you can auto-grant either or both to a new business.

Managing businesses

Getting business details

Retrieve business information using the X-Target-Business-Id header.

curl -s \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "X-Target-Business-Id: $BIZ_ID" \
  https://<host>/api/v1/platform/business

Updating a business

Use PATCH to update business fields. At least one field must be provided.

curl -s -X PATCH \
  -H "Authorization: Bearer $PLATFORM_KEY" \
  -H "X-Target-Business-Id: $BIZ_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Games Inc",
    "address": {
      "line1": "456 Commerce Blvd",
      "city": "Austin",
      "state": "TX",
      "postalCode": "78702",
      "country": "US"
    }
  }' \
  https://<host>/api/v1/platform/business

Updatable fields: name, logoUrl, address, payoutWallet.

Payout wallet setup

The payout wallet determines where payments are routed for invoices and distributions. It can be configured in three ways:

1. At creation time — pass payoutWallet in the create request
2. Via API update — use PATCH /v1/platform/business to set it later
3. By the business owner — the owner configures it through the Oncade dashboard

API Quick Reference

All business endpoints are under /v1/platform/business.

References

• Platform API Reference
• Platform Invoices Guide
• Platform Payouts Guide