# Append identifiers on preference records (/docs/api-reference/preference-record-identifiers/post-v1-preferences-append-identifiers) Append a single identifier to each provided preference record. This endpoint appends identifiers on preference records and does not trigger DSR workflows. Set returnIdentifiers to include remaining identifiers in the response. ## POST /v1/preferences/{partition}/append-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": "Append identifiers on preference records", "description": "Append a single identifier to each provided preference record.\nThis endpoint appends identifiers on preference records and does not trigger DSR workflows.\nSet `returnIdentifiers` to include remaining 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 append a `transcend` identifier — doing so fails with: \"The transcend identifier cannot be added, changed, or removed through this request; it is system-managed.\"", "operationId": "post-v1-preferences-append-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": { "type": "array", "description": "List of append operations to perform. Max 10 records.", "maxItems": 10, "items": { "type": "object", "required": [ "anchorIdentifier", "append", "timestamp" ], "properties": { "anchorIdentifier": { "description": "The primary identifier that specifies the preference record to which the new entry will be appended.", "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "The anchor identifier name (e.g., \"email\", \"phone\", \"transcend\")" }, "value": { "type": "string", "description": "The anchor identifier value" } } }, "append": { "type": "object", "required": [ "name", "value" ], "description": "The identifier to append to the preference record specified by the anchorIdentifier. Cannot be a `transcend` identifier.", "properties": { "name": { "type": "string", "description": "The identifier name to append (e.g., \"email\", \"phone\"). Cannot be \"transcend\"." }, "value": { "type": "string", "description": "The identifier value to append" } } }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the operation was requested. This is used for auditing and bookkeeping purposes." }, "options": { "type": "object", "description": "Options controlling how the server processes the append", "properties": { "mergeRecordsOnConflict": { "type": "boolean", "default": true, "description": "When false, raise an error if the identifier to append already exists on a different preference record." }, "returnIdentifiers": { "type": "boolean", "default": false, "description": "When true, include the preference record identifiers in the response. When false, identifiers are omitted from the response." } } } } } } } }, "examples": { "Append Identifiers Example": { "value": { "records": [ { "anchorIdentifier": { "name": "email", "value": "xyz@foo.com" }, "append": { "name": "phone", "value": "+1231231234" }, "timestamp": "2024-06-01T12:00:00Z" } ] } }, "Append Identifier with Merging Disabled": { "value": { "records": [ { "anchorIdentifier": { "name": "email", "value": "xyz@foo.com" }, "append": { "name": "phone", "value": "+1231231234" }, "timestamp": "2024-06-01T12:00:00Z", "options": { "mergeRecordsOnConflict": false } } ] } }, "Append Identifier with `returnIdentifiers` Enabled": { "value": { "records": [ { "anchorIdentifier": { "name": "email", "value": "xyz@foo.com" }, "append": { "name": "phone", "value": "+1231231234" }, "timestamp": "2024-06-01T12:00:00Z", "options": { "returnIdentifiers": true } } ] } }, "Batch Append identifiers on Multiple Records": { "value": { "records": [ { "anchorIdentifier": { "name": "email", "value": "xyz@foo.com" }, "append": { "name": "phone", "value": "+1231231234" }, "timestamp": "2024-06-01T12:00:00Z", "options": { "returnIdentifiers": true } }, { "anchorIdentifier": { "name": "email", "value": "abc@foo.com" }, "append": { "name": "phone", "value": "+1231231235" }, "timestamp": "2024-06-01T12:00:00Z", "options": { "returnIdentifiers": true } } ] } }, "Append identifier using Transcend ID as anchor": { "value": { "records": [ { "anchorIdentifier": { "name": "transcend", "value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "append": { "name": "phone", "value": "+1231231234" }, "timestamp": "2024-06-01T12:00:00Z" } ] } } } } } }, "security": [ { "Transcend_API_Key": [ "Modify User Stored Preferences" ] } ], "responses": { "200": { "description": "The result of the append operation for each record. Each record indicates whether the append succeeded or failed, along with any relevant error messages or identifiers. 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 order of the input records.", "type": "array", "items": { "type": "object", "properties": { "identifiers": { "type": "array", "description": "The list of all identifiers for the preference record. Included only when request `options.returnIdentifiers` is true.", "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "The identifier name (e.g., \"email\", \"phone\")" }, "value": { "type": "string", "description": "The identifier value" } } } }, "success": { "type": "boolean", "description": "Whether the append operation succeeded for this record." }, "errorMessage": { "type": "string", "description": "When `success` is false, contains a human-readable error explaining why the append failed." } } } }, "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 input 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 entire request.", "type": "array", "items": { "type": "string" } } } }, "examples": { "Successful Append": { "value": { "records": [ { "success": true } ], "failures": [], "errors": [] } }, "Successful Append with Identifiers": { "value": { "records": [ { "identifiers": [ { "name": "transcend", "value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, { "name": "email", "value": "xyz123@foo.com" }, { "name": "phone", "value": "+1231231234" } ], "success": true } ], "failures": [], "errors": [] } }, "Partial Success": { "value": { "records": [ { "success": true }, { "success": false, "errorMessage": "+1231231234 is already associated to a different preference record" } ], "failures": [ { "index": 1, "error": "+1231231234 is already associated to a different 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" ] } } ```