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

# Listar empresas

> Retorna uma lista paginada de empresas da organização.

## Endpoint

```
GET /v1/companies
```

**Escopo necessário:** `read:companies`

## Parâmetros de query

| Parâmetro     | Tipo    | Descrição                                                        |
| ------------- | ------- | ---------------------------------------------------------------- |
| `limit`       | integer | Itens por página. Padrão: `25`. Máximo: `100`                    |
| `cursor`      | string  | Token de paginação                                               |
| `search`      | string  | Busca por nome, email ou telefone                                |
| `tag`         | string  | Filtra por tag exata                                             |
| `sector`      | string  | Filtra por setor (busca parcial, case-insensitive)               |
| `size`        | string  | Filtra por tamanho: `1-10`, `11-50`, `51-200`, `201-500`, `500+` |
| `assigned_to` | string  | ID do membro responsável                                         |

## Exemplo de requisição

```bash theme={null}
curl "https://api.socialsell.ai/v1/companies?sector=tecnologia&size=51-200" \
  -H "Authorization: Bearer sk_live_..."
```

## Exemplo de resposta

```json theme={null}
{
  "data": [
    {
      "id": "664b1c2d3e4f5a6789012346",
      "name": "Empresa ABC Ltda",
      "email": "contato@empresaabc.com.br",
      "phone": "+5511333344445",
      "website": "https://empresaabc.com.br",
      "sector": "Tecnologia",
      "size": "51-200",
      "city": "São Paulo",
      "state": "SP",
      "assigned_to": {
        "id": "664a1b2c3d4e5f6789012345",
        "name": "Maria Santos"
      },
      "tags": ["parceiro", "tech"],
      "custom_fields": {},
      "contacts_count": 8,
      "deals_count": 3,
      "total_deals_value": 45000,
      "created_at": "2026-01-10T09:00:00.000Z",
      "updated_at": "2026-05-20T11:30:00.000Z"
    }
  ],
  "meta": {
    "total": 87,
    "has_more": false,
    "next_cursor": null,
    "request_id": "req_01jx8kz3m4n5p6q7r8s9t0u1v"
  }
}
```

## Objeto empresa

| Campo               | Tipo         | Descrição                                             |
| ------------------- | ------------ | ----------------------------------------------------- |
| `id`                | string       | ID único da empresa                                   |
| `name`              | string       | Nome da empresa                                       |
| `email`             | string\|null | Email                                                 |
| `phone`             | string\|null | Telefone                                              |
| `website`           | string\|null | Site                                                  |
| `sector`            | string\|null | Setor de atuação                                      |
| `size`              | string\|null | Tamanho: `1-10`, `11-50`, `51-200`, `201-500`, `500+` |
| `city`              | string\|null | Cidade                                                |
| `state`             | string\|null | Estado                                                |
| `assigned_to`       | object\|null | Responsável `{id, name}`                              |
| `tags`              | string\[]    | Tags                                                  |
| `custom_fields`     | object       | Campos personalizados                                 |
| `contacts_count`    | integer      | Quantidade de contatos vinculados                     |
| `deals_count`       | integer      | Quantidade de negócios vinculados                     |
| `total_deals_value` | number       | Valor total dos negócios                              |
| `created_at`        | string       | Timestamp de criação                                  |
| `updated_at`        | string       | Timestamp de atualização                              |