> ## 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.

# Listar pessoas

> Consultar e filtrar pessoas em sua organização — para entidades de pessoa na plataforma KYC e análise de risco gu1, com exemplos para list.

## Visão Geral

Recupera uma lista de pessoas com filtragem opcional por país, ID fiscal ou ID externo. Retorna até 100 pessoas por requisição.

## Endpoint

```
GET http://api.gu1.ai/entities?type=person
```

## Autenticação

Requer uma chave de API válida no cabeçalho de autorização:

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

## Parâmetros de Consulta

<ParamField query="type" type="string" required>
  Deve ser definido como `person` para recuperar apenas pessoas
</ParamField>

<ParamField query="country" type="string">
  Filtrar por código de país ISO 3166-1 alpha-2 (por exemplo, "US", "BR", "AR")
</ParamField>

<ParamField query="taxId" type="string">
  Filtrar por número de identificação fiscal exato
</ParamField>

<ParamField query="externalId" type="string">
  Filtrar por seu identificador externo
</ParamField>

## Resposta

<ResponseField name="entities" type="array">
  Array de objetos pessoa, cada um contendo:

  * `id` - ID interno do gu1
  * `externalId` - Seu ID externo
  * `organizationId` - ID da sua organização
  * `type` - Sempre "person"
  * `name` - Nome da pessoa
  * `taxId` - ID fiscal
  * `countryCode` - Código do país
  * `riskScore` - Pontuação de risco (0-100)
  * `riskFactors` - Array de fatores de risco
  * `status` - Status da pessoa
  * `kycVerified` - Status de verificação KYC
  * `kycProvider` - Nome do provedor KYC
  * `kycData` - Dados de verificação KYC
  * `entityData` - Dados específicos da pessoa
  * `attributes` - Atributos personalizados
  * `createdAt` - Timestamp de criação
  * `updatedAt` - Timestamp da última atualização
  * `deletedAt` - Timestamp de exclusão (null se ativo)
</ResponseField>

## Exemplos

### Listar Todas as Pessoas

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "http://api.gu1.ai/entities?type=person" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('http://api.gu1.ai/entities?type=person', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const data = await response.json();
  console.log(`Found ${data.entities.length} persons`);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'http://api.gu1.ai/entities',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY'
      },
      params={'type': 'person'}
  )

  data = response.json()
  print(f"Found {len(data['entities'])} persons")
  ```
</CodeGroup>

### Filtrar por País

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "http://api.gu1.ai/entities?type=person&country=BR" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'http://api.gu1.ai/entities?type=person&country=BR',
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();
  console.log(`Found ${data.entities.length} Brazilian customers`);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'http://api.gu1.ai/entities',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      params={
          'type': 'person',
          'country': 'BR'
      }
  )

  brazilian_customers = response.json()['entities']
  print(f"Found {len(brazilian_customers)} Brazilian customers")
  ```
</CodeGroup>

### Buscar por ID Externo

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "http://api.gu1.ai/entities?type=person&externalId=customer_12345" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'http://api.gu1.ai/entities?type=person&externalId=customer_12345',
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();
  const person = data.entities[0]; // IDs externos devem ser únicos
  console.log('Found person:', person.name);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'http://api.gu1.ai/entities',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      params={
          'type': 'person',
          'externalId': 'customer_12345'
      }
  )

  entities = response.json()['entities']
  if entities:
      print(f"Found person: {entities[0]['name']}")
  ```
</CodeGroup>

### Buscar por ID Fiscal

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "http://api.gu1.ai/entities?type=person&taxId=20-12345678-9" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'http://api.gu1.ai/entities?type=person&taxId=20-12345678-9',
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();
  if (data.entities.length > 0) {
    console.log('Person found:', data.entities[0].name);
  }
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'http://api.gu1.ai/entities',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      params={
          'type': 'person',
          'taxId': '20-12345678-9'
      }
  )

  entities = response.json()['entities']
  if entities:
      print(f"Person found: {entities[0]['name']}")
  ```
</CodeGroup>

## Exemplo de Resposta

```json theme={null}
{
  "entities": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "externalId": "customer_12345",
      "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
      "type": "person",
      "name": "María González",
      "taxId": "20-12345678-9",
      "countryCode": "AR",
      "riskScore": 25,
      "riskFactors": [
        {
          "factor": "new_customer",
          "impact": 15,
          "description": "Customer registered within last 30 days"
        }
      ],
      "status": "active",
      "kycVerified": true,
      "kycProvider": "gueno_ai",
      "kycData": {
        "verificationDate": "2024-10-03T14:30:00Z",
        "overallStatus": "approved"
      },
      "entityData": {
        "person": {
          "firstName": "María",
          "lastName": "González",
          "dateOfBirth": "1985-03-15",
          "nationality": "AR",
          "occupation": "Software Engineer",
          "income": 85000
        }
      },
      "attributes": {
        "email": "maria.gonzalez@example.com",
        "phone": "+54 11 1234-5678"
      },
      "createdAt": "2024-10-03T14:30:00.000Z",
      "updatedAt": "2024-10-03T14:35:00.000Z",
      "deletedAt": null
    }
  ]
}
```

## Casos de Uso

### Monitoramento de Clientes de Alto Risco

Consultar todas as pessoas e filtrar por pontuação de risco:

```javascript theme={null}
const response = await fetch('http://api.gu1.ai/entities?type=person', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

const data = await response.json();
const highRiskCustomers = data.entities.filter(e => e.riskScore > 70);

console.log(`Found ${highRiskCustomers.length} high-risk customers requiring review`);
highRiskCustomers.forEach(person => {
  console.log(`- ${person.name} (Risk: ${person.riskScore})`);
});
```

### Painel de Conformidade KYC

Obter todos os clientes não verificados para o painel de conformidade:

```python theme={null}
import requests

response = requests.get(
    'http://api.gu1.ai/entities',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'type': 'person'}
)

persons = response.json()['entities']
unverified = [p for p in persons if not p['kycVerified']]

print(f"Unverified customers: {len(unverified)}")
for person in unverified:
    print(f"- {person['name']} ({person['externalId']})")
```

## Respostas de Erro

### 401 Unauthorized

```json theme={null}
{
  "error": "Invalid or missing API key"
}
```

### 500 Internal Server Error

```json theme={null}
{
  "error": "Failed to search entities"
}
```

## Limites

* **Máximo de resultados por requisição**: 100 pessoas
* **Parâmetros de consulta**: Podem ser combinados para filtragem avançada
* **Limites de taxa**: Aplicam-se com base no seu nível de plano

## Próximos Passos

* [Obter Detalhes da Pessoa](/pt/api-reference/person/get) - Recuperar informações completas de uma pessoa específica
* [Criar Pessoa](/pt/api-reference/person/create) - Adicionar novas pessoas à sua organização
* [Atualizar Pessoa](/pt/api-reference/person/update) - Modificar atributos da pessoa