> ## 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: Skapa en ny lead programmatiskt

> Använd AgencyHandy API för att programmatiskt skapa nya leads genom att skicka en POST-begäran till bulk-lead-endpointen med de obligatoriska fälten.

Endpointen Skapa lead låter dig programmatiskt lägga till nya leads till din AgencyHandy-arbetsyta från vilket externt system som helst — ett webbformulär, ett CRM, en marknadsföringsautomationsplattform eller ett anpassat skript. Leads som skapas via denna endpoint visas i din lead-pipeline omedelbart, precis som om de lagts till manuellt.

<Note>
  Innan du använder denna endpoint, slutför guiden [Kom igång](/sv/api/getting-started) för att skaffa din API-nyckel och ditt företags-ID. Du behöver också hämta ditt **klientroll-ID**, vilket krävs när du skapar en lead.
</Note>

## Förutsättningar

* ✅ API-nyckel genererad från **Arbetsytekonfiguration → API-nyckel**
* ✅ Företags-ID hämtat från `GET {{URL}}/accounts/companies`
* ✅ Klientroll-ID hämtat (se Steg 1 nedan)

***

## Steg 1: Hämta klientroll-ID:t

Innan du skapar en lead behöver du roll-ID:t för `client`-rollen i ditt företag.

### Endpoint

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

### Huvuden

| Huvud       | Värde            |
| ----------- | ---------------- |
| `x-api-key` | Din API-nyckel   |
| `companyid` | Ditt företags-ID |

### Exempelbegäran

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

### Exempelsvar

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

Hitta posten där `roles[0].role.name === "client"` och extrahera det **yttre** `_id` — det vill säga `roles[0]._id`, **inte** `roles[0].role._id`.

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

<Warning>
  Använd `roles[0]._id` (företagsrollen mappnings-ID), **inte** `roles[0].role._id` (rolldefinitions-ID:t). Att använda fel ID gör att lead-skapande begäran misslyckas.
</Warning>

***

## Steg 2: Skapa en ny lead

### Endpoint

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

### Huvuden

| Huvud          | Värde              |
| -------------- | ------------------ |
| `x-api-key`    | Din API-nyckel     |
| `companyid`    | Ditt företags-ID   |
| `Content-Type` | `application/json` |

### Begärandekropp

Begärandekroppen är en **JSON-array** — du kan skapa en eller flera leads i ett enda anrop.

<ParamField body="firstName" type="string" required>
  Leadens förnamn.
</ParamField>

<ParamField body="lastName" type="string" required>
  Leadens efternamn.
</ParamField>

<ParamField body="email" type="string" required>
  Leadens e-postadress. Måste vara unik inom din arbetsyta.
</ParamField>

<ParamField body="role" type="string" required>
  Klientroll-ID:t hämtat i Steg 1 (dvs. `roles[0]._id`).
</ParamField>

<ParamField body="isConvertedClient" type="boolean" required>
  Måste sättas till `false` när du skapar en lead. Sätt till `true` endast när du konverterar en lead till en fullständig klient.
</ParamField>

<ParamField body="status" type="string">
  Leadens pipeline-status. Vanliga värden: `New`, `Contacted`, `Qualified`. Standardvärdet är `New` om det utelämnas.
</ParamField>

<ParamField body="contactNo" type="string">
  Leadens telefonnummer.
</ParamField>

<ParamField body="source" type="string">
  Hur du fick tag på denna lead. Exempelvärden: `website`, `referral`, `social`.
</ParamField>

<ParamField body="positionInBoard" type="number">
  Leadens position (ordning) inom pipeline-boardkolumnen. Standardvärdet är `1`.
</ParamField>

### Exempelbegäran

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

### Lyckat svar

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

<ResponseField name="message" type="string">
  Bekräftelsesträng: `"Lead created successfully"`.
</ResponseField>

<ResponseField name="createdMembers" type="array">
  Array med skapade lead-objekt.
</ResponseField>

<ResponseField name="createdMembers[].\_id" type="string">
  Det unika ID:t för den nyligen skapade leadsen. Spara detta om du behöver referera till leadsen i efterföljande API-anrop.
</ResponseField>

<ResponseField name="createdMembers[].name" type="string">
  Leadens fullständiga namn (förnamn + efternamn).
</ResponseField>

<ResponseField name="createdMembers[].status" type="string">
  Pipeline-statusen för leadsen som den lagrats.
</ResponseField>

<ResponseField name="createdMembers[].role" type="string">
  Rollnamnet tilldelat till medlemmen — kommer att vara `"client"`.
</ResponseField>

<Tip>
  Du kan skicka flera lead-objekt i arrayen för att skapa flera leads i ett enda API-anrop. Varje objekt måste inkludera alla obligatoriska fält med sin egen unika e-postadress.
</Tip>