> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List entity country activations

> Read per-merchant country activation flags (AR, BR, CL, CO, MX, US). Missing rows are returned as deactivated.

## Overview

Returns the operational country activation state for a merchant entity. This is an **operational flag only** — it does not change entity data, enrichments, or compliance status. Integrators typically re-fetch the full entity after receiving the [`entity.country_activation_changed`](/en/webhooks/events/entity-events) webhook.

Supported countries (v1): **AR**, **BR**, **CL**, **CO**, **MX**, **US**.

When no row exists for a country, the API returns `deactivated` (opt-in model).

## Endpoint

```
GET http://api.gu1.ai/entities/{id}/country-activations
```

## Authentication

Requires `entities:read` (legacy fallback: `entities:read` / viewer role).

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Path Parameters

<ParamField path="id" type="string" required>
  UUID of the entity (merchant).
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the request succeeded.
</ResponseField>

<ResponseField name="data.entityId" type="string">
  Entity UUID.
</ResponseField>

<ResponseField name="data.countries" type="array">
  Fixed list of six countries with activation metadata.
</ResponseField>

Each item in `data.countries`:

| Field           | Type           | Description                                                                     |
| --------------- | -------------- | ------------------------------------------------------------------------------- |
| `countryCode`   | string         | ISO 3166-1 alpha-2 (`AR`, `BR`, `CL`, `CO`, `MX`, `US`)                         |
| `status`        | string         | `deactivated`, `activation_requested`, `activation_in_progress`, or `activated` |
| `activatedAt`   | string \| null | ISO timestamp when last reached `activated`                                     |
| `deactivatedAt` | string \| null | ISO timestamp when last reached `deactivated`                                   |
| `updatedAt`     | string \| null | ISO timestamp of last status change (`null` if never set)                       |

## Example

```bash theme={null}
curl -X GET "https://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000/country-activations" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

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

## Errors

| HTTP | Code               | When                                              |
| ---- | ------------------ | ------------------------------------------------- |
| 404  | `ENTITY_NOT_FOUND` | Entity does not exist in the current organization |