# Webkio API examples

Common tasks, each in curl, JavaScript, PHP and Python. Put your API key in `WEBKIO_API_KEY`.

## Check your key

The account a key belongs to. A quick way to see a key works.

curl:

```bash
curl "https://api.webkio.com/v1/me" \
  -H "Authorization: Bearer $WEBKIO_API_KEY"
```

JavaScript:

```javascript
const res = await fetch('https://api.webkio.com/v1/me', {
  headers: {
    Authorization: `Bearer ${process.env.WEBKIO_API_KEY}`,
  },
});
const { data } = await res.json();
```

PHP:

```php
$ch = curl_init('https://api.webkio.com/v1/me');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('WEBKIO_API_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true)['data'];
```

Python:

```python
import os, requests

res = requests.get(
    'https://api.webkio.com/v1/me',
    headers={'Authorization': f"Bearer {os.environ['WEBKIO_API_KEY']}"},
)
data = res.json()['data']
```

## List your sites

Every list is cursor-paginated: pass meta.next_cursor as cursor until meta.has_more is false. A site's id is the project_id the other calls take.

curl:

```bash
curl "https://api.webkio.com/v1/projects?limit=25" \
  -H "Authorization: Bearer $WEBKIO_API_KEY"
```

JavaScript:

```javascript
const res = await fetch('https://api.webkio.com/v1/projects?limit=25', {
  headers: {
    Authorization: `Bearer ${process.env.WEBKIO_API_KEY}`,
  },
});
const { data } = await res.json();
```

PHP:

```php
$ch = curl_init('https://api.webkio.com/v1/projects?limit=25');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('WEBKIO_API_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true)['data'];
```

Python:

```python
import os, requests

res = requests.get(
    'https://api.webkio.com/v1/projects?limit=25',
    headers={'Authorization': f"Bearer {os.environ['WEBKIO_API_KEY']}"},
)
data = res.json()['data']
```

## Create or update a contact

Matched on email: a new address creates a contact, a known one updates it. Fields you leave out are not changed.

curl:

```bash
curl -X POST "https://api.webkio.com/v1/contacts" \
  -H "Authorization: Bearer $WEBKIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"SITE_ID","email":"sofia@example.com","name":"Sofia Almeida","tags":["vip"]}'
```

JavaScript:

```javascript
const res = await fetch('https://api.webkio.com/v1/contacts', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WEBKIO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "project_id": "SITE_ID",
    "email": "sofia@example.com",
    "name": "Sofia Almeida",
    "tags": [
      "vip"
    ]
  }),
});
const { data } = await res.json();
```

PHP:

```php
$ch = curl_init('https://api.webkio.com/v1/contacts');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('WEBKIO_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'project_id' => 'SITE_ID',
        'email' => 'sofia@example.com',
        'name' => 'Sofia Almeida',
        'tags' => [
            'vip',
        ],
    ]),
]);
$data = json_decode(curl_exec($ch), true)['data'];
```

Python:

```python
import os, requests

res = requests.post(
    'https://api.webkio.com/v1/contacts',
    headers={'Authorization': f"Bearer {os.environ['WEBKIO_API_KEY']}"},
    json={
        "project_id": "SITE_ID",
        "email": "sofia@example.com",
        "name": "Sofia Almeida",
        "tags": [
            "vip"
        ]
    },
)
data = res.json()['data']
```

## Add an email subscriber

Optionally to a list (GET /email-lists gives their ids). Someone who unsubscribed is never subscribed again this way.

curl:

```bash
curl -X POST "https://api.webkio.com/v1/subscribers" \
  -H "Authorization: Bearer $WEBKIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"SITE_ID","email":"sofia@example.com","name":"Sofia Almeida","list_id":"LIST_ID"}'
```

JavaScript:

```javascript
const res = await fetch('https://api.webkio.com/v1/subscribers', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WEBKIO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "project_id": "SITE_ID",
    "email": "sofia@example.com",
    "name": "Sofia Almeida",
    "list_id": "LIST_ID"
  }),
});
const { data } = await res.json();
```

PHP:

```php
$ch = curl_init('https://api.webkio.com/v1/subscribers');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('WEBKIO_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'project_id' => 'SITE_ID',
        'email' => 'sofia@example.com',
        'name' => 'Sofia Almeida',
        'list_id' => 'LIST_ID',
    ]),
]);
$data = json_decode(curl_exec($ch), true)['data'];
```

Python:

```python
import os, requests

res = requests.post(
    'https://api.webkio.com/v1/subscribers',
    headers={'Authorization': f"Bearer {os.environ['WEBKIO_API_KEY']}"},
    json={
        "project_id": "SITE_ID",
        "email": "sofia@example.com",
        "name": "Sofia Almeida",
        "list_id": "LIST_ID"
    },
)
data = res.json()['data']
```

## Find an order by its number

Orders read exactly as the order webhooks send them.

curl:

```bash
curl "https://api.webkio.com/v1/orders?number=ORD-260914-0001" \
  -H "Authorization: Bearer $WEBKIO_API_KEY"
```

JavaScript:

```javascript
const res = await fetch('https://api.webkio.com/v1/orders?number=ORD-260914-0001', {
  headers: {
    Authorization: `Bearer ${process.env.WEBKIO_API_KEY}`,
  },
});
const { data } = await res.json();
```

PHP:

```php
$ch = curl_init('https://api.webkio.com/v1/orders?number=ORD-260914-0001');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('WEBKIO_API_KEY'),
    ],
]);
$data = json_decode(curl_exec($ch), true)['data'];
```

Python:

```python
import os, requests

res = requests.get(
    'https://api.webkio.com/v1/orders?number=ORD-260914-0001',
    headers={'Authorization': f"Bearer {os.environ['WEBKIO_API_KEY']}"},
)
data = res.json()['data']
```

## Subscribe a URL to an event

The answer carries the signing secret, shown only this once. Leave project_id out to hear about every site.

curl:

```bash
curl -X POST "https://api.webkio.com/v1/webhooks" \
  -H "Authorization: Bearer $WEBKIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event":"order.paid","target_url":"https://example.com/webkio","project_id":"SITE_ID"}'
```

JavaScript:

```javascript
const res = await fetch('https://api.webkio.com/v1/webhooks', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WEBKIO_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "event": "order.paid",
    "target_url": "https://example.com/webkio",
    "project_id": "SITE_ID"
  }),
});
const { data } = await res.json();
```

PHP:

```php
$ch = curl_init('https://api.webkio.com/v1/webhooks');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('WEBKIO_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'event' => 'order.paid',
        'target_url' => 'https://example.com/webkio',
        'project_id' => 'SITE_ID',
    ]),
]);
$data = json_decode(curl_exec($ch), true)['data'];
```

Python:

```python
import os, requests

res = requests.post(
    'https://api.webkio.com/v1/webhooks',
    headers={'Authorization': f"Bearer {os.environ['WEBKIO_API_KEY']}"},
    json={
        "event": "order.paid",
        "target_url": "https://example.com/webkio",
        "project_id": "SITE_ID"
    },
)
data = res.json()['data']
```