> ## Documentation Index > Fetch the complete documentation index at: https://docs.akta.pro/llms.txt > Use this file to discover all available pages before exploring further. # Company Addition ## Overview The Company Addition API lets you add a company that isn't yet in akta.pro's database. If the Company Search API returns no results for a company, submit it here and akta.pro will add it. If the company already exists in the database, the API tells you so immediately and returns its details — no addition request is created. Otherwise, this is an **asynchronous, two-step endpoint**: 1. **Submit** a company for addition with a `POST` request. If it's new, the API returns a `request_id`. 2. **Track** the request to completion, either by polling the [request status endpoint](/docs/supporting-apis/request-status-api) with that `request_id`, or by [configuring a webhook](/webhook-config) to be notified when the status changes. This is a **free endpoint** so it does not consume API credits. **Endpoint** ```text theme={null} POST https://api.akta.pro/api/v1/company/addition-requests/ ``` Pass the `company_name` and `website` in a JSON request body. The `request_id` returned can then be used to check the status of the addition request. **Plan availability:** This endpoint is only available to **Subscription** and **Enterprise** plan users. **Rate limits:** Subscription plans are limited to **100 requests/day** on this endpoint. Enterprise plans have **custom rate limits** — contact your account representative to configure these. *** ## Authentication All requests must include an **API key** in the `x-api-key` HTTP header. ```text theme={null} x-api-key: ``` Never expose your API key in client-side code, browser requests, or public repositories. A missing or invalid key returns `401 Unauthorized`. *** ## Request Reference Send a JSON body with the `Content-Type: application/json` header. | Parameter | Type | Required | Description | | -------------- | ------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------- | | `company_name` | string | **Required** | Name of the company to add (e.g. `"solios"`). | | `website` | string | **Required** | Primary website URL of the company (e.g. `"https://www.soleosenergy.com/"`). Used to disambiguate and entity-resolve the company. | **Example requests:** ```bash cURL theme={null} curl --location 'https://api.akta.pro/api/v1/company/addition-requests/' \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data '{ "company_name": "solios", "website": "https://www.soleosenergy.com/" }' ``` ```python Python theme={null} import requests response = requests.post( "https://api.akta.pro/api/v1/company/addition-requests/", headers={ "x-api-key": "", "Content-Type": "application/json", }, json={ "company_name": "solios", "website": "https://www.soleosenergy.com/", }, ) result = response.json() if result["already_exists"]: # Company is already in the database — use its UUID directly print(f"Already exists: {result['company']['uuid']}") else: # A new addition request was created — track it to completion print(f"Addition request submitted: {result['request_id']}") ``` *** ## Response The response depends on whether the company already exists in akta.pro's database, indicated by the `already_exists` flag. ### Company already exists If the company is already in the database, **no addition request is created** — `request_id` and `status` are both `null`, and the existing company's details are returned directly in the `company` object. You can use its `uuid` straight away, with no need to track a request. ```json theme={null} { "already_exists": true, "company": { "uuid": "0002lx7", "website": "maximl.com", "name": "Maximl Labs Private Limited", "legal_name": "Maximl Labs Private Limited" }, "request_id": null, "status": null, "domain": "maximl.com", "credits_consumed": 0 } ``` ### New addition request created If the company is not yet in the database, an addition request is created. `company` is `null`, and a `request_id` and `status` are returned so you can track the request to completion. ```json theme={null} { "already_exists": false, "company": null, "request_id": "2db01b38-5c81-4b3f-b76d-8b36aeed603b", "status": "pending", "domain": "brigadegroup.com", "credits_consumed": 0.00 } ``` ### Response fields | Field | Type | Description | | ------------------ | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `already_exists` | boolean | `true` if the company is already in the database (no request created), `false` if a new addition request was created. | | `company` | object \| null | The existing company's details when `already_exists` is `true`; otherwise `null`. See **Company object** below. | | `request_id` | string (UUID) \| null | Unique identifier for the addition request. `null` when the company already exists. Use this to check request status or to match incoming webhook notifications. | | `status` | string \| null | Current status of the request at submission time (typically `"pending"`). `null` when the company already exists. See **Request statuses** below. | | `domain` | string | The resolved domain for the submitted company. | | `credits_consumed` | float | Always `0.00` — this is a free endpoint. | ### Company object Returned only when `already_exists` is `true`. | Field | Type | Description | | ------------ | ------ | ------------------------------------------------------------------------------------------------ | | `uuid` | string | Unique Akta identifier for the company. Pass this as the `company` parameter in downstream APIs. | | `website` | string | Primary website of the company. | | `domain` | string | Resolved domain of the company. | | `name` | string | Company name. | | `legal_name` | string | Legal or registered company name. | ### Request statuses | Status | Description | | ------------- | ----------------------------------------------------------------------------------------------- | | `pending` | The request has been accepted and is queued for processing. | | `in_progress` | The company is being ingested and entity-resolved. | | `completed` | The company has been added and is now available via the Company Search API and other endpoints. | | `failed` | The company could not be added. | *** ## Checking request status Once a company is submitted, track the request to completion in one of two ways. ### Option 1 — Poll the status endpoint Pass the `request_id` to the status endpoint to retrieve the current status on demand. ```text theme={null} GET https://api.akta.pro/api/v1/company/addition-requests/{request_id}/ ``` ```bash cURL theme={null} curl --location 'https://api.akta.pro/api/v1/status/3fa85f64-5717-4562-b3fc-2c963f66afa6/' \ --header 'x-api-key: ' ``` ```python Python theme={null} import requests request_id = "dac3d4f7-9171-40e4-8856-10570c886095" response = requests.get( f"https://api.akta.pro/api/v1/status/{request_id}/", headers={"x-api-key": "your-api-key"}, ) print(response.json()["status"]) ``` **Sample response** ```json theme={null} { "request_id": "dac3d4f7-9171-40e4-8856-10570c886095", "request_type": "company_addition", "status": "failed", "detail": { "company_addition_request_id": "0e0ac245-f591-4b43-b29d-a65b722c22b9", "company_name": "Lento India", "domain": "lentoindia.com", "status": "failed", "reason": null, "company_uuid": "02lko2r", "created_at": "2026-07-21T13:41:52.095899Z", "updated_at": "2026-07-21T13:46:37.096111Z" } } ``` When the request reaches `completed`, the `uuid` field is populated with the newly added company's Akta identifier, which you can then use as the `company` parameter in the Company Data, News, and other APIs. ### Option 2 — Configure a webhook Instead of polling, configure a webhook to be notified automatically when the status of an addition request changes. akta.pro will send a `POST` request to your configured endpoint each time a request transitions status (e.g. to `completed` or `failed`). Learn more about configuring webhooks [here](/webhook-config). *** ## Using the UUID in other APIs Once the addition request is `completed` and you have the company's `uuid`, pass it as the `company` parameter in downstream API calls: ```python theme={null} import requests HEADERS = {"x-api-key": ""} # Step 1: Submit the company for addition submit = requests.post( "https://api.akta.pro/api/v1/company/addition-requests/", headers={**HEADERS, "Content-Type": "application/json"}, json={"company_name": "solios", "website": "https://www.soleosenergy.com/"}, ) request_id = submit.json()["request_id"] # Step 2: Once completed (via polling or webhook), retrieve the UUID status = requests.get( f"https://api.akta.pro/api/v1/company/addition-requests/{request_id}/", headers=HEADERS, ) uuid = status.json()["uuid"] # Step 3: Use the UUID in the Company Data API enrich = requests.post( "https://api.akta.pro/api/v1/company/enrichment", headers={**HEADERS, "Content-Type": "application/json"}, json={"company": uuid, "sections": ["firmographic", "funding_details"]}, ) print(enrich.json()["data"]["firmographic"]["name"]) ```