Partner Provisioning API

The Partner Provisioning API lets an approved partner (builder, insurer, realtor, property manager) stand up a complete Dib home for a user with a few API calls: create a setup, drop in documents (Dib extracts the details), set structured values, then finalize it into a real account.

Unlike a normal Dib key, a partner key isn't tied to an existing team — it's what you use to create brand-new accounts.

Authentication

Partner keys look like dibp_live_… and dibp_test_…. They're minted for you by the Dib team. Send yours as a Bearer token:

Authorization: Bearer dibp_live_abc...xyz

Partner keys carry their own scopes:

• partner:accounts:write— create and read setups
• partner:documents:write— upload + extract documents
• partner:data:write— set property, inventory, vehicles, rooms, tasks
• partner:finalize— provision the account

The flow

1. Create a setup. POST /partner/v1/accounts returns a setup_id. Everything you add hangs off this staging container — nothing real is created yet.
2. Add documents (optional). Presign with POST /partner/v1/accounts/{id}/documents, PUT the file to the returned URL, then POST …/documents/{docId}/process to extract.
3. Set values (optional). Post to /property, /inventory, /vehicles, /rooms, or /tasks.
4. Finalize. POST /partner/v1/accounts/{id}/finalize.

Finalize modes

• invite(default) — we email the user a one-click magic link. They claim ownership on click. Always use this unless you have a reason not to.
• managed(verified partners only) — we provision silently, send no email, and return team_id + magic_link so you can keep operating and hand off access whenever you like.

Finalize is idempotent: a retried call returns the already-finalized state instead of creating a second account. Pass an Idempotency-Key header to make retries explicit.

Quick example

# 1. Create a setup
curl -X POST https://dib.io/api/partner/v1/accounts \
  -H "Authorization: Bearer dibp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"partner_type":"builder","recipient_email":"jane@example.com"}'
# -> { "data": { "setup_id": "..." } }

# 2. Stage some inventory
curl -X POST https://dib.io/api/partner/v1/accounts/SETUP_ID/inventory \
  -H "Authorization: Bearer dibp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"items":[{"name":"Refrigerator","brand":"LG","model":"LRFVS3006S"}]}'

# 3. Finalize -> emails Jane a one-click claim link
curl -X POST https://dib.io/api/partner/v1/accounts/SETUP_ID/finalize \
  -H "Authorization: Bearer dibp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"mode":"invite"}'

Limits & safety

• Up to 100 documents and 1,000 inventory items per setup.
• Per-partner rate limits apply; back off on the Retry-After header.
• In invite mode the user is always emailed, so they know an account was created for them.
• Need a key or managed-mode verification? Email developers@dib.io.