# Readers

API for managing app readers

## List Readers

<mark style="color:blue;">`GET`</mark> `https://www.magloft.com/api/portal/v1/readers/:app_id`

This endpoint **returns** a list of all `readers` that belong to the magazine

#### Path Parameters

| Name    | Type   | Description                                     |
| ------- | ------ | ----------------------------------------------- |
| app\_id | String | App ID (Publication) to scope this request for. |

#### Query Parameters

| Name  | Type                       | Description |
| ----- | -------------------------- | ----------- |
| debug | Virtus::Attribute::Boolean |             |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1234,
  "email": "john.doe@magloft.com",
  "name": "John",
  "lastname": "Doe",
  "last_sign_in_at": "2018-01-24 10:55:35",
  "created_at": "2018-01-24 10:55:35",
  "devices": [
    "android",
    "apple"
  ],
  "confirmed": true,
  "authentication_token": "aabbccddeeff00112233445566778899",
  "custom_data": {
  },
  "password": "",
  "classification_ids": [
    1,
    2,
    3
  ]
}
```

{% endtab %}
{% endtabs %}

## Retrieve paginated list of readers

<mark style="color:blue;">`GET`</mark> `https://www.magloft.com/api/portal/v1/readers/:app_id/page/:page`

This endpoint **returns** a page list of all `readers` that belong to the magazine

#### Path Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| app\_id | String  | App ID (Publication) to scope this request for. |
| page    | Integer | The page number to list                         |

#### Query Parameters

| Name       | Type    | Description                              |
| ---------- | ------- | ---------------------------------------- |
| per\_page  | Integer | Number of items to show per page         |
| order\_by  | Symbol  | Field to sort results by                 |
| order\_dir | Symbol  | Direction (asc, desc) to sort results by |
| filter     | JSON    |                                          |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "total": 1,
  "page": 1,
  "records": [
    {
      "id": 1234,
      "email": "john.doe@magloft.com",
      "name": "John",
      "lastname": "Doe",
      "last_sign_in_at": "2018-01-24 10:55:35",
      "created_at": "2018-01-24 10:55:35",
      "devices": [
        "android",
        "apple"
      ],
      "confirmed": true,
      "classification_ids": [
        1,
        2,
        3
      ]
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Get Reader

<mark style="color:blue;">`GET`</mark> `https://www.magloft.com/api/portal/v1/readers/:app_id/(:email)(:id)`

This endpoint **returns** a specific `reader` by `id`

#### Path Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| app\_id | String  | App ID (Publication) to scope this request for. |
| email   | String  | Reader Email Address                            |
| id      | Integer | Reader ID                                       |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1234,
  "email": "john.doe@magloft.com",
  "name": "John",
  "lastname": "Doe",
  "last_sign_in_at": "2018-01-24 10:55:35",
  "created_at": "2018-01-24 10:55:35",
  "devices": [
    "android",
    "apple"
  ],
  "confirmed": true,
  "authentication_token": "aabbccddeeff00112233445566778899",
  "custom_data": {
  },
  "password": "",
  "classification_ids": [
    1,
    2,
    3
  ]
}
```

{% endtab %}
{% endtabs %}

## Create a Reader

<mark style="color:green;">`POST`</mark> `https://www.magloft.com/api/portal/v1/readers/:app_id`

This endpoint **creates** a new `reader` and **returns** the saved `reader`

#### Path Parameters

| Name    | Type   | Description                                     |
| ------- | ------ | ----------------------------------------------- |
| app\_id | String | App ID (Publication) to scope this request for. |

#### Request Body

| Name                | Type                       | Description                                  |
| ------------------- | -------------------------- | -------------------------------------------- |
| email               | String                     | Reader Email Address                         |
| password            | String                     | Reader Password                              |
| name                | String                     | Reader First Name                            |
| lastname            | String                     | Reader Last Name                             |
| custom\_data        | Hash                       | Custom key-value data stored for this reader |
| confirmation        | Virtus::Attribute::Boolean | Send Confirmation Email                      |
| confirmed           | Virtus::Attribute::Boolean | Whether this readers' Email was confirmed    |
| classification\_ids | Array                      | Reader Classification IDs                    |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1234,
  "email": "john.doe@magloft.com",
  "name": "John",
  "lastname": "Doe",
  "last_sign_in_at": "2018-01-24 10:55:35",
  "created_at": "2018-01-24 10:55:35",
  "devices": [
    "android",
    "apple"
  ],
  "confirmed": true,
  "authentication_token": "aabbccddeeff00112233445566778899",
  "custom_data": {
  },
  "password": "",
  "classification_ids": [
    1,
    2,
    3
  ]
}
```

{% endtab %}
{% endtabs %}

## Update a Reader

<mark style="color:orange;">`PUT`</mark> `https://www.magloft.com/api/portal/v1/readers/:app_id/:id`

This endpoint **updates** a specific `reader` by `id` and **returns** the updated `reader`

#### Path Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| app\_id | String  | App ID (Publication) to scope this request for. |
| id      | Integer | Reader ID                                       |

#### Request Body

| Name                | Type                       | Description                                  |
| ------------------- | -------------------------- | -------------------------------------------- |
| name                | String                     | Reader First Name                            |
| lastname            | String                     | Reader Last Name                             |
| email               | String                     | Reader Email Address                         |
| custom\_data        | Hash                       | Custom key-value data stored for this reader |
| password            | String                     | Reader Password                              |
| confirmed           | Virtus::Attribute::Boolean | Whether this readers' Email was confirmed    |
| classification\_ids | Array                      | Reader Classification IDs                    |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": 1234,
  "email": "john.doe@magloft.com",
  "name": "John",
  "lastname": "Doe",
  "last_sign_in_at": "2018-01-24 10:55:35",
  "created_at": "2018-01-24 10:55:35",
  "devices": [
    "android",
    "apple"
  ],
  "confirmed": true,
  "authentication_token": "aabbccddeeff00112233445566778899",
  "custom_data": {
  },
  "password": "",
  "classification_ids": [
    1,
    2,
    3
  ]
}
```

{% endtab %}
{% endtabs %}

## Delete Reader

<mark style="color:red;">`DELETE`</mark> `https://www.magloft.com/api/portal/v1/readers/:app_id/:id`

This endpoint **deletes** a specific `reader` by `id` and **returns** an `empty response` with status `204`

#### Path Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| app\_id | String  | App ID (Publication) to scope this request for. |
| id      | Integer | Reader ID                                       |

{% tabs %}
{% tab title="200 " %}

```javascript
null
```

{% endtab %}
{% endtabs %}

## Create Issue Purchases

<mark style="color:green;">`POST`</mark> `https://www.magloft.com/api/portal/v1/readers/:app_id/:id/unlock`

This endpoint **creates** one or many `issue purchases` by `product_id` and **returns** a list of `issue purchases`

#### Path Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| app\_id | String  | App ID (Publication) to scope this request for. |
| id      | Integer | Reader ID                                       |

#### Request Body

| Name         | Type   | Description                                  |
| ------------ | ------ | -------------------------------------------- |
| product\_ids | Array  | Array containing Issue Product IDs to unlock |
| order\_id    | String | Subscription Order ID                        |

{% tabs %}
{% tab title="200 " %}

```javascript
{
}
```

{% endtab %}
{% endtabs %}

## Unlock Issue By Coupon

<mark style="color:green;">`POST`</mark> `https://www.magloft.com/api/portal/v1/readers/:app_id/:id/unlock/coupon`

This endpoint **unlock** one `issue` by `coupon` and **returns** a list of `issue purchases`

#### Path Parameters

| Name    | Type    | Description                                     |
| ------- | ------- | ----------------------------------------------- |
| app\_id | String  | App ID (Publication) to scope this request for. |
| id      | Integer | Reader ID                                       |

#### Request Body

| Name        | Type    | Description |
| ----------- | ------- | ----------- |
| issue\_id   | Integer |             |
| article\_id | Integer |             |
| code        | String  |             |

{% tabs %}
{% tab title="200 " %}

```javascript
{
}
```

{% endtab %}
{% endtabs %}

## Export readers

<mark style="color:blue;">`GET`</mark> `https://www.magloft.com/api/portal/v1/readers/:app_id/export.csv`

#### Path Parameters

| Name    | Type   | Description                                     |
| ------- | ------ | ----------------------------------------------- |
| app\_id | String | App ID (Publication) to scope this request for. |

{% tabs %}
{% tab title="200 " %}

```javascript
null
```

{% endtab %}
{% endtabs %}