Team Setup

Use a partner API key for the partner-scoped routes on this page. Partner API keys are issued by VRPlatform during partner onboarding — see Authentication and Credentials. Collection routes like list teams are partner-scoped and take no x-team-id header. Singleton team routes use x-team-id.

Discover Teams

curl 'https://api.vrplatform.app/teams' \
  -H 'x-api-key: <partner-api-key>'

Store the returned team ID. Use it for team-scoped product requests and embedded sessions.

Create A Team

curl 'https://api.vrplatform.app/teams' \
  -X POST \
  -H 'x-api-key: <partner-api-key>' \
  -H 'content-type: application/json' \
  --data '{
    "name": "Example Team",
    "email": "team@example.com",
    "generalLedger": false
  }'

The generated operation defines all optional billing, address, portal, and member fields. generalLedger: false creates the team without accounting setup. When generalLedger is omitted, true, or a configuration object, the API runs team initialization as part of the create request: it provisions the chart of accounts, tax rates, statement layouts, recurring fees, and line mappings from the default template (or from copyFromTeamId in the configuration object). Create team does not support dry run.

When provisioning with a partner API key, uniqueRef is required: send your own stable identifier for the customer. Creating a team with a uniqueRef that already exists for your partner fails with 409 — load the existing team with lookup team instead of re-posting. Retrying a create request that failed before completing is safe; a request that succeeded must not be repeated.

Initialize Later

Use initialize team only when the selected team still needs GL initialization or a specific copy/include plan. Send the selected team in x-team-id. The operation supports dry run.

Initialization can copy selected accounts, tax rates, mappings, fees, or statement layouts. Treat it as an accounting setup operation, not a repeated idempotent bootstrap call.

Verify

Load the selected team and inspect ID, status, type, GL state, books-closing date, partner relationship, and available connection capabilities. Then continue to Connections.

List Managed-Team Users

Use list partner users to build a user directory across managed child teams. The collection excludes anyone who has a direct membership on the partner team itself, even when that person also has a managed child-team membership. Search, user views, team filters, totals, and pagination all operate after this exclusion.

When the portfolio spans regions, request each region advertised by GET /me with x-data-region; one response contains only the selected regional partition.

List Partner-Team Members

Use list partner members to build the partner team's own member directory. Each root row includes the member's role, status, and lastInvitedAt from the partner-team membership. Its memberships array contains only managed child-team memberships.

Invite A Team Member

Use invite team member with the selected team in x-team-id. Set sendEmail: false to create a copyable link instead of sending the email immediately. The endpoint does not support dry run because it creates an invite token and dispatches notification work.

An email already used by an owner account cannot also be invited as a team member. That request returns 400 BAD_REQUEST; use the structured error code for behavior and display its message to explain the conflict.

Delete A Team

DELETE /team?confirm=true queues deletion of the team selected by x-team-id. This administrative operation requires an authenticated active VRPlatform member. Partner API keys, service tokens, and ordinary tenant users receive 403 and must contact VRPlatform support. force=true bypasses active resource checks, but it does not bypass the active-subscription guard.

Deletion runs asynchronously after validation. A successful response confirms that the deletion task was queued, not that every cleanup step has completed.