# Update identifiers on preference records (/docs/api-reference/preference-record-identifiers/post-v1-preferences-update-identifiers) Batch update identifiers on preference records. This endpoint updates identifiers on preference records and does not trigger DSR workflows. Use mergeRecordsOnConflict to control merging behavior and returnIdentifiers to include identifiers in the response. ## POST /v1/preferences/{partition}/update-identifiers ```json { "servers": [ { "url": "https://multi-tenant.sombra.transcend.io", "description": "Multi-tenant (EU)" }, { "url": "https://multi-tenant.sombra.us.transcend.io", "description": "Multi-tenant (US)" }, { "description": "Self-hosted", "url": "https://_yourOrganizationSombraURL_.com" }, { "description": "Preference Store in Europe", "url": "https://consent.transcend.io" }, { "description": "Preference Store in the U.S.", "url": "https://consent.us.transcend.io" }, { "description": "Rules Automation webhook ingestion (EU)", "url": "https://rule-automation.transcend.io" }, { "description": "Rules Automation webhook ingestion (US)", "url": "https://rule-automation.us.transcend.io" } ], "security": [ { "Transcend_API_Key": [], "Sombra_Token": [], "Transcend_API_Key_If_Multitenant": [] } ], "operation": { "summary": "Update identifiers on preference records", "description": "Batch update identifiers on preference records.\nThis endpoint updates identifiers on preference records and does not trigger DSR workflows.\nUse `mergeRecordsOnConflict` to control merging behavior and `returnIdentifiers` to include identifiers in the response.\n\n**Rate Limits**\n\n- 100 requests per organization per minute (default).\n- This limit can be increased upon request.\n\n**Rate Limiting Headers**\n\n- `X-RateLimit-Limit`: The maximum number of requests allowed in the current window.\n- `X-RateLimit-Remaining`: The number of requests remaining in the current window.\n- `X-RateLimit-Reset`: The time at which the current rate limit window resets in ISO 8601 format.\n- `Retry-After`: (on 429) The number of seconds to wait before making a new request.\n\n**Transcend ID Restrictions**\n\n- Use `{ \"name\": \"transcend\", \"value\": \"\" }` as the `anchorIdentifier` to locate a preference record.\n- You cannot update the `transcend` identifier value — doing so fails with: \"The transcend identifier cannot be added, changed, or removed through this request; it is system-managed.\"", "operationId": "post-v1-preferences-update-identifiers", "parameters": [ { "$ref": "#/components/parameters/authorization" }, { "$ref": "#/components/parameters/x-sombra-authorization" }, { "$ref": "#/components/parameters/content-type-application-json" }, { "name": "partition", "in": "path", "required": true, "schema": { "type": "string", "description": "The ID of the partition in the Preference Store." } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "records" ], "properties": { "records": { "description": "List of identifier update operations to apply in a single batch. Max 10 records.", "type": "array", "maxItems": 10, "items": { "type": "object", "required": [ "anchorIdentifier", "update", "timestamp" ], "properties": { "anchorIdentifier": { "description": "The primary identifier that identifies the preference record to update.", "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "Identifier name (e.g. \"email\", \"phone\", \"transcend\")" }, "value": { "type": "string", "description": "Identifier value for locating the preference record" } } }, "update": { "description": "The identifier update operation to perform on the anchored record. Cannot update the `transcend` identifier.", "type": "object", "required": [ "name", "oldValue", "newValue" ], "properties": { "name": { "type": "string", "description": "The identifier name to update (e.g. \"phone\"). Cannot be \"transcend\"." }, "oldValue": { "type": "string", "description": "The existing identifier value that should be replaced." }, "newValue": { "type": "string", "description": "The new identifier value to set on the record." } } }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the operation was requested. This is used for auditing and bookkeeping purposes." }, "options": { "description": "Optional flags that control how the update is processed.", "type": "object", "properties": { "mergeRecordsOnConflict": { "type": "boolean", "default": true, "description": "If true, merge profiles when the `newValue` already exists on another record. If false, the operation fails on conflict." }, "returnIdentifiers": { "type": "boolean", "default": false, "description": "If true, include the record's identifiers in the response after the update. If false, the response will not include identifiers." } } } } } } } }, "examples": { "Update phone number for xyz@foo.com": { "value": { "records": [ { "anchorIdentifier": { "name": "email", "value": "xyz@foo.com" }, "update": { "name": "phone", "oldValue": "+1231231234", "newValue": "+1231231235" }, "timestamp": "2025-11-26T17:33:13.515Z" } ] } }, "Update phone number for xyz@foo.com and get full identifiers in response": { "value": { "records": [ { "anchorIdentifier": { "name": "email", "value": "xyz@foo.com" }, "update": { "name": "phone", "oldValue": "+1231231234", "newValue": "+1231231235" }, "timestamp": "2025-11-26T17:33:13.515Z", "options": { "returnIdentifiers": true } } ] } }, "Update phone number for xyz@foo.com and return error when +1231231235 already exists on another record": { "value": { "records": [ { "anchorIdentifier": { "name": "email", "value": "xyz@foo.com" }, "update": { "name": "phone", "oldValue": "+1231231234", "newValue": "+1231231235" }, "timestamp": "2025-11-26T17:33:13.515Z", "options": { "mergeRecordsOnConflict": false } } ] } }, "Batch update identifiers on multiple records": { "value": { "records": [ { "anchorIdentifier": { "name": "email", "value": "user1@example.com" }, "update": { "name": "phone", "oldValue": "+15551234567", "newValue": "+15557654321" }, "timestamp": "2025-11-26T17:33:13.515Z" }, { "anchorIdentifier": { "name": "phone", "value": "+15557654321" }, "update": { "name": "email", "oldValue": "old@example.com", "newValue": "new@example.com" }, "timestamp": "2025-11-26T17:34:00.000Z" } ] } }, "Update identifier using Transcend ID as anchor": { "value": { "records": [ { "anchorIdentifier": { "name": "transcend", "value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "update": { "name": "phone", "oldValue": "+1231231234", "newValue": "+1231231235" }, "timestamp": "2025-11-26T17:33:13.515Z" } ] } } } } } }, "security": [ { "Transcend_API_Key": [ "Modify User Stored Preferences" ] } ], "responses": { "200": { "description": "The response includes the result of each update operation in the records array, along with any partial failures in `failures` and batch failures in `errors`. Note: When the response includes failures, clients can only retry the failed items from the original request after addressing the reported errors. When the response includes errors, clients should retry the entire batch after addressing the reported errors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "records": { "description": "Per-record results for each input operation. Order matches the input `records` array.", "type": "array", "items": { "type": "object", "properties": { "identifiers": { "description": "The list of identifiers on the preference record after the update (only present when `returnIdentifiers` was true) operation is complete.", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Identifier name (e.g. \"email\", \"phone\")" }, "value": { "type": "string", "description": "Identifier value" } } } }, "success": { "type": "boolean", "description": "Whether the update operation for this record succeeded." }, "errorMessage": { "type": [ "string", "null" ], "description": "Human-readable error message when `success` is false." } } } }, "failures": { "description": "List of failed operations within the batch. Use `index` to map back to the input record.", "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number", "description": "Position of the failed record in the request `records` array." }, "error": { "type": "string", "description": "Human-readable explanation of the failure." } } } }, "errors": { "description": "Top-level errors that caused the entire batch to fail. If present, clients should retry the request.", "type": "array", "items": { "type": "string" } } } }, "examples": { "Successful batch update": { "value": { "records": [ { "success": true }, { "success": true } ], "failures": [], "errors": [] } }, "Successful update with identifiers returned": { "value": { "records": [ { "identifiers": [ { "name": "transcend", "value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, { "name": "email", "value": "user1@example.com" }, { "name": "phone", "value": "+15557654321" } ], "success": true, "errorMessage": null } ], "failures": [], "errors": [] } }, "Partial Success": { "value": { "records": [ { "success": false, "identifiers": [ { "name": "transcend", "value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, { "name": "email", "value": "user1@example.com" } ], "errorMessage": "The oldValue identifier \"+1231231234\" for identifier name \"phone\" is not linked to the preference record" }, { "identifiers": [ { "name": "transcend", "value": "b2c3d4e5-f6a7-8901-bcde-f12345678901" }, { "name": "email", "value": "xyz123@foo.com" } ], "success": true } ], "failures": [ { "index": 0, "error": "The oldValue identifier \"+1231231234\" for identifier name \"phone\" is not linked to the preference record" } ], "errors": [] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string", "description": "An error message describing the bad request." } } } } } } }, "401": { "description": "There was a problem authenticating your request. This may be an issue with the Transcend API key (\"authorization\" header), or the Sombra API key (\"x-sombra-authorization\" header used for self-hosted gateways only).", "headers": {}, "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": {} } } } }, "413": { "description": "The request body is too large. JSON and raw bodies must be less than 50MB. URL encoded bodies must be less than 30MB.", "headers": {}, "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": {} } } } }, "429": { "description": "You are sending requests too quickly and have hit our rate limit. If you hit this, you'll need to throttle your request velocity or try again later.", "headers": { "Retry-After": { "description": "The number of seconds to wait before retrying.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "The maximum number of requests allowed in the time window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the time window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "The time at which the rate limit will reset.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": {} } } } }, "500": { "description": "A 5xx error means there is either an issue with your self-hosted gateway, or a Transcend server is having issues. You check our system status at status.transcend.io. Please reach out to Transcend support if you're experiencing this error.", "headers": {}, "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": {} } } } }, "502": { "description": "An upstream service on Transcend's side is having issues. You check our system status at status.transcend.io. Please reach out to Transcend support if you're experiencing this error.", "headers": {}, "content": { "application/json": { "schema": { "description": "", "type": "object", "properties": {} } } } } }, "tags": [ "Preference record identifiers" ] } } ```