Change person external ID
curl --request POST \
--url http://api.gu1.ai/entities/change-external-id \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"entityId": {},
"externalId": "<string>",
"taxId": "<string>",
"newExternalId": "<string>",
"reason": "<string>"
}
'import requests
url = "http://api.gu1.ai/entities/change-external-id"
payload = {
"entityId": {},
"externalId": "<string>",
"taxId": "<string>",
"newExternalId": "<string>",
"reason": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
entityId: {},
externalId: '<string>',
taxId: '<string>',
newExternalId: '<string>',
reason: '<string>'
})
};
fetch('http://api.gu1.ai/entities/change-external-id', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/entities/change-external-id",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'entityId' => [
],
'externalId' => '<string>',
'taxId' => '<string>',
'newExternalId' => '<string>',
'reason' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/entities/change-external-id"
payload := strings.NewReader("{\n \"entityId\": {},\n \"externalId\": \"<string>\",\n \"taxId\": \"<string>\",\n \"newExternalId\": \"<string>\",\n \"reason\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://api.gu1.ai/entities/change-external-id")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"entityId\": {},\n \"externalId\": \"<string>\",\n \"taxId\": \"<string>\",\n \"newExternalId\": \"<string>\",\n \"reason\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities/change-external-id")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"entityId\": {},\n \"externalId\": \"<string>\",\n \"taxId\": \"<string>\",\n \"newExternalId\": \"<string>\",\n \"reason\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"changed": true,
"entity": {},
"externalIdPropagation": "<string>"
}API Reference
Change person external ID
Assign a new external identifier to a person entity in gu1 with a mandatory audit reason; denormalized transaction and user event references are updated.
POST
/
entities
/
change-external-id
Change person external ID
curl --request POST \
--url http://api.gu1.ai/entities/change-external-id \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"entityId": {},
"externalId": "<string>",
"taxId": "<string>",
"newExternalId": "<string>",
"reason": "<string>"
}
'import requests
url = "http://api.gu1.ai/entities/change-external-id"
payload = {
"entityId": {},
"externalId": "<string>",
"taxId": "<string>",
"newExternalId": "<string>",
"reason": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
entityId: {},
externalId: '<string>',
taxId: '<string>',
newExternalId: '<string>',
reason: '<string>'
})
};
fetch('http://api.gu1.ai/entities/change-external-id', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/entities/change-external-id",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'entityId' => [
],
'externalId' => '<string>',
'taxId' => '<string>',
'newExternalId' => '<string>',
'reason' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/entities/change-external-id"
payload := strings.NewReader("{\n \"entityId\": {},\n \"externalId\": \"<string>\",\n \"taxId\": \"<string>\",\n \"newExternalId\": \"<string>\",\n \"reason\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://api.gu1.ai/entities/change-external-id")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"entityId\": {},\n \"externalId\": \"<string>\",\n \"taxId\": \"<string>\",\n \"newExternalId\": \"<string>\",\n \"reason\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities/change-external-id")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"entityId\": {},\n \"externalId\": \"<string>\",\n \"taxId\": \"<string>\",\n \"newExternalId\": \"<string>\",\n \"reason\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"changed": true,
"entity": {},
"externalIdPropagation": "<string>"
}Overview
Use this endpoint when you need to change an entity’s external ID. It is not possible to changeexternalId via PATCH /entities/:id, PATCH /entities/by-external-id/:externalId, or PATCH /entities/by-tax-id/:taxId — those routes ignore any externalId in the body.
The operation:
- Validates that the new external ID is unique within your organization.
- Updates the entity row.
- When the previous external ID was non-empty and differs from the new value, rewrites denormalized references on transactions (
origin_external_id/destination_external_id) and user events (entity_external_id, including rows matched byentity_id). The entity row is saved immediately. The historical rows are updated in short batches, so a large history does not block the request.externalIdPropagationisdonewhen that rewrite finished before the response, orrunningwhile it continues. New transactions already use the new external ID. Older rows still carrying the previous ID catch up while the field isrunning.
externalIdChangeReason and source: change_external_id_endpoint).
Endpoint
POST https://api.gu1.ai/entities/change-external-id
Authentication
Authorization: Bearer YOUR_API_KEY
Request Body
Provide exactly one lookup field to identify the entity, plus the new value and reason.Lookup only: the entity’s current external ID (not the new value). Use when you identify entities by your own ID in daily operations.
Lookup only: tax ID of an entity that already has a non-empty tax ID stored. Matching uses the same alphanumeric normalization as elsewhere (ignores punctuation). If more than one entity matches, the API returns
409 with code AMBIGUOUS_TAX_ID_LOOKUP — use entityId or externalId instead.The new external identifier (trimmed on the server). Must not be in use by another entity in the organization.
Response
Present when
changed is true. done means historical transaction and user-event references already use the new external ID. running means the entity is updated and the historical rewrite is still in progress. New transactions use the new ID either way.Errors
| HTTP | Code / shape | Meaning |
|---|---|---|
| 400 | VALIDATION_ERROR, INVALID_LOOKUP | Zero or more than one lookup field, or invalid body |
| 404 | NOT_FOUND | No entity matches the lookup |
| 409 | DUPLICATE_EXTERNAL_ID | Another entity already uses newExternalId |
| 409 | AMBIGUOUS_TAX_ID_LOOKUP | Several entities share the normalized tax ID |
Example
curl -X POST "https://api.gu1.ai/entities/change-external-id" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"entityId": "550e8400-e29b-41d4-a716-446655440000",
"newExternalId": "crm_customer_8842",
"reason": "CRM migration — align ID with Salesforce Account Id"
}'
{
"externalId": "legacy_key_001",
"newExternalId": "unified_key_001",
"reason": "Consolidating duplicate external keys after data cleanup"
}
{
"taxId": "20-12345678-9",
"newExternalId": "ar_person_maria_01",
"reason": "Standardize external IDs for Argentina retail onboarding"
}
Was this page helpful?