> ## Documentation Index > Fetch the complete documentation index at: https://docs.beltic.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Business Lookup > Create a new business registry lookup request. This will queue a task to fetch business information from country-specific vendor APIs. **Processing Modes:** - **Async Mode** (`async: true`): Returns immediately with `201 Created` and processing status. Client should poll the GET endpoint for completion. - **Sync Mode** (`async: false`): Waits up to 45 seconds for completion. - If processing completes within 45 seconds: Returns `200 OK` with full business data. - If timeout occurs: Returns `201 Created` with processing status (client should poll for completion). **Country Requirements:** - **US**: Requires `country`, `official_name`, and `address` - **BR**: Requires `country` and `registration_number` - **GB**: Requires `country` and `registration_number` - **ZZ**: Test country, requires `country` and at least one input field (`official_name`, `registration_number`, or `address`) **Workflow:** 1. Call this endpoint to create a business lookup task 2. The task is queued and processed by a country-specific service 3. Poll the GET endpoint (or wait in sync mode) to retrieve results **Note:** The business record is created immediately with `async_status: processing`. The record will be updated with results when processing completes. ## OpenAPI ````yaml POST /v1/businesses openapi: 3.1.0 info: title: Beltic Business API version: 1.0.0 description: >- # Business Registry API The Beltic Business API provides business registry lookup capabilities across multiple countries and vendors. ## Key Features - **Multi-Country Support**: Lookup business information from various country registries - **Vendor Integration**: Aggregates data from multiple vendor sources - **Async Processing**: Support for both synchronous and asynchronous processing modes - **JSON:API Format**: All responses follow JSON:API specification ## Workflow 1. **Create Business Lookup**: Submit a business lookup request with country and search parameters 2. **Processing**: The request is queued and processed by country-specific services 3. **Retrieve Results**: Poll the business record to get updated status and results ## Processing Modes - **Async Mode** (async: true): Returns immediately with processing status. Client polls for completion. - **Sync Mode** (async: false): Waits up to 45 seconds for completion. Returns processing status if timeout. ## Authentication All endpoints require authentication. Include your API key in the `x-api-key` header: ``` x-api-key: YOUR_API_KEY ``` ## Response Format All responses follow the JSON:API specification for consistent data structures. contact: name: Beltic API Support email: engineering@beltic.com servers: - url: https://api.beltic.com description: Production security: - ApiKeyAuth: [] tags: - name: Business description: >- Manage business registry lookups. Create lookup requests, retrieve results, and list business records. Supports multiple countries and vendors with async/sync processing modes. externalDocs: description: Beltic Platform Documentation url: https://docs.beltic.com paths: /v1/businesses: post: tags: - Business summary: Create business lookup description: >- Create a new business registry lookup request. This will queue a task to fetch business information from country-specific vendor APIs. **Processing Modes:** - **Async Mode** (`async: true`): Returns immediately with `201 Created` and processing status. Client should poll the GET endpoint for completion. - **Sync Mode** (`async: false`): Waits up to 45 seconds for completion. - If processing completes within 45 seconds: Returns `200 OK` with full business data. - If timeout occurs: Returns `201 Created` with processing status (client should poll for completion). **Country Requirements:** - **US**: Requires `country`, `official_name`, and `address` - **BR**: Requires `country` and `registration_number` - **GB**: Requires `country` and `registration_number` - **ZZ**: Test country, requires `country` and at least one input field (`official_name`, `registration_number`, or `address`) **Workflow:** 1. Call this endpoint to create a business lookup task 2. The task is queued and processed by a country-specific service 3. Poll the GET endpoint (or wait in sync mode) to retrieve results **Note:** The business record is created immediately with `async_status: processing`. The record will be updated with results when processing completes. requestBody: content: application/json: schema: type: object properties: data: type: object properties: type: type: string enum: - business meta: type: object properties: search_parameters: type: object properties: country: type: string minLength: 2 maxLength: 2 description: >- ISO 3166-1 alpha-2 country code (e.g., US, BR, GB) example: US input: type: object properties: official_name: type: - string - 'null' registration_number: type: - string - 'null' address: type: - string - 'null' description: >- Search input parameters - at least one field must be provided async: type: boolean description: >- If false, wait up to 45 seconds for completion. If true, return immediately with processing status. example: false required: - country - input - async required: - search_parameters description: Business lookup metadata relationships: type: object properties: session: type: object properties: data: type: - object - 'null' properties: type: type: string enum: - session id: type: string format: uuid required: - type - id description: >- Session resource identifier. Links this business to a session (1:1). description: JSON:API relationships. Optional session link (1:1). required: - type - meta required: - data responses: '200': description: >- Business lookup completed (sync mode only). Returned when `async: false` and processing completes within 45 seconds. content: application/json: schema: type: object properties: id: type: string type: type: string enum: - business attributes: type: object properties: is_registered: type: - boolean - 'null' official_name: type: - string - 'null' status: type: - string - 'null' legal_form: type: - string - 'null' registration_date: type: - string - 'null' dissolution_date: type: - string - 'null' translation: type: - object - 'null' properties: official_name: type: - string - 'null' status: type: - string - 'null' legal_form: type: - string - 'null' registered_address: type: - object - 'null' properties: formatted_address: type: string street: type: string street2: type: - string - 'null' city: type: string state_or_province: type: string postal_code: type: string po_box: type: - string - 'null' country: type: string latitude: type: - number - 'null' longitude: type: - number - 'null' start_date: type: - string - 'null' end_date: type: - string - 'null' translation: type: - object - 'null' properties: official_name: type: - string - 'null' status: type: - string - 'null' legal_form: type: - string - 'null' required: - formatted_address - street - city - state_or_province - postal_code - country physical_address: type: - object - 'null' properties: formatted_address: type: string street: type: string street2: type: - string - 'null' city: type: string state_or_province: type: string postal_code: type: string po_box: type: - string - 'null' country: type: string latitude: type: - number - 'null' longitude: type: - number - 'null' start_date: type: - string - 'null' end_date: type: - string - 'null' translation: type: - object - 'null' properties: official_name: type: - string - 'null' status: type: - string - 'null' legal_form: type: - string - 'null' required: - formatted_address - street - city - state_or_province - postal_code - country identifiers: type: - array - 'null' items: type: object properties: type: type: string value: type: string required: - type - value industry: type: - array - 'null' items: type: object properties: code: type: string description: type: string system: type: string is_primary: type: boolean translation: type: - object - 'null' properties: official_name: type: - string - 'null' status: type: - string - 'null' legal_form: type: - string - 'null' required: - code - description - system - is_primary capital: type: - object - 'null' properties: registered: type: - object - 'null' properties: amount: type: number currency: type: string required: - amount - currency paid_up: type: - object - 'null' properties: amount: type: number currency: type: string required: - amount - currency officers: type: - array - 'null' items: type: object properties: name: type: string type: type: string date_of_birth: type: - string - 'null' id_type: type: - string - 'null' id_number: type: - string - 'null' start_date: type: - string - 'null' end_date: type: - string - 'null' address_detail: type: - object - 'null' properties: formatted_address: type: string street: type: string street2: type: - string - 'null' city: type: string state_or_province: type: string postal_code: type: string po_box: type: - string - 'null' country: type: string latitude: type: - number - 'null' longitude: type: - number - 'null' start_date: type: - string - 'null' end_date: type: - string - 'null' translation: type: - object - 'null' properties: official_name: type: - string - 'null' status: type: - string - 'null' legal_form: type: - string - 'null' required: - formatted_address - street - city - state_or_province - postal_code - country translation: type: - object - 'null' properties: official_name: type: - string - 'null' status: type: - string - 'null' legal_form: type: - string - 'null' states: type: - array - 'null' items: type: string sources: type: - array - 'null' items: type: string required: - name - type shareholders: type: - array - 'null' items: type: object properties: name: type: string shareholder_type: type: string date_of_birth: type: - string - 'null' id_type: type: - string - 'null' id_number: type: - string - 'null' number_of_share: type: - string - 'null' percentage_of_share: type: - number - 'null' effective_date: type: - string - 'null' end_date: type: - string - 'null' translation: type: - object - 'null' properties: official_name: type: - string - 'null' status: type: - string - 'null' legal_form: type: - string - 'null' required: - name - shareholder_type contacts: type: - array - 'null' items: type: object properties: type: type: string value: type: string description: type: - string - 'null' start_date: type: - string - 'null' end_date: type: - string - 'null' required: - type - value name_history: type: - array - 'null' items: type: object properties: name: type: string effective_date: type: string end_date: type: - string - 'null' translation: type: - object - 'null' properties: official_name: type: - string - 'null' status: type: - string - 'null' legal_form: type: - string - 'null' required: - name - effective_date activity_history: type: - array - 'null' items: type: object properties: activity: type: string date: type: string required: - activity - date latest_annual_return: type: - object - 'null' properties: year_of_filing: type: - string - 'null' annual_meeting_date: type: - string - 'null' relationships: type: object properties: sessions: type: object properties: data: type: array items: type: object properties: type: type: string id: type: string required: - type - id required: - data required: - id - type - attributes - relationships '201': description: >- Business lookup created and processing. Returned for async mode (`async: true`) or when sync mode times out. Poll the GET endpoint for completion. content: application/json: schema: type: object properties: id: type: string type: type: string enum: - business attributes: type: object properties: is_registered: type: - boolean - 'null' official_name: type: - string - 'null' status: type: - string - 'null' legal_form: type: - string - 'null' registration_date: type: - string - 'null' dissolution_date: type: - string - 'null' translation: type: - object - 'null' properties: official_name: type: - string - 'null' status: type: - string - 'null' legal_form: type: - string - 'null' registered_address: type: - object - 'null' properties: formatted_address: type: string street: type: string street2: type: - string - 'null' city: type: string state_or_province: type: string postal_code: type: string po_box: type: - string - 'null' country: type: string latitude: type: - number - 'null' longitude: type: - number - 'null' start_date: type: - string - 'null' end_date: type: - string - 'null' translation: type: - object - 'null' properties: official_name: type: - string - 'null' status: type: - string - 'null' legal_form: type: - string - 'null' required: - formatted_address - street - city - state_or_province - postal_code - country physical_address: type: - object - 'null' properties: formatted_address: type: string street: type: string street2: type: - string - 'null' city: type: string state_or_province: type: string postal_code: type: string po_box: type: - string - 'null' country: type: string latitude: type: - number - 'null' longitude: type: - number - 'null' start_date: type: - string - 'null' end_date: type: - string - 'null' translation: type: - object - 'null' properties: official_name: type: - string - 'null' status: type: - string - 'null' legal_form: type: - string - 'null' required: - formatted_address - street - city - state_or_province - postal_code - country identifiers: type: - array - 'null' items: type: object properties: type: type: string value: type: string required: - type - value industry: type: - array - 'null' items: type: object properties: code: type: string description: type: string system: type: string is_primary: type: boolean translation: type: - object - 'null' properties: official_name: type: - string - 'null' status: type: - string - 'null' legal_form: type: - string - 'null' required: - code - description - system - is_primary capital: type: - object - 'null' properties: registered: type: - object - 'null' properties: amount: type: number currency: type: string required: - amount - currency paid_up: type: - object - 'null' properties: amount: type: number currency: type: string required: - amount - currency officers: type: - array - 'null' items: type: object properties: name: type: string type: type: string date_of_birth: type: - string - 'null' id_type: type: - string - 'null' id_number: type: - string - 'null' start_date: type: - string - 'null' end_date: type: - string - 'null' address_detail: type: - object - 'null' properties: formatted_address: type: string street: type: string street2: type: - string - 'null' city: type: string state_or_province: type: string postal_code: type: string po_box: type: - string - 'null' country: type: string latitude: type: - number - 'null' longitude: type: - number - 'null' start_date: type: - string - 'null' end_date: type: - string - 'null' translation: type: - object - 'null' properties: official_name: type: - string - 'null' status: type: - string - 'null' legal_form: type: - string - 'null' required: - formatted_address - street - city - state_or_province - postal_code - country translation: type: - object - 'null' properties: official_name: type: - string - 'null' status: type: - string - 'null' legal_form: type: - string - 'null' states: type: - array - 'null' items: type: string sources: type: - array - 'null' items: type: string required: - name - type shareholders: type: - array - 'null' items: type: object properties: name: type: string shareholder_type: type: string date_of_birth: type: - string - 'null' id_type: type: - string - 'null' id_number: type: - string - 'null' number_of_share: type: - string - 'null' percentage_of_share: type: - number - 'null' effective_date: type: - string - 'null' end_date: type: - string - 'null' translation: type: - object - 'null' properties: official_name: type: - string - 'null' status: type: - string - 'null' legal_form: type: - string - 'null' required: - name - shareholder_type contacts: type: - array - 'null' items: type: object properties: type: type: string value: type: string description: type: - string - 'null' start_date: type: - string - 'null' end_date: type: - string - 'null' required: - type - value name_history: type: - array - 'null' items: type: object properties: name: type: string effective_date: type: string end_date: type: - string - 'null' translation: type: - object - 'null' properties: official_name: type: - string - 'null' status: type: - string - 'null' legal_form: type: - string - 'null' required: - name - effective_date activity_history: type: - array - 'null' items: type: object properties: activity: type: string date: type: string required: - activity - date latest_annual_return: type: - object - 'null' properties: year_of_filing: type: - string - 'null' annual_meeting_date: type: - string - 'null' relationships: type: object properties: sessions: type: object properties: data: type: array items: type: object properties: type: type: string id: type: string required: - type - id required: - data required: - id - type - attributes - relationships '400': description: Validation error content: application/json: schema: type: object properties: errors: type: array items: type: object properties: status: type: string title: type: string detail: type: string required: - status - title - detail required: - errors security: - ApiKeyAuth: [] components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-Api-Key description: |- API key for authentication. Access https://console.beltic.com/ to obtain your API key. ````