# Platform API

## Discovery

### Discovery planners

Provides data for planners who started planning within a specified date range.

<mark style="color:green;">`POST`</mark> `https://api.flip.to/v1/company/data/discovery/planners`

#### Query Parameters

| Name                                        | Type   | Description                                                                                                                                                                |
| ------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| startdate<mark style="color:red;">\*</mark> | String | The inclusive date range in ISO 8601 format `yyyy-MM-dd` (e.g. 2022-09-18)                                                                                                 |
| enddate<mark style="color:red;">\*</mark>   | String | The inclusive date range in ISO 8601 format `yyyy-MM-dd` (e.g. 2022-10-18)                                                                                                 |
| page                                        | String | The page number of the data to consume. If a page isn't specified, page should be set to 1.                                                                                |
| pagesize                                    | String | <p>The total number of records to send for each page</p><p>Page size cannot exceed 500 records at a time, and if not specified, the default value would be set to 100.</p> |

#### Request Body

| Name                  | Type    | Description                                                                                                                             |
| --------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| discoveries\[]        | String  | An array of discovery IDs to limit results to. If no discoveries are specified, all discoveries the key has access to will be returned. |
| isIncludeReservations | Boolean | Indicates whether to include the plan's associated reservations.                                                                        |
| isIncludeRestricted   | Boolean | Indicates whether to include restricted (GDPR) data.                                                                                    |
| isIncludeGuests       | Boolean | Indicate whethers to include guests planners.                                                                                           |
| isIncludeOptout       | Boolean | Indicate whether to include planners who have chosen to opt-out.                                                                        |

#### Example

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

```json
{
  "total": 1669,
  "page": 1,
  "planners": [
    {
      "discoveryName": "www.overlookhotel.com",
      "plannerId": "1D5892B3-48A9-3102-BED1-32BC97AAF577",
      "createDate": "2022-01-01T17:36:58.4478437",
      "email": "james@gmail.com",
      "first": "James",
      "languageCode": "en",
      "isBooked": true,
      "isUninterested": false,
      "isPrivacyRestricted": false,
      "isOptout": false,
      "activePlan": {
        "propertyId": "1234DF43-C41C-442F-804C-1234A7952738",
        "propertySlug": "overlook-hotel",
        "adults": 2,
        "children": 0,
        "beds": null,
        "rooms": 1,
        "arrival": "2022-01-01",
        "departure": "2022-01-02",
        "promo": null
      },
      "reservations": [
        {
          "propertyId": "1234DF43-C41C-442F-804C-1234A7952738",
          "propertySlug": "overlook-hotel",
          "createDate": "2022-01-02T04:14:00",
          "pmsNumber": "161000",
          "crsNumber": "10622SC40",
          "email": "james@flip.to",
          "first": "James",
          "last": "Smith",
          "phone": "1234567890",
          "phoneConsentMode": "Checkbox"
          "arrival": "2022-01-01",
          "departure": "2022-01-02",
          "currency": "USD",
          "amount": 365.11
        }
      ]
    }
  ]
}
```

{% endtab %}
{% endtabs %}

### Discovery planners who opted-out

Provides data for planners who opted out within a specified date range.

<mark style="color:green;">`POST`</mark> `https://api.flip.to/v1/company/data/discovery/optouts`

#### Query Parameters

| Name                                        | Type   | Description                                                                                                                                                                |
| ------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| startdate<mark style="color:red;">\*</mark> | String | The inclusive date range in ISO 8601 format `yyyy-MM-dd` (e.g. 2022-09-18)                                                                                                 |
| enddate<mark style="color:red;">\*</mark>   | String | The inclusive date range in ISO 8601 format `yyyy-MM-dd` (e.g. 2022-10-18)                                                                                                 |
| page                                        | String | The page number of the data to consume. If a page isn't specified, page should be set to 1.                                                                                |
| pagesize                                    | String | <p>The total number of records to send for each page</p><p>Page size cannot exceed 500 records at a time, and if not specified, the default value would be set to 100.</p> |

#### Request Body

| Name           | Type   | Description                                                                                                                             |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| discoveries\[] | String | An array of discovery IDs to limit results to. If no discoveries are specified, all discoveries the key has access to will be returned. |

#### Example

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

```json
{
  "total": 150,
  "page": 1,
  "optouts": [
    {
      "discoveryName": "www.overlookhotel.com",
      "email": "james@gmail.com",
      "optoutDate": "2022-05-04T18:21:58.1272137"
    }
  ]
}

```

{% endtab %}
{% endtabs %}

## Advocacy

### Advocacy leads

Provides data for leads who signed up within a specified date range.

<mark style="color:green;">`POST`</mark> `https://api.flip.to/v1/company/data/advocacy/signups`

#### Query Parameters

| Name                                        | Type   | Description                                                                                                                                                                |
| ------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| startdate<mark style="color:red;">\*</mark> | String | The inclusive date range in ISO 8601 format `yyyy-MM-dd` (e.g. 2022-09-18)                                                                                                 |
| enddate<mark style="color:red;">\*</mark>   | String | The inclusive date range in ISO 8601 format `yyyy-MM-dd` (e.g. 2022-10-18)                                                                                                 |
| page                                        | String | The page number of the data to consume. If a page isn't specified, page should be set to 1.                                                                                |
| pagesize                                    | String | <p>The total number of records to send for each page</p><p>Page size cannot exceed 500 records at a time, and if not specified, the default value would be set to 100.</p> |

#### Request Body

| Name                | Type    | Description                                                                                                                          |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| properties\[]       | String  | An array of property IDs to limit results to. If no properties are specified, all properties the key has access to will be returned. |
| isIncludeRestricted | Boolean | Indicates whether to include restricted (GDPR) data.                                                                                 |
| isIncludeOptout     | Boolean | Indicate whether to include leads who have chosen to opt-out.                                                                        |

#### Example

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

```json
{
  "total": 19388,
  "page": 1,
  "signups": [
    {
      "id": "C123600-2B05-47E3-8FBE-3EAB9E8A5Q11",
      "createDate": "2021-12-01T00:01:00",
      "propertyId": "1234DF43-C41C-442F-804C-1234A7952738",
      "propertySlug": "overlook-hotel",
      "email": "james@flip.to",
      "first": "James",
      "last": "Smith",
      "phone": "1234567890",
      "phoneConsentMode": "Checkbox",
      "languageCode": "en",
      "isOptout": false,
      "isPrivacyRestricted": false,
      "layerType": "photo contest",
      "category": "friend",
      "country": "United States", 
      "region": "FL", 
      "city": "Orlando"
    }
  ]
}

```

{% endtab %}
{% endtabs %}

### Advocacy stories

Provides data for Advocacy stories that were submitted within a specified date range. Results limited to stories that include a photo submission.

<mark style="color:green;">`POST`</mark> `https://api.flip.to/v1/company/data/advocacy/stories`

#### Query Parameters

| Name                                        | Type   | Description                                                                                                                                                                |
| ------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| startdate<mark style="color:red;">\*</mark> | String | The inclusive date range in ISO 8601 format `yyyy-MM-dd` (e.g. 2022-09-18)                                                                                                 |
| enddate<mark style="color:red;">\*</mark>   | String | The inclusive date range in ISO 8601 format `yyyy-MM-dd` (e.g. 2022-10-18)                                                                                                 |
| page                                        | String | The page number of the data to consume. If a page isn't specified, page should be set to 1.                                                                                |
| pagesize                                    | String | <p>The total number of records to send for each page</p><p>Page size cannot exceed 500 records at a time, and if not specified, the default value would be set to 100.</p> |

#### Request Body

| Name                | Type    | Description                                                                                                                          |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| properties\[]       | String  | An array of property IDs to limit results to. If no properties are specified, all properties the key has access to will be returned. |
| isIncludeRestricted | Boolean | Indicates whether to include restricted (GDPR) data.                                                                                 |
| isIncludeOptout     | Boolean | Indicate whether to include leads who have chosen to opt-out.                                                                        |

#### Example

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

```json
{
  "total": 5679,
  "page": 1,
  "stories": [
    {
     "propertyId": 1234DF43-C41C-442F-804C-1234A7952738",
      "propertySlug": "overlook-hotel",
      "email": "james@flip.to",
      "first": "James",
      "last": "Smith",
      "phone": "1234567890",
      "phoneConsentMode": "Checkbox",
      "category": "guest",
      "startDate": "2021-12-25",
      "endDate": "2021-12-29",
      "languageCode": "en",
      "isOptout": false,
      "isPrivacyRestricted": false,
      "submissionDate": "2022-01-02T06:32:00", 
      "photo": {
        "id": "C123600-2B05-47E3-8FBE-3EAB9E8A5Q11",
        "contestName": "Myrtle Beach Vacation Memories Giveaway!",
        "finalistDate": "2022-01-06T19:25:00",
        "internalRating": "2022-01-06T19:25:00",
        "score": 13,
        "caption": "I awoke this particular morning to look at the sunrise and was surprised to see the moon still out as well! The view was breathtaking along with the beautiful waves gently hitting the shore!",
        "captionInternalRating": 3,
        "url": "https:\/\/cdn.flip.to\/public\/c123600-2b05-47e3-8fbe-3eab9e8a5q11.jpg"
      },
      "review": {
        "rating": 5,
        "quote": "Waking up to the beautiful sun rises in the morning was very relaxing so much so part of the family did not want to leave.",
        "internalRating": 2
      }
    }
  ]
}
```

{% endtab %}
{% endtabs %}

### Advocacy leads who opted out

Provides data for leads who opted out within a specified date range.

<mark style="color:green;">`POST`</mark> `https://api.flip.to/v1/company/data/advocacy/optouts`

#### Query Parameters

| Name                                        | Type   | Description                                                                                                                                                                |
| ------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| startdate<mark style="color:red;">\*</mark> | String | The inclusive date range in ISO 8601 format `yyyy-MM-dd` (e.g. 2022-09-18)                                                                                                 |
| enddate<mark style="color:red;">\*</mark>   | String | The inclusive date range in ISO 8601 format `yyyy-MM-dd` (e.g. 2022-10-18)                                                                                                 |
| page                                        | String | The page number of the data to consume. If a page isn't specified, page should be set to 1.                                                                                |
| pagesize                                    | String | <p>The total number of records to send for each page</p><p>Page size cannot exceed 500 records at a time, and if not specified, the default value would be set to 100.</p> |

#### Request Body

| Name          | Type   | Description                                                                                                                          |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| properties\[] | String | An array of property IDs to limit results to. If no properties are specified, all properties the key has access to will be returned. |

#### Example

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

```json
{
  "total": 19388,
  "page": 1,
  "optouts": [
    {
      "propertyId": "1234DF43-C41C-442F-804C-1234A7952738",
      "propertySlug": "overlook-hotel",
      "optoutDate": "2022-05-04T18:21:58.1272137",
      "email": "james@gmail.com"
    }
  ]
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.flip.to/docs/api/reference/platform-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.