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

# API AgencyHandy: Criar um Novo Lead Programaticamente

> Use a API do AgencyHandy para criar novos leads programaticamente enviando uma requisição POST para o endpoint bulk-lead com os campos obrigatórios.

O endpoint Criar Lead permite que você adicione novos leads programaticamente ao seu workspace do AgencyHandy a partir de qualquer sistema externo — um formulário web, um CRM, uma plataforma de automação de marketing ou um script personalizado. Leads criados via este endpoint aparecem em seu pipeline de leads imediatamente, como se tivessem sido adicionados manualmente.

<Note>
  Antes de usar este endpoint, conclua o guia de [Primeiros Passos](/pt-BR/api/getting-started) para obter sua chave de API e ID de Empresa. Você também precisa buscar o **ID do Perfil de Cliente**, que é obrigatório ao criar um lead.
</Note>

## Pré-requisitos

* ✅ Chave de API gerada em **Configuração do Workspace → Chave de API**
* ✅ ID de Empresa recuperado de `GET {{URL}}/accounts/companies`
* ✅ ID do Perfil de Cliente recuperado (veja o Passo 1 abaixo)

***

## Passo 1: Obter o ID do Perfil de Cliente

Antes de criar um lead, você precisa do ID do perfil para o perfil `client` na sua empresa.

### Endpoint

```
GET {{URL}}/roles?type=company
```

### Headers

| Header      | Valor             |
| ----------- | ----------------- |
| `x-api-key` | Sua chave de API  |
| `companyid` | Seu ID de Empresa |

### Exemplo de requisição

```bash cURL theme={null}
curl --request GET "https://api.agencyhandy.com/roles?type=company" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --header "companyid: <YOUR_COMPANY_ID>"
```

### Exemplo de resposta

```json theme={null}
{
  "roles": [
    {
      "_id": "6525994184e9ddd798534535",
      "role": {
        "_id": "6525994184e9ddd79853451e",
        "responsibility": "",
        "name": "client"
      },
      "company": "6525994184e9ddd79853450e",
      "createdAt": "2023-10-10T18:34:41.567Z",
      "updatedAt": "2024-10-01T07:28:48.340Z",
      "__v": 0,
      "type": "company"
    }
  ]
}
```

Encontre a entrada onde `roles[0].role.name === "client"` e extraia o `_id` **externo** — que é `roles[0]._id`, **não** `roles[0].role._id`.

```javascript theme={null}
const clientRoleId = roles.find(r => r.role.name === "client")._id;
// e.g. "6525994184e9ddd798534535"
```

<Warning>
  Use `roles[0]._id` (o ID do mapeamento empresa-perfil), **não** `roles[0].role._id` (o ID da definição do perfil). Usar o ID errado faz com que a requisição de criação de lead falhe.
</Warning>

***

## Passo 2: Criar um novo lead

### Endpoint

```
POST {{URL}}/members/bulk-lead
```

### Headers

| Header         | Valor              |
| -------------- | ------------------ |
| `x-api-key`    | Sua chave de API   |
| `companyid`    | Seu ID de Empresa  |
| `Content-Type` | `application/json` |

### Corpo da requisição

O corpo da requisição é um **array JSON** — você pode criar um ou mais leads em uma única chamada.

<ParamField body="firstName" type="string" required>
  O primeiro nome do lead.
</ParamField>

<ParamField body="lastName" type="string" required>
  O sobrenome do lead.
</ParamField>

<ParamField body="email" type="string" required>
  O endereço de e-mail do lead. Deve ser único dentro do seu workspace.
</ParamField>

<ParamField body="role" type="string" required>
  O ID do Perfil de Cliente recuperado no Passo 1 (ou seja, `roles[0]._id`).
</ParamField>

<ParamField body="isConvertedClient" type="boolean" required>
  Deve ser definido como `false` ao criar um lead. Defina como `true` apenas ao converter um lead em um cliente completo.
</ParamField>

<ParamField body="status" type="string">
  O status do lead no pipeline. Valores comuns: `New`, `Contacted`, `Qualified`. Padrão: `New` se omitido.
</ParamField>

<ParamField body="contactNo" type="string">
  O número de telefone do lead.
</ParamField>

<ParamField body="source" type="string">
  Como você adquiriu este lead. Exemplos de valores: `website`, `referral`, `social`.
</ParamField>

<ParamField body="positionInBoard" type="number">
  A posição (ordem) do lead dentro da coluna do quadro do pipeline. Padrão: `1`.
</ParamField>

### Exemplo de requisição

```bash cURL theme={null}
curl --request POST "https://api.agencyhandy.com/members/bulk-lead" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --header "companyid: <YOUR_COMPANY_ID>" \
  --header "Content-Type: application/json" \
  --data '[
    {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "role": "6525994184e9ddd798534535",
      "isConvertedClient": false,
      "status": "New",
      "contactNo": "1234567890",
      "source": "website",
      "positionInBoard": 1
    }
  ]'
```

### Resposta de sucesso

```json theme={null}
{
  "message": "Lead created successfully",
  "createdMembers": [
    {
      "_id": "NEW_MEMBER_ID",
      "name": "John Doe",
      "status": "New",
      "role": "client"
    }
  ]
}
```

<ResponseField name="message" type="string">
  String de confirmação: `"Lead created successfully"`.
</ResponseField>

<ResponseField name="createdMembers" type="array">
  Array de objetos de lead criados.
</ResponseField>

<ResponseField name="createdMembers[].\_id" type="string">
  O ID único do lead recém-criado. Armazene-o se precisar referenciar o lead em chamadas de API subsequentes.
</ResponseField>

<ResponseField name="createdMembers[].name" type="string">
  O nome completo do lead (firstName + lastName).
</ResponseField>

<ResponseField name="createdMembers[].status" type="string">
  O status do lead no pipeline conforme armazenado.
</ResponseField>

<ResponseField name="createdMembers[].role" type="string">
  O nome do perfil atribuído ao membro — será `"client"`.
</ResponseField>

<Tip>
  Você pode passar múltiplos objetos de lead no array para criar vários leads em uma única chamada de API. Cada objeto deve incluir todos os campos obrigatórios com seu próprio endereço de e-mail único.
</Tip>