> ## Documentation Index > Fetch the complete documentation index at: https://docs.salescaptain.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a new tag > Creates a new tag for a specific company. `status` is optional and defaults to `true`. User must have 'contacts' access role to create tags. `account_id` is derived from the authenticated user's account for the company. ## OpenAPI ````yaml POST /v1/create-tag openapi: 3.0.3 info: title: SalesCaptain API Documentation Service description: > API Documentation Service for SalesCaptain platform. This service provides endpoints for managing and retrieving company information for API documentation purposes. version: 0.1.0 contact: name: SalesCaptain API Team email: support@salescaptain.com license: name: Proprietary url: https://salescaptain.com/license servers: - url: https://api.salescaptain.com description: Production server security: - BearerAuth: [] tags: - name: Health description: Service health and status endpoints - name: Companies description: Company management and retrieval operations - name: Accounts description: Account management and retrieval operations - name: Conversation Profiles description: Conversation profile management for communication channels - name: Conversations description: Conversation management and retrieval operations - name: Contacts description: Contact management and retrieval operations - name: Tags description: Tag listing, creation, deletion, and contact assignment operations - name: Custom Fields description: Custom field definition management - name: Templates description: SMS template retrieval operations - name: Analytics description: Call analytics and reporting operations externalDocs: description: SalesCaptain API Documentation url: https://docs.salescaptain.com paths: /v1/create-tag: post: tags: - Tags summary: Create a new tag description: > Creates a new tag for a specific company. `status` is optional and defaults to `true`. User must have 'contacts' access role to create tags. `account_id` is derived from the authenticated user's account for the company. operationId: createTag requestBody: required: true content: application/json: schema: type: object properties: company_id: type: string format: uuid description: Unique identifier for the company example: 7f22b96a-f75b-461e-9a1d-b8ff6f53f519 tag_name: type: string description: Display name of the tag example: VIP Customer status: type: boolean description: Whether the tag is active (defaults to true) default: true example: true required: - company_id - tag_name examples: with_status: summary: Create tag with explicit status value: company_id: 7f22b96a-f75b-461e-9a1d-b8ff6f53f519 tag_name: VIP Customer status: true default_status: summary: Create tag with default status value: company_id: 7f22b96a-f75b-461e-9a1d-b8ff6f53f519 tag_name: VIP Customer responses: '201': description: Tag created successfully content: application/json: schema: type: object properties: message: type: string example: Tag created successfully! tag: type: object properties: data: $ref: '#/components/schemas/TagCreated' example: message: Tag created successfully! tag: data: tag_id: c9d8e7f6-a5b4-3210-9876-543210fedcba company_id: 7f22b96a-f75b-461e-9a1d-b8ff6f53f519 tag_name: VIP Customer status: true created_at: '2026-08-11T12:26:00.000Z' message: Tag created successfully '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing_company_id: summary: Missing company_id value: status: failure error: company_id is required missing_tag_name: summary: Missing tag_name value: status: failure error: tag_name is required invalid_status: summary: Invalid status value: status: failure error: status must be a boolean '401': $ref: '#/components/responses/UnauthorizedError' '403': description: Access forbidden or permission denied content: application/json: schema: $ref: '#/components/schemas/Error' example: status: failure error: You don't have permission to create tag! '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/InternalServerError' security: - BearerAuth: [] components: schemas: TagCreated: type: object description: Created tag response object properties: tag_id: type: string format: uuid description: Unique identifier for the tag example: c9d8e7f6-a5b4-3210-9876-543210fedcba company_id: type: string format: uuid description: Unique identifier for the company example: 7f22b96a-f75b-461e-9a1d-b8ff6f53f519 tag_name: type: string description: Display name of the tag example: VIP Customer status: type: boolean description: Whether the tag is active example: true created_at: type: string format: date-time description: Timestamp when the tag was created example: '2026-08-11T12:26:00.000Z' message: type: string description: Success message from the create operation example: Tag created successfully required: - tag_id - company_id - tag_name - status - created_at Error: type: object description: Error response object properties: error: type: string description: Error message example: Invalid request parameters code: type: string description: Error code for programmatic handling example: INVALID_PARAMS timestamp: type: string format: date-time description: Timestamp when the error occurred example: '2023-12-01T10:30:00Z' path: type: string description: API endpoint path where the error occurred example: /v1/fetch-companies required: - error responses: UnauthorizedError: description: Authentication token is missing or invalid content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Unauthorized access code: UNAUTHORIZED timestamp: '2023-12-01T10:30:00Z' path: /v1/fetch-companies RateLimitError: description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Too many requests, please try again later code: RATE_LIMIT_EXCEEDED timestamp: '2023-12-01T10:30:00Z' path: /v1/fetch-companies headers: X-RateLimit-Limit: description: Request limit per time window schema: type: integer example: 30 X-RateLimit-Remaining: description: Remaining requests in current window schema: type: integer example: 0 X-RateLimit-Reset: description: Time when the rate limit resets schema: type: integer example: 1701425400 InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Problem encountered while fetching companies! code: INTERNAL_ERROR timestamp: '2023-12-01T10:30:00Z' path: /v1/fetch-companies securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Authentication token required for accessing protected endpoints. The token should be obtained from the main SalesCaptain authentication service. ````