> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Import and Export Businesses

> Bulk-load Didit Business (KYB) entities from CSV and export the full business table. Available from the Didit Business Console. Pay-per-call billing.

export const AgentPromptAccordion = ({prompt, title = "AI Agent Integration Prompt"}) => {
  const [copied, setCopied] = React.useState(false);
  const handleCopy = e => {
    e.stopPropagation();
    if (!prompt) return;
    navigator.clipboard.writeText(prompt.trim()).then(() => {
      setCopied(true);
      setTimeout(() => setCopied(false), 2000);
    });
  };
  const agents = ["Claude Code", "Codex", "Cursor", "Devin", "Windsurf", "GitHub Copilot"];
  return <div className="didit-agent-card">
      {}
      <div className="didit-agent-titlebar">
        <div className="didit-agent-dots" aria-hidden="true">
          <span className="didit-agent-dot didit-agent-dot-red"></span>
          <span className="didit-agent-dot didit-agent-dot-yellow"></span>
          <span className="didit-agent-dot didit-agent-dot-green"></span>
        </div>
        <span className="didit-agent-filename">{title}</span>
        <button type="button" className={`didit-agent-copy ${copied ? "didit-agent-copy-copied" : ""}`} onClick={handleCopy} title="Copy prompt to clipboard" aria-label={copied ? "Copied!" : "Copy prompt to clipboard"}>
          {copied ? <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <path d="M3 8.5l3.5 3.5L13 4" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
              </svg>
              <span>Copied</span>
            </> : <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <rect x="5" y="5" width="9" height="9" rx="1.5" stroke="currentColor" strokeWidth="1.5" />
                <path d="M11 5V3.5A1.5 1.5 0 0 0 9.5 2h-6A1.5 1.5 0 0 0 2 3.5v6A1.5 1.5 0 0 0 3.5 11H5" stroke="currentColor" strokeWidth="1.5" />
              </svg>
              <span>Copy</span>
            </>}
        </button>
      </div>

      {}
      <pre className="didit-agent-body"><code>{prompt.trim()}</code></pre>

      {}
      <div className="didit-agent-footer">
        <span className="didit-agent-footer-label">Paste into</span>
        <div className="didit-agent-chips">
          {agents.map(name => <span key={name} className="didit-agent-chip">{name}</span>)}
        </div>
      </div>
    </div>;
};

<AgentPromptAccordion
  title="Bulk Import / Export Businesses Prompt"
  prompt={`# Goal — bulk-load (or extract) Didit Business entities programmatically

CSV import / export is console-only. For programmatic bulk operations, loop \`POST /v3/businesses/create/\` for imports and paginate \`GET /v3/businesses/\` for exports.

## Bulk import — loop the create endpoint

\`\`\`bash
# businesses.json — array of records
# [{"vendor_data":"biz-acme","display_name":"Acme Corp","country_code":"GBR"}, ...]

jq -c '.[]' businesses.json | while read biz; do
curl -X POST https://verification.didit.me/v3/businesses/create/ \\
-H "x-api-key: $DIDIT_API_KEY" \\
-H "Content-Type: application/json" \\
-d "$biz"
sleep 0.1   # respect rate limits — see /integration/rate-limiting
done
\`\`\`

Record shape (matches \`POST /v3/businesses/create/\`):

\`\`\`json
{
"vendor_data": "biz-acme",         // required, unique per app
"display_name": "Acme Corp",       // optional
"country_code": "GBR",             // ISO 3166-1 alpha-3, optional
"metadata": {"partner": "Acme Holdings"},
"tags": ["b2b-tier-1"]
}
\`\`\`

\`create\` is **not** idempotent. Upsert pattern:

\`\`\`bash
if curl -s -o /dev/null -w "%{http_code}" \\
 https://verification.didit.me/v3/businesses/$VD/ \\
 -H "x-api-key: $DIDIT_API_KEY" | grep -q 200; then
curl -X PATCH https://verification.didit.me/v3/businesses/$VD/ \\
-H "x-api-key: $DIDIT_API_KEY" -H "Content-Type: application/json" \\
-d "$BODY"
else
curl -X POST https://verification.didit.me/v3/businesses/create/ \\
-H "x-api-key: $DIDIT_API_KEY" -H "Content-Type: application/json" \\
-d "$BODY"
fi
\`\`\`

## Bulk export — paginate the list endpoint

\`\`\`bash
PAGE=1
while :; do
RESP=$(curl -sG https://verification.didit.me/v3/businesses/ \\
-H "x-api-key: $DIDIT_API_KEY" \\
--data-urlencode "page=$PAGE" \\
--data-urlencode "page_size=100")
echo "$RESP" | jq -c '.results[]' >> businesses.ndjson
HAS_NEXT=$(echo "$RESP" | jq -r '.next // empty')
[ -z "$HAS_NEXT" ] && break
PAGE=$((PAGE+1))
done
\`\`\`

Filter with \`status\`, \`country_code\`, \`search\`, date ranges (see /management-api/businesses/list).

## What survives on update vs what stays

| Field | Behaviour |
|---|---|
| \`display_name\`, \`metadata\`, \`tags\` | Overwritten by PATCH |
| \`legal_name\`, \`registration_number\`, \`country_code\` | Read-only after a verified KYB session (overrides logged in audit log) |
| Aggregate counters, \`features\` map | Computed by Didit — never accept writes |

## Failure modes

- \`409\` on create — \`vendor_data\` exists; use PATCH.
- \`429\` — rate limit; back off using \`Retry-After\`. Insert 100ms+ between calls for large batches.
- \`400\` — bad country code or bad JSON. Log and continue.

## Console fallback

The Business Console (Businesses → Import / Export) handles up to 100K rows for imports and 1M rows for exports with chunked async processing and an emailed signed download link.

## Sources of truth

- /management-api/businesses/create — POST /v3/businesses/create/ schema
- /management-api/businesses/list — GET /v3/businesses/ pagination
- /entities/businesses/data-model — mutable vs read-only fields
- /integration/rate-limiting — rate limits
- /integration/integration-prompt — canonical end-to-end prompt
`}
/>

The Business Console supports bulk import and export of Business entities — the same flow available for Users, adapted for business fields.

<Note>
  Bulk import/export here creates or updates Business profiles only. It does not recreate historical KYB sessions, registry reports, officers, beneficial owners, or provider decisions. For a full KYB migration from another provider or registry export, see [Import Data from Another Provider](/sessions-api/import-verifications).
</Note>

## Import businesses from CSV

### When to use it

* **Migration** from another KYB vendor.
* **Partner onboarding** — load a partner's customer list.
* **Metadata backfill** — update tags, tier, or custom fields across many businesses.

### Template columns

Download the template from *Businesses → Import → Download template*:

| Column                | Required | Description                                                          |
| --------------------- | -------- | -------------------------------------------------------------------- |
| `vendor_data`         | Yes      | Your identifier for the business. Unique per application.            |
| `display_name`        | No       | Human-readable name.                                                 |
| `legal_name`          | No       | Legal company name. Will be overwritten by verified registry data.   |
| `registration_number` | No       | Company registration. Will be overwritten by verified registry data. |
| `country_code`        | No       | ISO 3166-1 alpha-3. Triggers dangerous-countries check.              |
| `status`              | No       | `ACTIVE`, `FLAGGED`, or `BLOCKED`. Defaults to `ACTIVE`.             |
| `tags`                | No       | Comma-separated tags.                                                |
| `metadata_json`       | No       | Stringified JSON for custom metadata.                                |

### Running the import

<Steps>
  <Step title="Upload the CSV">
    *Businesses → Import → Upload CSV*.
  </Step>

  <Step title="Review the preview">
    Invalid rows are highlighted. Duplicates (existing `vendor_data`) are flagged as updates.
  </Step>

  <Step title="Start the import">
    Didit processes rows asynchronously; progress is tracked in *Businesses → Import history*.
  </Step>

  <Step title="Review results">
    Download an error report for any skipped rows.
  </Step>
</Steps>

### Update vs create

* New `vendor_data` → creates a new Business.
* Existing `vendor_data` → updates the Business's mutable fields and metadata.
* Registry-derived fields (`legal_name`, `registration_number`, `country_code`) are **not** overwritten by imports after a Business Verification (KYB) session has populated them.

## Export businesses to CSV

### When to use it

* **Compliance audits** and regulator requests.
* **Data warehouse sync** for BI.
* **Partner reporting** — filtered views of businesses by country, tier, or tag.

### Running an export

1. Navigate to *Businesses → Export*.
2. Apply filters (status, country, date range, search, tags).
3. Choose columns.
4. Submit — Didit generates the export asynchronously and emails a signed download link.

Role restrictions apply — see [roles & permissions](/console/roles-permissions).

## Audit trail

All imports and exports are logged with operator, row counts, and timestamps. See [audit logs](/console/audit-logs).

## Next steps

<CardGroup cols={3}>
  <Card title="Create business API" icon="plus" href="/management-api/businesses/create">
    Programmatic bulk creation.
  </Card>

  <Card title="Data retention" icon="shield-halved" href="/console/data-retention">
    How long imported data persists.
  </Card>

  <Card title="Audit logs" icon="file-lines" href="/console/audit-logs">
    Review import/export history.
  </Card>
</CardGroup>