> ## Documentation Index > Fetch the complete documentation index at: https://docs.layerfi.com/llms.txt > Use this file to discover all available pages before exploring further. # Merge tag values > Merges one or more (source) tag values into another (target) tag value. This operation is used to merge one or more **source** tag values into a single **target** tag value. Upon merging, all taggable entities that are tagged with the source tag values are re-tagged to the target tag value, and all source tag values are archived after the merge. All tag values being operated on must be unarchived and belong to the same tag dimension. **Source tag values** → The tag values that will be replaced and archived after the operation. **Target tag value** → The tag value that will replace all source tag values. The target tag value must already exist before calling the merge operation. ## Example 1. Taggable entity `A` is tagged with tag value `1`. 2. Taggable entity `B` is tagged with tag value `2`. 3. Tag value `3` is created. 4. **Merge Operation:** Source tag values `1` and `2` are merged into target tag value `3`. The endpoint returns the target tag value `3`. 5. Taggable entity `A` and taggable entity `B` are now tagged with `3` and no longer have tag values `1` and `2`. 6. Tag values `1` and `2` are now archived. ## Use-cases Bulk deduplication or consolidation of tag values. * Example deduplication: `Location: san francisco` & `Location: SF` → `Location: San Francisco`. * Example consolidation: `Location: San Francisco` & `Location: San Jose` → `Location: Bay Area`. ## OpenAPI ````yaml post /v1/businesses/{businessId}/tags/values/{targetValueId}/merge openapi: 3.0.1 info: title: API version: latest servers: [] security: - BearerAuth: [] tags: [] externalDocs: url: / paths: /v1/businesses/{businessId}/tags/values/{targetValueId}/merge: post: tags: [] summary: Merge tag values description: Merges one or more (source) tag values into another (target) tag value. operationId: business.tags.values.value.merge.post parameters: - name: businessId in: path description: The UUID of the business. required: true schema: type: string format: uuid - name: targetValueId in: path description: The UUID of the tag value to merge into. required: true schema: type: string format: uuid - name: Content-Type in: header description: Content-Type must be set to application/json. schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/MergeTagValuesParams' responses: '200': description: Tag values merged successfully. Returns the target tag value. headers: {} content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/ApiTagValueDefinition' required: - data '400': description: >- Invalid request parameters. Returned when no source tag values are provided, a tag value is merged into itself, the source tagvalues and target belong to different tag dimensions, or the target or any source tagvalue is already archived. content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': description: >- Business not found, the target tag value does not exist, or one or more source tag values were not found. content: application/json: schema: $ref: '#/components/schemas/ApiError' deprecated: false components: schemas: MergeTagValuesParams: type: object properties: source_value_ids: type: array items: type: string format: uuid minItems: 1 description: >- UUIDs of the source tag value definitions to merge into the target. At least one source tag value UUID is required. All source tag values are archived after the merge, and all objects tagged with it are re-tagged to the target value. Source tag values must belong to the same tag dimension as the target. required: - source_value_ids ApiTagValueDefinition: type: object properties: type: type: string description: Resource type. Value will be `TagValue`. example: TagValue id: type: string format: uuid description: Unique identifier for the tag value definition. key: type: string description: The tag dimension key. value: type: string description: The tag value. display_name: type: string nullable: true description: Optional display name for the tag value definition. archived_at: type: string format: date-time nullable: true description: Timestamp when the tag value definition was archived. required: - id - key - value ApiError: type: object description: An error object returned in API error responses. properties: type: $ref: '#/components/schemas/ApiErrorType' description: >- A fixed category for the error, helpful for categorizing and processing errors. description: type: string description: A human-readable error description. error_enum: $ref: '#/components/schemas/ApiEnumErrorType' description: >- A stable, machine-readable identifier for programmatically handling specific error conditions. Only present for 4xx client errors—not included for 5xx server errors. Use this instead of parsing the description field, as enum values remain stable across API versions. nullable: true meta: type: object description: Optional additional information about the error. nullable: true required: - type - description ApiErrorType: type: string enum: - ResourceArchived - AuthFailure - Plaid - Stripe - InvalidState - ResourceNotFound - InvalidParameters - JsonSerialization - Unknown - BadRequest - PaginationCursor - Conflict - LedgerOperationFailed ApiEnumErrorType: type: string description: >- Stable enum values for programmatic error handling. Only present in 4xx error responses. enum: - AccessCodeInvalid - BalanceSheetDoesNotBalance - BalanceSheetMissingAccount - BankStatementParserError - BillStateError - BulkCategorizeFailure - BulkMatchFailure - BusinessTaskAlreadyCompleted - BusinessTaskDeleted - CalendlyOAuthError - CallBookingError - CantUpdateTransactionInCustomerPayout - CantUpdateTransactionInVendorPayout - CheckPayrollConfigNotFound - CheckPayrollServiceNotFound - ClerkUserAlreadyExists - ConflictingQueryParams - CustomAccountAlreadyExists - CustomTransactionCsvParsingError - CustomTransactionUploadFailure - CustomerPayoutInputFormatError - DoesNotMatchExistingEntity - EmptyBatchRequest - ExpenseParserError - ExternalAccountBalanceReconciliationError - ExternalIdConflict - InvalidCategory - InvalidEffectiveDate - InvalidLedgerOperation - InvalidMonthlyAverageRange - InvalidMultiPartRequest - InvalidPaginationCursor - InvalidPayload - InvoiceDeleted - InvoiceNotFound - InvoiceReferenceMismatch - InvoiceStateError - ManualRateLimit - MultipleTagKeyFiltersUnsupported - NoCognitoUserFound - NoOpeningBalanceFound - NotYetReconciled - OnePasswordApiError - OnePasswordItemNotFound - OnePasswordVaultNotFound - OpenAICategorizationError - PaymentLinkInvalid - PayrollStateError - PeriodIsClosed - PeriodNotClosed - PhoneNumberAlreadyRegistered - PlaidApiError - PlaidConnectionBroken - PlaidCreateLinkTokenError - PlaidCredentialsNotConfigured - PlaidExchangePublicTokenError - PlaidGetInstitutionByIdError - PlaidGetItemError - PlaidInvalidEnvironment - PlaidItemAlreadyExists - PlaidItemNotFound - PlaidProcessorApiError - PlaidUnlinkItemError - QueryParamFormat - QueryParamMissing - QuickbooksBrokenConnection - QuickbooksConnectionAlreadyExists - QuickbooksConnectionAlreadySyncing - QuickbooksConnectionMissing - QuickbooksConnectionNotActivated - QuickbooksInvalidRequest - QuickbooksInvalidState - QuickbooksNoMatchingAccount - QuickbooksNonPostingAccountType - QuickbooksNotConfigured - QuickbooksOAuthCallbackInvalid - QuickbooksOAuthError - QuickbooksTokenExpired - ResourceArchived - ScheduleCNotConfigured - SmsNotEnabled - SpecifiedBadRequest - SpecifiedIdNotFound - SplitTransactionError - StepEvaluationBadRequest - StripeConnectAccountIdNotFound - StripeCredentialsNotConfigured - StripeGetBalanceForConnectAccountFailure - StripeRedirectOrRefreshUrlNotConfigured - TagFilterNotFound - UnexpectedQueryParam - UnitAccountsInUse - WrongAnswerType securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT ````