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": {}
}

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": {}
}

Overview

Use this endpoint when you need to change an entity’s external ID. It is not possible to change externalId 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 / rows matched by entity_id), inside the same database transaction.

You must send a reason (minimum 5 characters) for compliance and audit. The change is recorded via the unified audit service (metadata includes 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.

string (uuid)

Internal gu1 entity ID. Use this when you already store our UUID.

string

Lookup only: the entity’s current external ID (not the new value). Use when you identify entities by your own ID in daily operations.

string

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.

string

required

The new external identifier (trimmed on the server). Must not be in use by another entity in the organization.

string

required

Audit reason, at least 5 characters (after trim), max 4000.

Response

boolean

true when the request completed successfully.

boolean

false if newExternalId equals the current value (no-op); true if the entity was updated.

object

Current entity snapshot after the operation.

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"
  }'

Lookup by current external ID:

{
  "externalId": "legacy_key_001",
  "newExternalId": "unified_key_001",
  "reason": "Consolidating duplicate external keys after data cleanup"
}

Lookup by tax ID:

{
  "taxId": "20-12345678-9",
  "newExternalId": "ar_person_maria_01",
  "reason": "Standardize external IDs for Argentina retail onboarding"
}

⌘I

Getting Started

SDK

Use Cases

Webhooks

Workflows

Monitoring (entities)

Person

Messaging

Company

Transactions

Devices

Events

Know Your Customer (KYC)

Payment Methods

Rules

Custom lists

Risk Matrix

Alerts

Investigations

Data Ingestion

Bulk imports

Documents

Enrichment

AML Crypto

Services

Integrations

Interactive Tutorials

Change person external ID

Overview

Endpoint

Authentication

Request Body

Response

Errors

Example

​Overview

​Endpoint

​Authentication

​Request Body

​Response

​Errors

​Example

Overview

Endpoint

Authentication

Request Body

Response

Errors

Example