## API URL

Adresa URL používaná na odosielanie HTTP požiadaviek:

```url
https://portal.bulkgate.com/api/1.0/address-book/add
```

> [!NOTE]
> Ak sa požiadavka nedostane k cieľu, zopakujte ju na [záložnom serveri](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/zalozny-server/) `backup1.bulkgate.com`.


## Podporované HTTP metódy

- `POST` - `application/json`

```http
POST /api/1.0/address-book/add HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
```

## Tabuľka s parametrami

| NÁZOV PARAMETRA	  | HODNOTA                                                        | 	POVINNÝ | PREDVOLENÁ HODNOTA             |
|:------------------|:---------------------------------------------------------------|:---------|:----------------------------|
| application_id    | [Aplikačný identifikátor](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/administracia-api/)         | **Áno**  | -                           | 
| application_token | [Aplikačný overovací token](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/api-tokeny/)	              | **Áno**  | -                           |
| groups            | Pole ID skupín, do ktorých bude kontakt pridaný                  | **Nie**   | -                           |
| group_name        | Pridaný kontakt bude pridaný do skupiny s názvom `group_name` | **Nie**   | -                           |
| data              | Kontaktné informácie                                            | **Áno**  | [Data objekt](#data-objekt) |
| category          | Adresár, s ktorým sa pracuje. Predvolený je hlavný adresár účtu.  | Nie       | `main`                      |
| duplicity_action  | Čo urobiť s kontaktom, ktorý už v adresári je — `restrict` (odmietnuť), `skip` (preskočiť), `update` (doplniť prázdne polia), `rewrite` (prepísať).  | Nie       | `restrict`                 |

## Data objekt

| NÁZOV PARAMETRA	 | HODNOTA                                                                                                                  | 	POVINNÝ | PREDVOLENÁ HODNOTA |
|:-----------------|:-------------------------------------------------------------------------------------------------------------------------|:---------|:----------------|
| type             | Typ kontaktu (person/company)                                                                                            | **Nie**   | -               |
| phone_mobile     | Hlavné telefónne číslo                                                                                                   | **Áno**  | -               | 
| title_before     | Titul pred menom                                                                                                        | **Nie**   | -               |
| first_name       | Krstné meno                                                                                                            | **Nie**   | -               |
| last_name        | Priezvisko                                                                                                                 | **Nie**   | -               |
| title_after      | Titul za menom                                                                                                           | **Nie**   | -               |
| gender           | male / female / transgender / agender / non_binary / unknown            | **Nie**   | unknown         |
| company_name     | Názov spoločnosti                                                                                                        | **Nie**   | -               |
| email            | E-mail                                                                                                                    | **Nie**   | -               |
| url              | URL vašej webovej stránky                                                                                                  | **Nie**   | -               |
| street1          | 1. riadok adresy (ulica)                                                                                                          | **Nie**   | -               |
| street2          | 2. riadok adresy (ulica)                                                                                                          | **Nie**   | -               |
| city             | Mesto                                                                                                                    | **Nie**   | -               |
| zip              | PSČ                                                                                                                  | **Nie**   | -               |
| state            | Štát                                                                                                                     | **Nie**   | -               |
| country          | [Kód krajiny vo formáte ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) | **Nie**   | `null`          |
| company_number   | IČO                                                                                                                      | **Nie**   | -               |
| company_vat      | IČ DPH                                                                                                                     | **Nie**   | -               |
| note             | Poznámka                                                                                                                 | **Nie**   | -               |
| custom_field_0   | Voliteľné pole                                                                                                           | **Nie**   | -               |
| custom_field_1   | Voliteľné pole                                                                                                           | **Nie**   | -               |
| custom_field_2   | Voliteľné pole                                                                                                           | **Nie**   | -               |
| custom_field_3   | Voliteľné pole                                                                                                           | **Nie**   | -               |
| custom_field_4   | Voliteľné pole                                                                                                           | **Nie**   | -               |
| custom_field_5   | Voliteľné pole                                                                                                           | **Nie**   | -               |
| custom_field_6   | Voliteľné pole                                                                                                           | **Nie**   | -               |
| custom_field_7   | Voliteľné pole                                                                                                           | **Nie**   | -               |
| custom_field_8   | Voliteľné pole                                                                                                           | **Nie**   | -               |
| custom_field_9   | Voliteľné pole                                                                                                           | **Nie**   | -               |

## Príklad požiadavky

```http-json
POST /api/1.0/address-book/add HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
	"application_id": 451,
	"application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
	"groups": [1, 2],
	"group_name": "Talos 1",
	"data": {
		"first_name": "Morgan",
		"last_name": "Yu",
		"phone_mobile": "123456789",
		"street1": "Crew's quarters",
		"street2": "Executive suite",
		"country": "Talos 1",
		"email": "morganyu@talos.com"
	}
}
```

## Odpoveď

**V prípade úspechu:**
```json
{
    "data": {
        "message": "contact_has_been_added",
        "groups": [1,2,3]
    }
}
```


**V prípade chyby:**
```json
{
    "type": "contact_with_this_phone_number_already_exists",
    "code": 400,
    "error": "Contact with this phone number already exists",
    "detail": null
}
```

```json
{
    "type": "invalid_phone_mobile",
    "code": 400,
    "error": "Invalid phone mobile",
    "detail": null
}
```

```json
{
    "type": "group_not_found",
    "code": 400,
    "error": "Group not found",
    "detail": null
}
```

Kde:

- **type** a **error** (popis chyby) nájdete v [tabuľke typov chýb](https://www.bulkgate.com/sk/dokumentacia/api-administracia-a-tokeny/typy-chyb-api/)
- **code** je HTTP kód chyby
- **detail** je doplňujúca informácia o chybe