> ## Documentation Index > Fetch the complete documentation index at: https://help.withallo.com/llms.txt > Use this file to discover all available pages before exploring further. # Create company attribute > Creates a custom attribute on your team's companies. The key is derived from the label. The call is idempotent: if an attribute with the same key and type already exists, it returns `201` with that attribute and `already_existed` set to `true`. `options` is required for `DROPDOWN` attributes and rejected for other types. **Required scope:** `CRM_WRITE` ## Body fields | Field | Type | Required | Description | | - | - | - | - | | `label` | string | yes | Display name, 1 to 255 characters, with at least one letter or digit | | `type` | string | yes | `TEXT`, `NUMBER`, `DATE`, `BOOLEAN` or `DROPDOWN` | | `options` | array | `DROPDOWN` only | At least one `{ label, key? }` object. Rejected for other types | | `prompt` | string | no | Instruction the AI CRM Manager follows to fill this attribute from calls | | `should_prompt_override` | boolean | no | Whether the AI may overwrite a value that is already set | ## Key derivation The `key` is derived from the label: lowercase, accents removed, runs of non-alphanumeric characters replaced by `_`, truncated to 64 characters. `Industry segment` becomes `industry_segment`. Option keys are derived the same way. A label that resolves to a reserved key is rejected with `ATTRIBUTE_KEY_RESERVED`. The reserved keys are: `id`, `name`, `phone_numbers`, `website`, `industry`, `logo_url`, `last_activity`, `activity_history`, `sms_content`, `created_at` and `updated_at`. ## Response Returns `201` with the created attribute. `source` is `allo`, and `already_existed` is `false`. ```json theme={null} { "data": { "key": "industry_segment", "label": "Industry segment", "type": "DROPDOWN", "options": [ { "key": "smb", "label": "SMB" }, { "key": "enterprise", "label": "Enterprise" } ], "is_visible": true, "prompt": "Pick the segment that matches the company size mentioned on the call.", "should_prompt_override": false, "source": "allo", "created_at": "2026-10-07T14:21:08", "updated_at": "2026-10-07T14:21:08", "already_existed": false } } ``` ## Creating the same attribute twice The call is safe to repeat. If an attribute with the same key and type already exists, the endpoint returns `201` with that attribute and `already_existed` set to `true`. Nothing is created and the existing definition is left unchanged. If the key exists with a different type, the request returns `409 ATTRIBUTE_KEY_CONFLICT`. ## Limits Each type has a fixed number of slots per team. Once a type is full, creating another attribute of that type returns `409 ATTRIBUTE_SLOTS_EXHAUSTED`. Delete an unused attribute or use another type. Custom attributes are only available to teams on the new contact model. Other teams get `404 TEAM_NOT_FOUND`. ## Errors | Status | Code | When | | - | - | - | | `400` | `ATTRIBUTE_LABEL_INVALID` | `label` is blank, longer than 255 characters, or has no letter or digit | | `400` | `ATTRIBUTE_KEY_RESERVED` | The label resolves to a reserved key | | `400` | `ATTRIBUTE_OPTION_INVALID` | A `DROPDOWN` attribute has no options, or an option label is blank, longer than 255 characters or duplicated | | `400` | `ATTRIBUTE_OPTIONS_NOT_SUPPORTED` | `options` sent for a type other than `DROPDOWN` | | `400` | `INVALID_REQUEST_BODY` | `type` is missing or unknown | | `403` | `API_KEY_INSUFFICIENT_SCOPE` | The key does not hold `CRM_WRITE` | | `404` | `TEAM_NOT_FOUND` | The workspace is not on the new contact model | | `409` | `ATTRIBUTE_KEY_CONFLICT` | An attribute with this key already exists with another type | | `409` | `ATTRIBUTE_SLOTS_EXHAUSTED` | No free slot is left for this type | | `409` | `ATTRIBUTE_CONCURRENT_MODIFICATION` | Attributes were modified at the same time. Retry the request | ## OpenAPI ````yaml POST /v2/api/crm/companies/attributes openapi: 3.0.3 info: title: Allo API description: >- Allo API provides programmatic access to your Allo account, allowing you to manage webhooks, retrieve calls and contacts, and send SMS messages. All requests to `/v1/api/**` endpoints automatically go through quota checking and scope validation. version: 1.0.0 contact: name: Allo Support servers: - url: https://api.withallo.com description: Production server security: [] tags: - name: Summary Templates description: >- Manage call summary templates that control how AI-generated call summaries are structured for your team. - name: Webhooks description: >- Manage webhook endpoints to receive real-time notifications about events in your Allo account. Each endpoint subscribes to one or more event topics and is verified with a signing secret. - name: Calls description: >- Retrieve and search call records with filtering and pagination. Filter calls by your Allo phone number. - name: Contacts description: >- Search and retrieve contact information with sorting and pagination. Includes engagement level tracking. - name: SMS description: Send SMS messages to phone numbers using your Allo numbers. - name: Phone Numbers description: Retrieve information about your Allo phone numbers. - name: Analytics description: Pre-computed call metrics, team performance, and outbound dial funnel - name: CRM description: Manage people, companies, and deals in your CRM. - name: Notes description: >- Internal team notes on conversations and CRM people, with @mention support. Notes are never visible to the contact. - name: Threads description: >- Team discussion threads attached to a conversation item (call, SMS, or conversation note). One thread per item. - name: AI Receptionist description: >- Read and write the AI receptionist configuration of a phone line: business details, voice, prompt, capabilities, business hours, transfer rules, scheduling calendars and knowledge sources. paths: /v2/api/crm/companies/attributes: post: tags: - CRM summary: Create custom company attribute description: >- Creates a custom attribute on your team's companies. The key is derived from the label. The call is idempotent: if an attribute with the same key and type already exists, it returns `201` with that attribute and `already_existed` set to `true`. `options` is required for `DROPDOWN` attributes and rejected for other types. operationId: createCompanyAttribute requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCompanyAttributeRequest' example: label: Industry segment type: DROPDOWN options: - label: SMB - label: Enterprise prompt: >- Pick the segment that matches the company size mentioned on the call. responses: '201': description: >- The attribute that was created, or the existing one when `already_existed` is `true` content: application/json: schema: type: object properties: data: allOf: - $ref: '#/components/schemas/CompanyAttribute' - type: object properties: already_existed: type: boolean description: >- `true` when an attribute with the same key and type already existed and nothing was created example: data: key: industry_segment label: Industry segment type: DROPDOWN options: - key: smb label: SMB - key: enterprise label: Enterprise is_visible: true prompt: >- Pick the segment that matches the company size mentioned on the call. should_prompt_override: false source: allo created_at: '2026-10-07T14:21:08' updated_at: '2026-10-07T14:21:08' already_existed: false '400': $ref: '#/components/responses/ApiValidationError' '401': $ref: '#/components/responses/ApiUnauthorized' '403': $ref: '#/components/responses/ApiForbidden' '404': $ref: '#/components/responses/ApiNotFound' '409': $ref: '#/components/responses/ApiConflict' '429': $ref: '#/components/responses/ApiRateLimited' security: - ApiKeyAuth: [] components: schemas: CreateCompanyAttributeRequest: type: object required: - label - type properties: label: type: string description: >- Display name of the attribute. The attribute key is derived from it: lowercase, accents removed, runs of non-alphanumeric characters replaced by `_`, truncated to 64 characters. Labels that resolve to a reserved key are rejected. example: Industry segment type: type: string enum: - TEXT - NUMBER - DATE - BOOLEAN - DROPDOWN example: DROPDOWN options: type: array description: >- Allowed values. Required, with at least one option, for `DROPDOWN`; rejected for other types. items: $ref: '#/components/schemas/CompanyAttributeOptionInput' prompt: type: string nullable: true description: >- Instruction the AI CRM Manager follows to fill this attribute from calls. A blank value clears it. example: >- Pick the segment that matches the company size mentioned on the call. should_prompt_override: type: boolean description: Whether the AI may overwrite a value that is already set CompanyAttribute: type: object description: A custom attribute on companies properties: key: type: string description: Unique key within your team example: industry_segment label: type: string nullable: true description: Display name example: Industry segment type: type: string nullable: true enum: - TEXT - NUMBER - DATE - BOOLEAN - DROPDOWN example: DROPDOWN options: type: array nullable: true description: Allowed values. Only set for `DROPDOWN` attributes. items: $ref: '#/components/schemas/CompanyAttributeOption' is_visible: type: boolean description: Whether the attribute is shown in the Allo apps prompt: type: string nullable: true description: >- Instruction the AI CRM Manager follows to fill this attribute from calls. A blank value clears it. example: >- Pick the segment that matches the company size mentioned on the call. should_prompt_override: type: boolean description: Whether the AI may overwrite a value that is already set nullable: true source: type: string description: >- `allo` for attributes created in Allo or with the API, otherwise the lowercase name of the integration that manages it, such as `hubspot` example: allo created_at: type: string format: date-time updated_at: type: string format: date-time CompanyAttributeOptionInput: type: object required: - label properties: label: type: string description: Display name of the option example: Enterprise key: type: string description: >- Existing option key. Send it when editing an attribute to keep the option's key stable while its label changes. Keys that do not match an existing option are ignored and a key is derived from the label. example: enterprise CompanyAttributeOption: type: object properties: key: type: string example: enterprise label: type: string example: Enterprise ApiError: type: object properties: error: type: object properties: type: type: string code: type: string message: type: string retryable: type: boolean request_id: type: string retry_after_seconds: type: integer nullable: true responses: ApiValidationError: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ApiError' ApiUnauthorized: description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ApiError' ApiForbidden: description: API key lacks the required scope or access to the resource content: application/json: schema: $ref: '#/components/schemas/ApiError' ApiNotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ApiError' ApiConflict: description: Conflict with existing resource content: application/json: schema: $ref: '#/components/schemas/ApiError' ApiRateLimited: description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ApiError' securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.