Skip to main content
PATCH
/
entities
/
{id}
/
country-activations
/
{countryCode}
Update entity country activation
curl --request PATCH \
  --url http://api.gu1.ai/entities/{id}/country-activations/{countryCode} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "<string>"
}
'

​
Overview

Sets the operational activation status for one country on a merchant entity. This does not modify entity profile data — use GET /entities/{id} to re-fetch the dossier after activation. On every real status change, Gu1 emits the entity.country_activation_changed webhook to subscribed endpoints. Transitions between statuses are free-form (any status may move to any other). Supported countryCode values: AR, BR, CL, CO, MX, US (case-insensitive).

​
Endpoint

PATCH http://api.gu1.ai/entities/{id}/country-activations/{countryCode}

​
Authentication

Requires entities:edit (legacy fallback: entities:write). 
Authorization: Bearer YOUR_API_KEY

​
Path Parameters

​
id
string
required
UUID of the entity (merchant).
​
countryCode
string
required
ISO 3166-1 alpha-2 country to update (AR, BR, CL, CO, MX, US).

​
Request Body

​
status
string
required
One of: deactivated, activation_requested, activation_in_progress, activated.

​
Response

FieldTypeDescription
data.entityIdstringEntity UUID
data.countryCodestringNormalized country code
data.statusstringNew status
data.previousStatusstringStatus before this call
data.changedbooleanfalse if status was already the requested value (no webhook)
data.activatedAtstring | nullLast activated timestamp
data.deactivatedAtstring | nullLast deactivated timestamp
data.updatedAtstring | nullLast change timestamp
data.countriesarrayFull snapshot of all allowlist countries after this call

​
Example

curl -X PATCH "https://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000/country-activations/CO" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"activation_requested"}'

{
  "success": true,
  "data": {
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "countryCode": "CO",
    "status": "activation_requested",
    "previousStatus": "deactivated",
    "changed": true,
    "activatedAt": null,
    "deactivatedAt": null,
    "updatedAt": "2026-07-03T15:00:00.000Z",
    "countries": [
      { "countryCode": "AR", "status": "deactivated", "activatedAt": null, "deactivatedAt": null, "updatedAt": null },
      { "countryCode": "CO", "status": "activation_requested", "activatedAt": null, "deactivatedAt": null, "updatedAt": "2026-07-03T15:00:00.000Z" },
      { "countryCode": "MX", "status": "activated", "activatedAt": "2026-07-03T14:00:00.000Z", "deactivatedAt": null, "updatedAt": "2026-07-03T14:00:00.000Z" }
    ]
  }
}

​
Webhook payload (on change)

When changed is true, subscribers receive: 
{
  "event": "entity.country_activation_changed",
  "timestamp": "2026-07-03T15:00:00.000Z",
  "organizationId": "org-uuid",
  "payload": {
    "entity": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "externalId": "merchant_123",
      "name": "Acme Corp",
      "type": "company",
      "countryCode": "US"
    },
    "countryCode": "CO",
    "status": "activation_requested",
    "previousStatus": "deactivated",
    "activeCountryCodes": ["MX"],
    "countries": [
      { "countryCode": "AR", "status": "deactivated" },
      { "countryCode": "CO", "status": "activation_requested" },
      { "countryCode": "MX", "status": "activated" }
    ],
    "timeline": [
      {
        "previousStatus": "deactivated",
        "status": "activation_requested",
        "changedAt": "2026-07-03T15:00:00.000Z"
      }
    ],
    "changedAt": "2026-07-03T15:00:00.000Z"
  }
}

​
Errors

HTTPCodeWhen
400UNSUPPORTED_COUNTRY_CODECountry not in v1 allowlist
404ENTITY_NOT_FOUNDEntity does not exist in the current organization