---
title: "Save your business verification profile"
method: PUT
path: "/v1/business-verification"
tags: ["Accounts"]
---

# Save your business verification profile

`PUT /v1/business-verification`

## Request

- Base URL: `https://api.honkio.ca`
- URL: `https://api.honkio.ca/v1/business-verification`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Creates the profile, or replaces it while it is DRAFT, VERIFIED, CHANGES_REQUESTED or DECLINED (BUSINESS_VERIFICATION_NOT_EDITABLE otherwise). Every field is checked. The status does not change, except that a VERIFIED profile goes back to DRAFT: submit it when it is ready. Changes to a verified business go back to HonkIO for review, and the account stays verified (verified is true) in the meantime, as it was verified: verified_details, not the changed fields, is what counts until HonkIO verifies the changes. A test key can save a profile that was never verified, but changing a verified business needs a live key (LIVE_KEY_REQUIRED).

Requires `account:m`.

## Request body

- object: Your business and a contact person.
  - `business_name` string, required: The legal name: as registered with the CRA or your province, or your own name for a sole proprietorship.
  - `doing_business_as` string, nullable: The name the business trades under, when it differs from the legal name.
  - `entity_type` 'SOLE_PROPRIETOR' | 'PRIVATE_PROFIT' | 'PUBLIC_PROFIT' | 'NON_PROFIT' | 'GOVERNMENT', required: The kind of organization. GET /v1/toll-free-verifications/options lists the values with labels.
  - `business_registration_number` string, nullable: The CRA business number: 9 digits, optionally followed by a program account such as RC0001. Spaces and hyphens are ignored. Required unless entity_type is SOLE_PROPRIETOR.
  - `business_address` object, required: Where the business is registered or operates, in Canada. line2 (suite, unit or floor) is optional.
    - `line1` string, required
    - `city` string, required
    - `province` 'AB' | 'BC' | 'MB' | 'NB' | 'NL' | 'NS' | 'NT' | 'NU' | 'ON' | 'PE' | 'QC' | 'SK' | 'YT', required: Two-letter province or territory code.
    - `postal_code` string, required: Canadian postal code, e.g. K1A 0B1.
    - `line2` string, nullable
  - `website` string, required: An https link that shows the business: its website or, for a sole proprietor, a public profile such as LinkedIn or an app store listing.
  - `business_description` string, required: What the business does and who it serves, 20 to 500 characters.
  - `contact` object, required: The person HonkIO staff can contact about the review.
    - `first_name` string, required
    - `last_name` string, required
    - `email` string, email, required
    - `phone` string, required: A North American phone number, e.g. +14165550100.

## Response `200`

The saved profile.

- BusinessVerification: Your business verification: the profile staff review, where the review stands and, when they asked for changes, declined or revoked it, why.
  - `id` string, required
  - `status` 'DRAFT' | 'IN_REVIEW' | 'VERIFIED' | 'CHANGES_REQUESTED' | 'DECLINED' | 'REVOKED', required: DRAFT, then IN_REVIEW (HonkIO staff), then VERIFIED. CHANGES_REQUESTED and DECLINED can be edited and submitted again; REVOKED can only be restored by HonkIO staff. Editing a VERIFIED profile moves it back to DRAFT for another review.
  - `verified` boolean, required: Whether the business counts as verified. It stays true while the changed details of a verified business are reviewed again (status DRAFT, IN_REVIEW or CHANGES_REQUESTED), and turns false when HonkIO staff decline the changes or revoke the verification.
  - `verified_at` string, date-time, nullable, required: When HonkIO staff last verified the business; null when it is not verified.
  - `verified_details` object, nullable, required: The business as HonkIO staff last verified it. While changed details are reviewed again, the fields below show the changes and this keeps what was verified: toll-free verification reads its business number. Null when the business is not verified.
    - `business_name` string, required
    - `doing_business_as` string, nullable, required
    - `entity_type` 'SOLE_PROPRIETOR' | 'PRIVATE_PROFIT' | 'PUBLIC_PROFIT' | 'NON_PROFIT' | 'GOVERNMENT', required
    - `business_registration_number` string, nullable, required
  - `business_name` string, required
  - `doing_business_as` string, nullable, required
  - `entity_type` 'SOLE_PROPRIETOR' | 'PRIVATE_PROFIT' | 'PUBLIC_PROFIT' | 'NON_PROFIT' | 'GOVERNMENT', required
  - `business_registration_number` string, nullable, required
  - `business_address` object, nullable, required
    - `line1` string, required
    - `line2` string, nullable, required
    - `city` string, required
    - `province` string, required
    - `postal_code` string, required
  - `website` string, nullable, required
  - `business_description` string, nullable, required
  - `contact` object, required
    - `first_name` string, nullable, required
    - `last_name` string, nullable, required
    - `email` string, nullable, required
    - `phone` string, nullable, required
  - `reviewer_note` string, nullable, required: What HonkIO staff asked to change, or why they declined the profile.
  - `revoked_reason` string, nullable, required: Why HonkIO staff revoked the verification.
  - `submitted_at` string, date-time, nullable, required
  - `reviewed_at` string, date-time, nullable, required
  - `revoked_at` string, date-time, nullable, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `401`: Missing, invalid, revoked or expired API key.
- `402`: The account has no balance, or a LIVE key was used before the first top-up.
- `403`: LIVE_KEY_REQUIRED: a test key cannot change the profile of a verified business, including one whose changed details are in review. It can save a profile that was never verified. Also FORBIDDEN when the key lacks the permission this operation requires, or the account is suspended or closed.
- `409`: BUSINESS_VERIFICATION_NOT_EDITABLE: the profile is in review or revoked.
- `422`: VALIDATION_ERROR: the request failed validation; details names the fields.
- `429`: Rate limit reached: 100 requests per second per account, or a route-specific limit (Retry-After set where one applies).
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/honkio/apis/honkio-api.md) · [All operations](https://skmtc.dev/honkio/apis/honkio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/honkio/apis/honkio-api/revisions/ce4ed3fe9691?raw)