## API-URL

URL som brukes til å sende HTTP-forespørslene:

```url
https://portal.bulkgate.com/api/1.0/simple/promotional
```

> [!NOTE]
> Hvis forespørselen ikke kommer frem, gjentar du den på [reserveserveren](https://www.bulkgate.com/no/dokumentasjon/api-administrasjon/api-reserveserver/) `backup1.bulkgate.com`.

## Støttede HTTP-metoder

- `GET`
- `POST` - `application/x-www-form-urlencoded`
- `POST` - `application/json`

Se [forespørselsmetoder](https://www.bulkgate.com/no/dokumentasjon/simple-api/simple-promotional-metoder/) for eksempler på hver av dem.

## Parametertabell

| PARAMETERNAVN     | VERDI | OBLIGATORISK | STANDARDVERDI |
|:------------------|:------|:-------------|:--------------|
| application_id    | [Applikasjonsidentifikator](https://www.bulkgate.com/no/dokumentasjon/api-administrasjon/administrasjon-av-api/) | **Ja** | - | 
| application_token | [Applikasjonens autentiseringstoken](https://www.bulkgate.com/no/dokumentasjon/api-administrasjon/api-token/) | **Ja** | - |
| number            | Mottakernumre atskilt med `;` (semikolon) | **Ja** | - |
| text              | Teksten i SMS-meldingen (maks. 612 tegn, eller 268 tegn hvis Unicode brukes), UTF-8-koding | **Ja** | - |
| unicode	          | `Yes`/`true`/`1` for Unicode-SMS, `no`/`false`/`0` for 7-bits SMS | Nei | `false` |
| sender_id         | Avsender-ID, se [avsender-ID-type](#avsender-id-type-sender-id) | Nei | `gSystem` |
| sender_id_value   | Avsenderverdi - `gOwn` (f.eks. «420 777 777 777»), `gText` (f.eks. «BulkGate»), `gProfile` (f.eks. «423»), `gMobile` eller `gPush` [(KEY)](https://www.bulkgate.com/no/hjelpesenter/mobile-connect/mobile-connect-installasjon/) | | |
| country           | Oppgi mottakernumrene i internasjonalt format (med landsprefiks, f.eks. `420`), eller legg til [landskoden](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) (`775123456` + `CZ` = `420775123456`). Se eksempelet på en forespørsel med land. Hvis verdien er **`null`**, brukes tidssonen du har angitt, til å fylle ut informasjonen | Nei | `null` |
| schedule          | Planlegg dato og klokkeslett for sendingen i [Unix-tidsstempel](https://en.wikipedia.org/wiki/Unix_time) eller [ISO 8601.](https://en.wikipedia.org/wiki/ISO_8601) Se eksemplene nedenfor. Verdien `now` sender meldingen umiddelbart, på samme måte som når parameteren utelates. | Nei | Nå |
| duplicates_check  | Velg **`on`** for å hindre at duplikatmeldinger sendes til samme telefonnummer. Meldinger med samme tekst sendt til samme nummer fjernes. Med **`off`** fjernes ingen duplikater. Duplikater fjernes **bare innenfor én og samme gruppe**, ikke på tvers av forespørsler. | Nei | `off` |
| tag               | Meldingsetikett som brukeren senere kan hente meldingene etter. | Nei | - |

### Avsender-ID-type `sender_id`

| VERDI      | BESKRIVELSE |
|:-----------|:------------|
| `gSystem`  | Systemnummer | 
| `gShort`   | Kortnummer (short code) | 
| `gText`    | Tekstavsender | 
| `gMobile`  | [Mobile Connect](https://www.bulkgate.com/no/hjelpesenter/mobile-connect/mobile-connect-installasjon/) |
| `gPush`    | Mobile Connect push - sender et varsel til Mobile Connect-appen |
| `gOwn`     | Eget nummer (krever bekreftelse av nummeret) | 
| `gProfile` | [BulkGate-profil-ID](https://www.bulkgate.com/no/hjelpesenter/sms/avsenderprofil/) |
| `<int>`    | BulkGate-profil-ID | 

## Eksempler på forespørsler

**Eksempel på en fullstendig forespørsel:**

```url
https://portal.bulkgate.com/api/1.0/simple/promotional
    ?application_id=451
    &application_token=NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj
    &number=420777777777;420775123456;606123456
    &text=test_sms
    &unicode=yes
    &sender_id=gText
    &sender_id_value=BulkGate
    &country=cz
    &schedule=2018-05-14T18:30:00-01:00
```

**Eksempel på en forespørsel med land:**

```url
https://portal.bulkgate.com/api/1.0/simple/promotional
    ?application_id=451
    &application_token=NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj
    &number=606123456;420777777777
    &text=test_sms
    &country=cz
```

**Eksempel på en forespørsel med ISO 8601:**

```url
https://portal.bulkgate.com/api/1.0/simple/promotional
    ?application_id=451
    &application_token=NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj
    &number=420775123456;420606123456
    &text=test_sms
    &schedule=2018-05-14T18:30:00-01:00
```

**Eksempel på en forespørsel med Unix-tidsstempel:**

```url
https://portal.bulkgate.com/api/1.0/simple/promotional
    ?application_id=451
    &application_token=NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj
    &number=420775123456;420606123456
    &text=test_sms
    &schedule=1526992636
```

**Eksempel på en POST JSON-forespørsel:**

```http-json
POST /api/1.0/simple/promotional HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
    "application_id": 451,
    "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
    "number": "420777777777;420775123456;606123456",
    "text": "test_sms",
    "unicode": true,
    "sender_id": "gText",
    "sender_id_value": "BulkGate",
    "country": "cz",
    "schedule": "2018-05-14T18:30:00-01:00"
}
```

## Svar

**Ved suksess:**

```json
{
  "data": {
    "total": {
      "status": {
        "sent": 0,
        "accepted": 0,
        "scheduled": 2,
        "error": 1
      }
    },
    "response": [
      {
        "status": "scheduled",
        "sms_id": "idfkvqrp-0",
        "part_id": [
                    "idfkvqrp-0_1",
                    "idfkvqrp-0_2",
                    "idfkvqrp-0"
                ],
        "number": "420775123456"
      },
      {
        "status": "scheduled",
        "sms_id": "idfkvqrp-1",
        "part_id": [
                    "idfkvqrp-1_1",
                    "idfkvqrp-1_2",
                    "idfkvqrp-1"
                ],
        "number": "420606123456"
      },
      {
        "status": "error",
        "code": 9,
        "error": "Invalid phone number",
        "number": "44771447678"
      }
    ]
  }
}
```

Der:

- **part_ID** er en matrise med ID-ene til delene av den opprinnelige lange meldingen, som ble delt opp fordi den overskred grensen på 160 tegn for én enkelt melding. Mer informasjon finner du [her](https://www.bulkgate.com/no/hjelpesenter/sms/sammenkjedede-meldinger/).

**Ved feil:**

```json
{
    "type": "invalid_phone_number",
    "code": 400,
    "error": "Invalid phone number",
    "detail": null
}
```

```json
{
    "type": "unknown_identity",
    "code": 401,
    "error": "Unknown identity / unauthorized / empty application_id",
    "detail": null
}
```

Der:

- **type** og **error** (beskrivelse av feilen) finner du i [tabellen over feiltyper](https://www.bulkgate.com/no/dokumentasjon/api-administrasjon/api-feiltyper/) 
- **code** er HTTP-feilkoden
- **detail** er tilleggsinformasjon om feilen

Se alle feiltyper for Simple API og Advanced API [her](https://www.bulkgate.com/no/dokumentasjon/api-administrasjon/api-feiltyper/).