> ## Documentation Index > Fetch the complete documentation index at: https://docs.helloannie.com/llms.txt > Use this file to discover all available pages before exploring further. # Submit business verification > Submits an organization's business verification request for asynchronous processing. Annie validates the required business identity, authorized representative, calling configuration, and messaging documents, then submits the request to the verification and carrier review flow. This verification is required before Annie can complete trusted calling setup and SMS/A2P registration, because carriers require proof that the sender/caller is a real business with proper patient messaging consent. Only one request exists per organization; a later POST updates the same request when canUpdate is true. The API requires all messaging document URLs, and those URLs must be publicly reachable so Annie can snapshot stable copies for carrier review. ## OpenAPI ````yaml /openapi/openapi.yaml post /organizations/{orgId}/business-verification openapi: 3.0.3 info: title: Annie API description: > ### Overview The Annie API is a (mostly) RESTful API. Typically, both POST bodies and responses are JSON-encoded. Note: The documenation is Work In Progress and is subject to change. ### Base URL The base URL for the Annie API is https://api.helloannie.com/. Examples in this document may abbreviate this to `/`. ### Versioning Routes are prefixed with a version number i.e. `v1`. The version will change when there is a non-backwards compatible or other significant change to the api. ### Authentication The Annie API supports two authentication methods API Keys and OAuth Access Tokens: #### API Keys API Keys are long-lived tokens that can be generated from the Developer Portal on your organization page. API keys are prefixed with `annie-sk-v2-` and can be used directly in the `Authorization` header. ``` curl -H "Authorization: Bearer annie-sk-xxxxx" https://api.helloannie.com/... ``` #### OAuth Tokens OAuth tokens are short-lived access tokens generated using the OAuth 2.0 Client Credentials flow (Machine-to-Machine). OAuth clients provide scoped permissions and are ideal for server-to-server integrations. **Creating an OAuth Client** OAuth clients can be created in the Developer Portal on your organization page. When creating a client, you'll receive: - `client_id`: Your OAuth client identifier - `client_secret`: Your OAuth client secret (store this securely) **Generating an OAuth Token** To generate an OAuth access token, make a POST request to the Annie OAuth token endpoint: **Endpoint:** `https://annie-external-api.us.auth0.com/oauth/token` **Example Request:** ```bash curl -X POST https://annie-external-api.us.auth0.com/oauth/token \ -H "Content-Type: application/json" \ -d '{ "grant_type": "client_credentials", "client_id": "your-client-id", "client_secret": "your-client-secret", "audience": "https://api.helloannie.com" }' ``` The `access_token` from the response should be used in the `Authorization` header when making requests to the Annie API: ``` curl -H "Authorization: Bearer eyJhbGciOiJSUzI..." https://api.helloannie.com/v1/... ``` ### API Response Structure The Annie API returns status codes consistent with standard HTTP conventions. Success and Error responses follow the below structure: ``` { "success": boolean "data": {} "message": string // optional } ``` ### Rate Limiting The Annie API enforces rate limits to ensure stability and fair usage. The default rate limit is **60 requests per minute** per organization. This limit is applied per endpoint pattern (e.g. `GET /v1/bots/:id`). When the rate limit is exceeded, the API responds with HTTP `429 Too Many Requests`. Response headers include: - `X-RateLimit-Limit`: The maximum number of requests allowed in the current window. - `X-RateLimit-Remaining`: The number of requests remaining in the current window. - `X-RateLimit-Reset`: The time at which the current rate limit window resets (in UTC epoch seconds). If you exceed the limit, the response will contain a `Retry-After` header indicating how many seconds to wait before retrying. ### Pagination The Annie API does not currently support pagination. All results are returned at once. version: v1 servers: - url: https://api.helloannie.com/v1 security: [] paths: /organizations/{orgId}/business-verification: post: tags: - Business Verification summary: Submit business verification description: >- Submits an organization's business verification request for asynchronous processing. Annie validates the required business identity, authorized representative, calling configuration, and messaging documents, then submits the request to the verification and carrier review flow. This verification is required before Annie can complete trusted calling setup and SMS/A2P registration, because carriers require proof that the sender/caller is a real business with proper patient messaging consent. Only one request exists per organization; a later POST updates the same request when canUpdate is true. The API requires all messaging document URLs, and those URLs must be publicly reachable so Annie can snapshot stable copies for carrier review. operationId: postV1OrganizationsByOrgIdBusiness-verification parameters: - name: orgId in: path required: true schema: format: uuid description: Organization ID type: string requestBody: description: >- Business verification proves the legal organization, responsible representative, calling identity, and messaging consent materials before Annie can complete carrier setup for calls and SMS. Submit this payload to create the org's single verification request or update it when the current status allows changes. required: true content: application/json: schema: $ref: '#/components/schemas/BusinessVerificationSubmitRequest' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/BusinessVerificationSubmitRequest' multipart/form-data: schema: $ref: '#/components/schemas/BusinessVerificationSubmitRequest' responses: '202': description: >- Response returned when submitting or checking business verification. Use the top-level status for product logic and steps/issues for user-facing detail. content: application/json: schema: $ref: '#/components/schemas/BusinessVerificationResponse' '400': description: The request was invalid or malformed content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' '403': description: You do not have permission to perform this action content: application/json: schema: $ref: '#/components/schemas/ForbiddenResponse' '404': description: The requested resource was not found content: application/json: schema: $ref: '#/components/schemas/NotFoundResponse' '409': description: The request conflicts with another in-progress operation content: application/json: schema: $ref: '#/components/schemas/ConflictResponse' '500': description: An internal server error occurred content: application/json: schema: $ref: '#/components/schemas/ServerErrorResponse' components: schemas: BusinessVerificationSubmitRequest: additionalProperties: false type: object required: - business - authorizedRepresentative - messaging properties: business: additionalProperties: false description: >- Legal business identity. Verification providers and carriers require this information to confirm the sender/caller is a real organization before approving telephony and messaging. type: object required: - legalBusinessName - ein - businessType - dba - websiteUrl - address properties: legalBusinessName: minLength: 1 description: >- Legal business name registered with the EIN. This should match tax and business registration records, not just the public practice name. type: string ein: minLength: 1 description: >- US employer identification number for the legal business. Carriers use this to verify the organization. type: string businessType: default: llc description: Legal entity type for the organization being verified. type: string enum: - llc - sole_proprietorship - corporation - partnership - non_profit_corporation - co_operative dba: minLength: 1 description: >- Doing-business-as or public practice name patients recognize. This may differ from the legal business name. type: string websiteUrl: minLength: 1 description: >- Public business website URL. Annie normalizes this to HTTPS before provider submission. type: string address: additionalProperties: false description: >- Physical business address for the legal organization or office being verified. type: object required: - addressLine1 - city - state - zip - country properties: addressLine1: minLength: 1 type: string addressLine2: type: string nullable: true city: minLength: 1 type: string state: minLength: 1 type: string zip: minLength: 1 type: string country: minLength: 2 maxLength: 2 default: US type: string authorizedRepresentative: additionalProperties: false description: >- Person authorized to submit the business for provider/carrier verification. type: object required: - firstName - lastName - email - phone - businessTitle - jobPosition properties: firstName: minLength: 1 description: First name of the person authorized to represent the business. type: string lastName: minLength: 1 description: Last name of the person authorized to represent the business. type: string email: minLength: 1 description: Business email address for the authorized representative. type: string phone: minLength: 1 description: Business phone number for the authorized representative. type: string businessTitle: minLength: 1 description: >- Title of the authorized representative at the business, for example Owner or Practice Manager. type: string jobPosition: default: Director description: Supported job position value for the authorized representative. type: string enum: - Director - GM - VP - CEO - CFO - General Counsel - Other calling: additionalProperties: false description: >- Calling configuration tied to business verification. Calling setup lets outbound calls display a verified business identity. type: object properties: cnamDisplayName: maxLength: 15 pattern: ^[a-zA-Z][a-zA-Z0-9 .,]*$ description: >- Caller ID display name for outbound calls. This is used for CNAM setup and is limited to 15 characters. type: string messaging: additionalProperties: false description: >- Messaging registration details. Carriers require consent, terms, and privacy materials before approving application-to-person SMS traffic. type: object required: - documents - attestations properties: documents: additionalProperties: false description: >- Required SMS registration documents. Unlike the UI, the API requires all three document URLs on submission. type: object required: - privacyPolicyUrl - termsAndConditionsUrl - patientIntakeFormUrl properties: privacyPolicyUrl: minLength: 1 description: >- Publicly accessible privacy policy URL. The link must not require authentication and must be reachable by Annie so it can be snapshotted for carrier review. type: string termsAndConditionsUrl: minLength: 1 description: >- Publicly accessible terms and conditions URL for SMS messaging. The link must not require authentication and must be reachable by Annie. type: string patientIntakeFormUrl: minLength: 1 description: >- Publicly accessible patient intake or SMS consent form URL. The document should show how patients consent to receive text messages. type: string attestations: additionalProperties: false description: Required compliance attestations for SMS registration. type: object required: - hasPrivacyPolicyOptIn - hasTcpaCompliance properties: hasPrivacyPolicyOptIn: description: >- Confirms the provided privacy policy and consent materials include the required SMS opt-in disclosures. enum: - true type: boolean hasTcpaCompliance: description: >- Confirms the business has proper TCPA-compliant consent to send text messages to patients. enum: - true type: boolean BusinessVerificationResponse: additionalProperties: false type: object required: - success - data properties: success: enum: - true type: boolean data: additionalProperties: false description: >- Business verification proves the legal organization, responsible representative, calling identity, and messaging consent materials before Annie can complete carrier setup for calls and SMS. This object is designed for polling after submission and for showing users what action, if any, is required. type: object required: - orgId - status - canUpdate - reason - issues - steps - submittedAt - reviewedAt - updatedAt properties: orgId: format: uuid type: string status: default: missing_information description: >- Overall business verification status. missing_information means the request has not been submitted, required data is missing, document links failed validation, or the verification provider/carrier needs corrected information. in_progress means Annie accepted the request and is validating, submitting, or waiting on provider/carrier review. passed means the business profile, calling setup, and messaging setup are approved. failed means a provider or carrier step failed and the reason/steps fields explain what happened. type: string enum: - missing_information - in_progress - passed - failed canUpdate: description: >- Whether POST can currently update the request. This is false while business or messaging review is locked by an active provider/carrier review. type: boolean reason: description: >- Human-readable summary of the overall status. For missing_information or failed responses, this is the first place to look for the next action. type: string nullable: true issues: description: >- Actionable validation or provider/carrier issues. Empty when there is no known customer action. type: array items: additionalProperties: false description: A validation, provider, or carrier review issue type: object required: - field - code - message properties: field: description: >- Dot-separated request field path, when the issue maps to a specific field. Null means the issue applies to the request as a whole. type: string nullable: true code: description: Stable machine-readable issue code type: string message: description: Human-readable issue detail type: string steps: additionalProperties: false description: >- Step-level statuses. businessProfile covers the legal organization review, calling covers voice caller identity setup, and messaging covers SMS/A2P registration. type: object required: - businessProfile - calling - messaging properties: businessProfile: additionalProperties: false description: >- Status for one part of the verification flow: legal business profile, calling setup, or messaging setup. type: object required: - status - reason - providerStatus properties: status: default: missing_information description: >- Overall business verification status. missing_information means the request has not been submitted, required data is missing, document links failed validation, or the verification provider/carrier needs corrected information. in_progress means Annie accepted the request and is validating, submitting, or waiting on provider/carrier review. passed means the business profile, calling setup, and messaging setup are approved. failed means a provider or carrier step failed and the reason/steps fields explain what happened. type: string enum: - missing_information - in_progress - passed - failed reason: description: >- Human-readable explanation for this step's current status, especially when action is needed or a provider/carrier step failed. type: string nullable: true providerStatus: description: >- Provider-specific status from the verification or carrier review flow. Use the normalized status and reason fields for product logic. type: string nullable: true calling: additionalProperties: false description: >- Status for one part of the verification flow: legal business profile, calling setup, or messaging setup. type: object required: - status - reason - providerStatus properties: status: default: missing_information description: >- Overall business verification status. missing_information means the request has not been submitted, required data is missing, document links failed validation, or the verification provider/carrier needs corrected information. in_progress means Annie accepted the request and is validating, submitting, or waiting on provider/carrier review. passed means the business profile, calling setup, and messaging setup are approved. failed means a provider or carrier step failed and the reason/steps fields explain what happened. type: string enum: - missing_information - in_progress - passed - failed reason: description: >- Human-readable explanation for this step's current status, especially when action is needed or a provider/carrier step failed. type: string nullable: true providerStatus: description: >- Provider-specific status from the verification or carrier review flow. Use the normalized status and reason fields for product logic. type: string nullable: true messaging: additionalProperties: false description: >- Status for one part of the verification flow: legal business profile, calling setup, or messaging setup. type: object required: - status - reason - providerStatus properties: status: default: missing_information description: >- Overall business verification status. missing_information means the request has not been submitted, required data is missing, document links failed validation, or the verification provider/carrier needs corrected information. in_progress means Annie accepted the request and is validating, submitting, or waiting on provider/carrier review. passed means the business profile, calling setup, and messaging setup are approved. failed means a provider or carrier step failed and the reason/steps fields explain what happened. type: string enum: - missing_information - in_progress - passed - failed reason: description: >- Human-readable explanation for this step's current status, especially when action is needed or a provider/carrier step failed. type: string nullable: true providerStatus: description: >- Provider-specific status from the verification or carrier review flow. Use the normalized status and reason fields for product logic. type: string nullable: true submittedAt: type: string format: date-time nullable: true reviewedAt: type: string format: date-time nullable: true updatedAt: type: string format: date-time nullable: true BadRequestResponse: additionalProperties: false type: object required: - success - data - message properties: success: enum: - false type: boolean data: additionalProperties: false type: object properties: {} message: type: string ForbiddenResponse: additionalProperties: false type: object required: - success - data - message properties: success: enum: - false type: boolean data: additionalProperties: false type: object properties: {} message: type: string NotFoundResponse: additionalProperties: false type: object required: - success - data - message properties: success: enum: - false type: boolean data: additionalProperties: false type: object properties: {} message: type: string ConflictResponse: additionalProperties: false type: object required: - success - data - message properties: success: enum: - false type: boolean data: additionalProperties: false type: object properties: {} message: type: string ServerErrorResponse: additionalProperties: false type: object required: - success - data - message properties: success: enum: - false type: boolean data: additionalProperties: false type: object properties: {} message: type: string ````