# API-åtkomst

Ett API (Application Programming Interface) är ett sätt för olika mjukvarusystem att kommunicera med varandra. <span data-t="appName">Your AI Connector</span>-API:et låter dig (eller din utvecklare) automatiskt skapa kontakter, skicka meddelanden, hantera listor och ta emot inkommande meddelanden från anpassade kanaler — allt utan att använda kontrollpanelen.


**Varför använda API:et?** Om du vill ansluta appen till ett verktyg som inte har en inbyggd integration, eller om du behöver automatisera repetitiva uppgifter i stor skala, är API:et rätt väg att gå.

::: note
**Obs:** Den här sidan är av mer teknisk natur. Om du är företagare och inte utvecklare kan det vara bra att dela den här sidan med ditt tekniska team eller en frilansande utvecklare.
:::


---

## Generera din API-nyckel

::: note
**Obs:** API-åtkomst är en betalfunktion som är tillgänglig för kvalificerade abonnemang. Om ditt abonnemang inte inkluderar detta kommer API-förfrågningar att avvisas med ett `403`-svar. Kontrollera ditt abonnemang eller kontakta supporten om du är osäker på om API-åtkomst är aktiverat.
:::


1. Klicka på **Inställningar** (kugghjulsikonen) i sidofältet till vänster.
2. I inställningsmenyn, under gruppen **Integrationer**, klickar du på **API-nyckel**.


3. Om du inte har en nyckel än, klicka på **Generera API-nyckel**.
4. Om du redan har en, visas den maskerad under **Din nyckel**. Om din nyckel stöder det, klicka på **Visa** för att avslöja den, och sedan **Kopiera** för att kopiera den — du kommer att se en bekräftelse i ett meddelandefält.
5. Förvara nyckeln på en säker plats — du behöver den för varje API-anrop.


::: note
**Obs:** Vissa konton ser "Din nyckel kan inte visas" istället för en kontroll för Visa/Kopiera — detta sker för nycklar som skapades innan appen kunde visa dem igen. Nyckeln fungerar fortfarande som vanligt; du behöver bara **Återskapa** (under nyckelkortet, i samma sektion) om du faktiskt behöver se klartexten igen. Att återskapa gör den gamla nyckeln ogiltig omedelbart och avbryter alla integrationer som använder den tills du klistrar in den nya — uppdatera dina integrationer direkt efteråt.
:::


::: warning
**Viktigt:** Din API-nyckel fungerar som ett lösenord — den ger full åtkomst till ditt konto. Dela den inte offentligt och publicera den inte någonstans där andra kan se den. Om du tror att din nyckel har komprometterats, återskapa den omedelbart.
:::


> **Teammedlemmar:** API-nyckeln tillhör kontots ägare, så om du är inloggad som en inbjuden teammedlem (inklusive en administratör) visas en notis istället för nyckeln. Logga in som kontots ägare för att visa, kopiera eller återskapa den — detta gäller även för begränsade nycklar.

> **Var hittar du den:** **API-nyckel** är en egen sektion under Inställningar → Integrationer, separat från **Webhooks**. Om en guide eller en kollega ber dig leta efter nyckeln under "Webhooks", titta i sektionen bredvid istället.

---

## Bas-URL

Alla API-förfrågningar använder följande webbadress som bas:

```
https://api.youraiconnector.com/v1/
```

---

## Autentisering

Varje förfrågan måste innehålla din API-nyckel så att plattformen vet att det är du. Det enklaste sättet är att lägga till den i slutet av webbadressen:

```
https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
```

Du kan också skicka nyckeln som en anropsrubrik (request header) istället för i URL:en (rekommenderas för produktion, så att nyckeln inte hamnar i serverloggar):

```
X-API-Key: YOUR_API_KEY
```
```
Authorization: Bearer YOUR_API_KEY
```

Alla förfrågningar måste använda en säker anslutning (HTTPS). Osäkra (HTTP) förfrågningar avvisas.

> **Letar du efter de fullständiga utvecklarguiderna?** Den här sidan är en snabb introduktion som täcker de vanligaste åtgärderna. För kompletta, steg-för-steg-guider — för varje resurs, med exempel i cURL, JavaScript och Python — se [Komma igång med API:et](../api/getting-started.md) och [API-referensen](../api/reference.md).

---

## Vanliga API-åtgärder

### Skapa en kontakt

**Begäran:**

```http
POST https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phoneNumber": "+15551234567",
  "email": "jane@example.com"
}
```

**Obligatoriska fält:** ett `phoneNumber` (med landskod) krävs alltid för att skapa en kontakt. Enbart en e-postadress räcker inte — en förfrågan utan ett giltigt telefonnummer avvisas. E-postadressen är valfri.

**Svar:**

```json
{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "abc123xyz",
    "listsAdded": []
  }
}
```

Spara `data.contactId` — du behöver det för anropet "Lägg till en kontakt i en lista".

::: note
**Obs:** om en kontakt med samma telefonnummer redan finns, skapar eller returnerar API:et **inte** den kontakten — det returnerar `{ "success": false, "error_code": 409 }`. Sök upp den befintliga kontakten först med `GET https://api.youraiconnector.com/v1/contacts?phoneNumber=...`.
:::


---

### Lägg till en kontakt i en lista

```http
POST https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "contactId": "abc123xyz",
  "listId": "YOUR_LIST_ID"
}
```

Hitta en listas ID i appen under **Kontakter → Listor**, via listans radmeny (**Kopiera list-ID**).

---

### Uppdatera en kontakt

```http
PUT https://api.youraiconnector.com/v1/contacts/YOUR_CONTACT_ID?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customFields": { "company": "Acme Inc" }
}
```

Endast de fält du inkluderar ändras. Detta är också sättet att massladda värden för anpassade fält efter en import — se [Anpassade fält, lead-profil & anteckningar](../get-started/custom-contact-fields.md#bulk-loading-custom-fields). Fullständiga detaljer finns i [Contacts API](../api/contacts.md).

---

### Skicka ett meddelande (anpassad kanal)

```http
POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "fromId": "external-contact-id",
    "customChannel": "my-channel",
    "body": "Hello Jane! Your order has been shipped.",
    "campaignId": "optional-campaign-id",
    "firstName": "Jane",
    "lastName": "Smith"
  }
}
```

| Fält | Obligatoriskt | Beskrivning |
|---|---|---|
| `customData.fromId` | Ja | Kontaktens ID på din plattform |
| `customData.customChannel` | Ja | Namnet på din anpassade kanal |
| `customData.body` | Ja | Meddelandetexten som ska skickas |
| `customData.campaignId` | Nej | Dirigera meddelandet till en specifik kampanj |
| `customData.firstName` | Nej | Kontaktens förnamn (används vid skapande av ny kontakt) |
| `customData.lastName` | Nej | Kontaktens efternamn |
| `customData.email` | Nej | Kontaktens e-postadress |

::: note
**Obs:** denna slutpunkt är för meddelanden via anpassade kanaler. För WhatsApp, SMS, Instagram och Messenger skickas meddelanden via utskick, kampanjer och AI-agenter.
:::


---

### Ta emot inkommande meddelanden (anpassad kanal)

Ta emot meddelanden från externa system som en anpassad kanal. Det är så här integrationer som GoHighLevel skickar meddelanden till <span data-t="appName">Your AI Connector</span>. Se [Anpassade kanaler](../messaging-channels/custom-channels.md) för fullständig information.

```http
POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "messageSid": "unique-message-id",
    "fromId": "external-contact-id",
    "toId": "your-user-id",
    "body": "Customer's message here",
    "channel": "custom",
    "status": "received"
  },
  "messageType": "text"
}
```

| Fält | Krävs | Beskrivning |
|---|---|---|
| `customData.messageSid` | Ja | Ett unikt ID för detta meddelande (förhindrar dubbletter). Du kan även använda `customData.id`. |
| `customData.fromId` | Ja | Avsändarens ID i ditt externa system. |
| `customData.toId` | Ja | Din företagsidentifierare. |
| `customData.body` | Ja | Meddelandetexten. |
| `customData.channel` | Nej | En etikett för källan (t.ex. `"email"`, `"livechat"`, `"custom"`). |
| `customData.status` | Nej | Meddelandestatus. Standard är `"received"`. |
| `messageType` | Nej | `"text"` för textmeddelanden, `"reaction"` för emoji-reaktioner. |

---

## Översikt över tillgängliga åtgärder

| Åtgärd | Metod | Adress | Beskrivning |
|---|---|---|---|
| Skapa en kontakt | `POST` | `/contacts` | Lägg till en ny kontakt i ditt konto |
| Hämta kontaktuppgifter | `GET` | `/contacts?phoneNumber=X` eller `/contacts?email=X` | Sök upp en kontakt via telefonnummer eller e-post |
| Uppdatera en kontakt | `PUT` | `/contacts/{contactId}` | Uppdatera valfritt fält på en befintlig kontakt |
| Lägg till kontakt i lista | `POST` | `/contacts/lists` | Lägg till en befintlig kontakt i en specifik lista |
| Skicka ett meddelande | `POST` | `/send_custom_channel_message` | Skicka ett meddelande via en anpassad kanal |
| Ta emot ett meddelande | `POST` | `/incoming_custom_channel_message` | Ta emot ett meddelande från ett externt system |

---

## Hastighetsbegränsning

The API enforces rate limits to ensure platform stability. Exceeding your limit returns `429 Too Many Requests` — back off and retry after the time indicated in the response headers. For high-volume use cases (bulk imports), use the built-in [import feature](../get-started/importing-contacts.md) or email [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com) for guidance.

---

## Bästa praxis

- **Förvara din API-nyckel säkert** — använd en lösenordshanterare eller server-side-konfiguration, aldrig klient-side-kod som en webbesökare kan läsa.
- **Inkludera alltid landsnummer** i telefonnummer (`+1` för USA, `+44` för Storbritannien, `+31` för Nederländerna).
- **Hantera fel på ett snyggt sätt** — kontrollera statuskoder och läs eventuella felmeddelanden som returneras.
- **Hantera dubbletter** — ett dubbelt telefonnummer returnerar `{ "success": false, "error_code": 409 }` istället för en ny kontakt. Sök upp kontakten först om du behöver arbeta med den.
- **Testa med en liten datamängd** innan du kör massåtgärder.

---

## Felmeddelanden

```json
{
  "error": {
    "code": "INVALID_PHONE",
    "message": "Phone number must include a valid country code."
  }
}
```

| Status Code | Meaning |
|---|---|
| `200` | Success |
| `201` | Resource created |
| `400` | Bad request — check your parameters |
| `401` | Unauthorized — invalid or missing API key |
| `403` | Forbidden — your plan doesn't include API access, or you lack permission |
| `404` | Resource not found |
| `429` | Rate limit exceeded |
| `500` | Server error — email [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com) if this persists |

---

## Nästa steg

- [Webhooks](webhooks.md) — ta emot realtidsaviseringar från appen (en separat sektion från din API-nyckel).
- [Anslut AI-assistenter (MCP)](connect-ai-clients.md) — använd samma API-nyckel för att låta Claude styra ditt konto.
- [Facebook Lead Forms](facebook-lead-forms.md) — använd API:et med automatiseringsplattformar för att fånga leads.
- [GoHighLevel-integration](ghl-integration.md) — ett exempel på en fullständig tvåvägs-API-integration.