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

# AgencyHandy API: Vytvoření nového leadu programově

> Pomocí API AgencyHandy programově vytvářejte nové leady odesláním POST požadavku na endpoint bulk-lead s požadovanými poli.

Endpoint pro vytvoření leadu umožňuje programově přidávat nové leady do vašeho workspace AgencyHandy z libovolného externího systému — webového formuláře, CRM, platformy pro marketingovou automatizaci nebo vlastního skriptu. Leady vytvořené prostřednictvím tohoto endpointu se okamžitě zobrazí v pipeline leadů, jako by byly přidány ručně.

<Note>
  Před použitím tohoto endpointu dokončete průvodce [Začínáme](/cs/api/getting-started) a získejte svůj API klíč a ID společnosti. Také potřebujete získat **ID role klienta**, které je vyžadováno při vytváření leadu.
</Note>

## Předpoklady

* ✅ API klíč vygenerovaný z **Konfigurace workspace → API klíč**
* ✅ ID společnosti získané z `GET {{URL}}/accounts/companies`
* ✅ ID role klienta získáno (viz Krok 1 níže)

***

## Krok 1: Získejte ID role klienta

Před vytvořením leadu potřebujete ID role pro roli `client` ve vaší společnosti.

### Endpoint

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

### Hlavičky

| Hlavička    | Hodnota             |
| ----------- | ------------------- |
| `x-api-key` | Váš API klíč        |
| `companyid` | Vaše ID společnosti |

### Ukázkový požadavek

```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>"
```

### Ukázková odpověď

```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"
    }
  ]
}
```

Najděte záznam, kde `roles[0].role.name === "client"`, a extrahujte **vnější** `_id` — to je `roles[0]._id`, **nikoli** `roles[0].role._id`.

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

<Warning>
  Použijte `roles[0]._id` (ID mapování role na společnost), **nikoli** `roles[0].role._id` (ID definice role). Použití nesprávného ID způsobí selhání požadavku na vytvoření leadu.
</Warning>

***

## Krok 2: Vytvoření nového leadu

### Endpoint

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

### Hlavičky

| Hlavička       | Hodnota             |
| -------------- | ------------------- |
| `x-api-key`    | Váš API klíč        |
| `companyid`    | Vaše ID společnosti |
| `Content-Type` | `application/json`  |

### Tělo požadavku

Tělo požadavku je **JSON pole** — v jednom volání můžete vytvořit jeden nebo více leadů.

<ParamField body="firstName" type="string" required>
  Křestní jméno leadu.
</ParamField>

<ParamField body="lastName" type="string" required>
  Příjmení leadu.
</ParamField>

<ParamField body="email" type="string" required>
  E-mailová adresa leadu. Musí být jedinečná v rámci vašeho workspace.
</ParamField>

<ParamField body="role" type="string" required>
  ID role klienta získané v Kroku 1 (tj. `roles[0]._id`).
</ParamField>

<ParamField body="isConvertedClient" type="boolean" required>
  Při vytváření leadu musí být nastaveno na `false`. Nastavte na `true` pouze při převodu leadu na plnohodnotného klienta.
</ParamField>

<ParamField body="status" type="string">
  Stav leadu v pipeline. Běžné hodnoty: `New`, `Contacted`, `Qualified`. Výchozí hodnota je `New`, pokud není zadáno.
</ParamField>

<ParamField body="contactNo" type="string">
  Telefonní číslo leadu.
</ParamField>

<ParamField body="source" type="string">
  Způsob získání tohoto leadu. Příklady hodnot: `website`, `referral`, `social`.
</ParamField>

<ParamField body="positionInBoard" type="number">
  Pozice (pořadí) leadu ve sloupci pipeline. Výchozí hodnota je `1`.
</ParamField>

### Ukázkový požadavek

```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
    }
  ]'
```

### Odpověď při úspěchu

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

<ResponseField name="message" type="string">
  Potvrzovací řetězec: `"Lead created successfully"`.
</ResponseField>

<ResponseField name="createdMembers" type="array">
  Pole vytvořených objektů leadů.
</ResponseField>

<ResponseField name="createdMembers[].\_id" type="string">
  Jedinečné ID nově vytvořeného leadu. Uložte jej, pokud potřebujete na lead odkazovat v následných voláních API.
</ResponseField>

<ResponseField name="createdMembers[].name" type="string">
  Celé jméno leadu (křestní jméno + příjmení).
</ResponseField>

<ResponseField name="createdMembers[].status" type="string">
  Stav leadu v pipeline tak, jak je uložen.
</ResponseField>

<ResponseField name="createdMembers[].role" type="string">
  Název role přiřazené členovi — bude `"client"`.
</ResponseField>

<Tip>
  V poli můžete předat více objektů leadů a vytvořit tak několik leadů v jednom volání API. Každý objekt musí obsahovat všechna povinná pole s vlastní jedinečnou e-mailovou adresou.
</Tip>