> For the complete documentation index, see [llms.txt](https://docs.flip.to/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flip.to/developers/api/reference/platform-api.md).

# 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></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></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></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&#x20;

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></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></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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.