# Retrieving opportunities

Retrieving opportunities enables you to:

* Retrieve information on all existing opportunities.
* Find out which properties are eligible for which opportunities.
* Retrieve instructions to render opportunities into a property's interface.
* Retrieve information on which dates the demand in a property's area is high.


→ If you want to implement or dismiss opportunities after retrieving them, see [implementing or dismissing opportunities](/connectivity/docs/opportunities-api/implementing-or-dismissing-opportunities).

## Retrieving all opportunities


```http
GET
https://supply-xml.booking.com/opportunity-api/opportunities
```

The `GET /opportunity-api/opportunities` request enables you to retrieve all the opportunities that are available on Booking.com.

→ If you want to know the opportunities for which a *specific property* is eligible, see [retrieving opportunities for a property](#retrieving-opportunities-for-a-property) 
→ If you want to know the properties that can implement a *specific opportunity*, see [retrieving properties by opportunity](#retrieving-properties-by-opportunity)

### Header parameters

The following table lists the header parameters in the request:

| Parameter | Description | Type | Required/Optional | Notes |
|  --- | --- | --- | --- | --- |
| Accept-Language | Specifies the language in which you want to receive the opportunity information. | enum | optional | You can find the lists of possible language codes at [https://connect.booking.com/user_guide/site/en-US/codes-bcl/](https://connect.booking.com/user_guide/site/en-US/codes-bcl/) |
| `Authorization` | [Machine account username and password](/connectivity/docs/authentication) | string | Required | Example: `Authorization: Basic {username:password}` |


### Sample request

You can find an example request in cURL here:


```cURL
curl -X GET \
  https://supply-xml.booking.com/opportunity-api/opportunities \
```

### Sample response

`PROVIDER` opportunities look slightly different.
`PROVIDER` opportunities do not have all of the elements that `TOGGLE` and `REDIRECT` have. You can find examples of each in the following sample.

You can find a sample response here:


```json
{
   "meta":{
      "ruid":"UmFuZG9tSVYkc2RlIyh6tr5vLrXVLc8GmUNIDetw/f912Hsa9sYk3GpQsk+ue9zdmvFPiClRDlNCaDgNDpsoMuOgnyDN"
   },
   "data":{
      "opportunities":[
         {
            "description":"We noticed your property is unavailable to book on certain high-demand dates for guests looking to stay in your area. We've highlighted these dates”as well as your most popular rooms”for you to take action on. Add more availability right away to start getting bookings!",
            "title":"You're missing out on bookings for the most popular dates in your area",
            "opportunity_id":"high_demand_dates_inventory",
            "implementation":"PROVIDER",
            "destination_api":"Unassigned"
         },
         {
            "url":"https://admin.booking.com/hotel/hoteladmin/extranet_ng/manage/connectivity_redirect.html?source=opp_api&hotel_id=5729902&redirect_id=no_credit_card_details_for_domestic_bookings&lang=en",
            "implementation":"REDIRECT",
            "destination_api":"Content API",
            "description":"Some guests may not have a credit card or may not want to use this. For customers living in your home country, you can offer a simplified booking process that doesn’t require credit card details.",
            "instructions":"Enable by clicking the button",
            "title":"Attract domestic customers by enabling room reservations without credit cards",
            "cta":"Activate through Booking.com",
            "opportunity_id":"no_credit_card_details_for_domestic_bookings"
         }
      ]
   },
   "warnings":[],
   "errors":[]
}
```

### Response body

The following table describes the elements of the response body:

| Element | Description | Type | Notes |
|  --- | --- | --- | --- |
| `meta` | Contains the meta data that comes with the response. | object |  |
| **>**`ruid` | Specifies the unique ID of the request. | string | You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong. |
| `data` | Contains the response data. | object |  |
| **>** `opportunities` | Contains the opportunity objects. | array |  |
| **>>** `description` | Specifies a recommendation for describing the opportunity. | string |  |
| **>>** `title` | Specifies a recommendation for introducing the opportunity. | string |  |
| **>>** `opportunity_id` | Specifies the unique ID of the opportunity. | string |  |
| **>>** `implementation` | Specifies the type of implementation. | string | The three possible implementation types are `TOGGLE`, `REDIRECT`, and `PROVIDER`. |
| **>>** `destination_api` | Specifies the API to which an opportunity belongs. | string |  |
| **>>** `categories` | Contains the categories in which opportunities are organised. | array |  |
| **>>>** `category_name` | Specifies the name of the opportunity category. The possible values are: `Availability`, `Ranking`, `Page views`, `Conversions`, `Length of stay`, `Average daily rate`, `Cancellations`, `Reduce workload`, and `Promotions`. | string |  |
| **>>** `cta` | Specifies a recommendation for describing the action. | string |  |
| **>>** `title` | Specifies a recommendation for introducing the opportunity. | string |  |
| **>>** `description` | Specifies a recommendation for describing the opportunity. | string |  |
| **>>** `url` | Specifies the URL that enables you to perform an action on the opportunity. | string |  |
| `warnings` | Contains potential warnings. These can help you improve your requests. | array |  |
| `errors` | Contains potential errors. These can help you understand what went wrong with your request. | array |  |


## Retrieving opportunities for a property


```http
GET
https://supply-xml.booking.com/opportunity-api/properties/{property_id}/opportunities
```

The `GET /opportunity-api/properties/{property_id}/opportunities` request enables you to retrieve all the possible opportunities for a specific property. This means you must specify the property ID to receive a list of opportunities that the property is eligible for.

Prioritisation of opportunities
The response lists the available opportunities by priority. You should present them in the same order on the property's interface.

### Path parameters

The following table lists the query parameters in the request:

| Parameter | Description | Type | Required/Optional | Notes |
|  --- | --- | --- | --- | --- |
| property_id | Specifies the ID of the property you want to retrieve opportunities for. | integer | required | You can only specify one property ID per call. |


### Header parameters

The following table lists the header parameters in the request:

| Parameter | Description | Type | Required/Optional | Notes |
|  --- | --- | --- | --- | --- |
| `Accept-Language` | Specifies the language in which you want to receive the opportunity information. | enum | optional | You can find the lists of possible language codes at [https://connect.booking.com/user_guide/site/en-US/codes-bcl/](https://connect.booking.com/user_guide/site/en-US/codes-bcl/) |
| `Authorization` | [Machine account username and password](/connectivity/docs/authentication) | string | Required | Example: `Authorization: Basic {username:password}` |


### Sample request

You can find a cURL example request here:


```cURL
curl -X GET \
  https://supply-xml.booking.com/opportunity-api/properties/5729902/opportunities \
```

### Sample response

`PROVIDER` opportunities look slightly different.
`PROVIDER` opportunities have a few different elements from `TOGGLE` and `REDIRECT` opportunities, and vice versa.

You can find a sample response here:


```json
{
  "meta": {
    "ruid": "UmFuZG9tSVYkc2RlIyh6tr5vLrXVLc8GmUNIDetw/f912Hsa9sYk3GpQsk+ue9zdmvFPiClRDlNCaDgNDpsoMuOgnyDN"
  },
  "data": {
    "opportunities": [
      {
        "implementation_data": [
          {
            "entity_id": "1234599_2020-02-19",
            "entity_type": "STAY_ID"
          },
          {
            "entity_id": "1234500_2020-02-19",
            "entity_type": "STAY_ID"
          },
          {
            "entity_id": "1234599_2020-02-20",
            "entity_type": "STAY_ID"
          }
        ],
        "description": "We noticed your property is unavailable to book on certain high-demand dates for guests looking to stay in your area. We've highlighted these dates”as well as your most popular rooms”for you to take action on. Add more availability right away to start getting bookings!",
        "title": "You're missing out on bookings for the most popular dates in your area",
        "opportunity_id": "high_demand_dates_inventory",
        "categories":[
               {
                  "category_name":"Availability"
               },
               {
                  "category_name":"Conversion"
               },
               {
                  "category_name":"Ranking"
               }
            ],
        "implementation": "PROVIDER"
      },
      {
        "url": "https://admin.booking.com/hotel/hoteladmin/extranet_ng/manage/connectivity_redirect.html?source=opp_api&hotel_id=5729902&redirect_id=no_credit_card_details_for_domestic_bookings&lang=en",
        "implementation": "REDIRECT",
        "destination_api": "Content API",
        "description": "Some guests may not have a credit card or may not want to use this. For customers living in your home country, you can offer a simplified booking process that doesn’t require credit card details.",
        "instructions": "Enable by clicking the button",
        "categories": [
          {
            "category_name": "Conversions"
          },
          {
            "category_name": "Promotions"
          }
        ],
        "title": "Attract domestic customers by enabling room reservations without credit cards",
        "cta": "Activate through Booking.com",
        "opportunity_id": "no_credit_card_details_for_domestic_bookings"
      }
    ]
  },
  "warnings": [],
  "errors": []
}
```

### Response body

The following table describes the elements of the response body:

| Element | Description | Type | Notes |
|  --- | --- | --- | --- |
| `meta` | Contains the meta data that comes with the response. | object |  |
| **>** `ruid` | Specifies the unique ID of the request. | string | You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong. |
| `data` | Contains the response data. | object |  |
| **>** `opportunities` | Contains the opportunity objects. | array |  |
| **>>** `implementation_data` | Contains the data specific to implementing the `PROVIDER` type opportunities. | array |  |
| **>>>**`entity_id` | Specifies the room ID and the date on which the demand is high. | string |  |
| **>>>** `entity_type` | Specifies the type of the `PROVIDER` opportunity. | string | The only possible value is `STAY_ID` |
| **>>** `description` | Specifies a recommendation for describing the opportunity. | string |  |
| **>>** `title` | Specifies a recommendation for introducing the opportunity. | string |  |
| **>>** `opportunity_id` | Specifies the unique ID of the opportunity. | string |  |
| **>>**`implementation` | Specifies the type of implementation. | string | The three possible implementation types are `TOGGLE`, `REDIRECT`, and `PROVIDER`. |
| **>>** `destination_api` | Specifies the API to which an opportunity belongs. | string |  |
| **>>** `categories` | Contains the categories in which opportunities are organised. | array |  |
| **>>>** `category_name` | Specifies the name of the opportunity category. The possible values are: `Availability`, `Ranking`, `Page views`, `Conversions`, `Length of stay`, `Average daily rate`, `Cancellations`, `Reduce workload`, and `Promotions`. | string |  |
| **>>** `cta` | Specifies a recommendation for describing the action. | string |  |
| **>>** `title` | Specifies a recommendation for introducing the opportunity. | string |  |
| **>>** `description` | Specifies a recommendation for describing the opportunity. | string |  |
| **>>** `url` | Specifies the URL that enables you to perform an action on the opportunity. | string |  |
| **>>** `implementation` |  | Specifies the type of implementation. | string |
| `warnings` | Contains potential warnings. These can help you improve your requests. | array |  |
| `errors` | Contains potential errors. These can help you understand what went wrong with your request. | array |  |


## Retrieving properties by opportunity


```http
GET
https://supply-xml.booking.com/opportunity-api/opportunities?opportunity_id={opportunity_id}
```

The `GET /opportunity-api/opportunities?opportunity_id={opportunity_id}` request enables you to retrieve all the properties that are eligible for a specific opportunity. This means you must specify the opportunity ID to receive a list of eligible properties.

Use of pagination
Because the amount of properties for this bulk call can be big, retrieving all of them at once can cause issues. Therefore, this call includes pagination, which you can modify depending on your situation or preferences.

### Query parameters

The following table lists the query parameters in the request:

| Parameter | Description | Type | Required/Optional | Notes |
|  --- | --- | --- | --- | --- |
| `opportunity_id` | Specifies the ID of the opportunity for which you want to retrieve the eligible properties. | string | required | You can only specify one opportunity ID per call. |
| `page` | Specifies the number of the page you want to retrieve. | integer | optional | The default value is 1. |
| `page_size` | Specifies the number of properties you want to retrieve per page. | integer | optional | The default value is 100.  For `PROVIDER` opportunities, the default value of 100 is also the max value. |


### Header parameters

The following table lists the header parameters in the request:

| Parameter | Description | Type | Required/Optional | Notes |
|  --- | --- | --- | --- | --- |
| `Accept-Language` | Specifies the language in which you want to receive the opportunity information. | enum | optional | You can find the lists of possible language codes at https://connect.booking.com/user_guide/site/en-US/codes-bcl/ |
| `Authorization` | [Machine account username and password](/connectivity/docs/authentication) | string | Required | Example: `Authorization: Basic {username:password}` |


### Sample request

You can find a cURL example request for `TOGGLE` and `REDIRECT` opportunities below. For a `PROVIDER` opportunity example, see [provider type sample request](#Provider-type-sample-request).


```cURL
curl -X GET \
  https://supply-xml.booking.com/opportunity-api/opportunities?opportunity_id=free_wifi&page=2&pagesize=100 \
```

### Sample response


```json
{
  "data": { 
    "opportunity":{ 
      "opportunity_id":"free_wifi",
      "title":"Show guests that your property offers free Wi-Fi",
      "description":"WiFi is one of the most requested features by modern travellers. Meet demand and make properties more attractive by showing potential guests that they offer free Wifi included in the stay.",
      "instructions":"Just enable by clicking the button",
      "cta":"Enable",
      "implementation":"TOGGLE",
      "url":"https://admin.booking.com/hotel/hoteladmin/extranet_ng/manage/availability_calendar.html",
      "destination_api":"Content API",
   },
    "properties":[ 
      { 
      "property_id":"12345",
      "status":"eligible"
      },
      { 
      "property_id":"54321",
      "status":"ineligible/implemented"
      }
   ],
    "pagination":{ 
      "page":2,
      "page_size":100,
      "page_count":123,
      "total_count":12300
   }
 },
  "meta": {
    "ruid": "UmFuZG9tSVYkc2RlIyd4ggzfY4dZasPGAUcglKEyRzk2/HbSzspV7O+mQdkB4hP2dlEyQkjV+iI71VQFka7vNa5MAta305nepI2yvXTv4="
    },
 "errors": [],
 "warnings": []
}
```

### Response body

The following table describes the elements of the response body:

| Element | Description | Type | Notes |
|  --- | --- | --- | --- |
| `meta` | Contains the meta data that comes with the response. | object |  |
| **>** `ruid` | Specifies the unique ID of the request. | string | You can send this ID to Booking.com customer support if you run into an issue. This can help to understand what went wrong. |
| `data` | Contains the response data. | object |  |
| **>** `opportunity` | Contains the specified opportunity information. | array |  |
| **>>** `opportunity_id` | Specifies the unique ID of the opportunity. | string |  |
| **>>** `title` | Specifies a recommendation for introducing the opportunity. | string |  |
| **>>** `description` | Specifies a recommendation for describing the opportunity. | string |  |
| **>>** `instructions` | Specifies the instructions the property must follow to implement or dismiss the opportunity. | string |  |
| **>>** `cta` | Specifies a recommendation for describing the action. | string |  |
| **>>** `implementation` | Specifies the type of implementation. | string | The three possible implementation types are `TOGGLE`, `REDIRECT`, and `PROVIDER`. |
| **>>** `url` | Specifies the url that enables you to perform an action on the opportunity. | string |  |
| **>>** `destination_api` | Specifies the api to which an opportunity belongs. | string |  |
| **>>** `categories` | Contains the categories in which opportunities are organised. | array |  |
| **>>>** `category_name` | Specifies the name of the opportunity category. The possible values are: `Availability`, `Ranking`, `Page views`, `Conversions`, `Length of stay`, `Average daily rate`, `Cancellations`, `Reduce workload`, and `Promotions`. | string |  |
| **>** `properties` | Contains the eligible opportunities. | array |  |
| **>>** `property_id` | Specifies the unique ID of the eligible property. | string |  |
| **>>** `status` | Specifies the status of the opportunity. The possible values are: `eligible` and `ineligible/implemented` | enum |  |
| **>**`pagination` | Contains the pagination information. | object |  |
| **>>**`page` |  | Specifies the page number that you requested. If you didn't specify the number, it returns page 1. | integer |
| **>>**`page_size` | Specifies the number of properties per page. If you didn't specify the amount, it returns 100 properties per page. | integer |  |
| **>>** `page_count` | Specifies the number of pages with properties. | integer |  |
| **>>** `total_count` | Specifies the total amount of properties connected to your machine account. | integer |  |
| `warnings` | Contains potential warnings. These can help you improve your requests. | array |  |
| `errors` | Contains potential errors. These can help you understand what went wrong with your request. | array |  |


### Provider type sample request

You can find a cURL example request for a `PROVIDER` opportunity example here:


```cURL
curl -X GET \
  https://supply-xml.booking.com/opportunity-api/opportunities?opportunity_id=high_demand_dates_inventory&page=1&pagesize=50 \
```

### Provider type sample response


```json
{
  "data": {  
    "properties": [
      {  
        "property_id": "6038700",  
        "implementation_data": []  
      },    
      {  
        "property_id": "6038692",  
        "implementation_data": [
          {  
            "entity_id": "566202102_2020-01-25",  
            "entity_type": "STAY_ID"  
          },  
          {  
            "entity_id": "566202102_2020-01-26",  
            "entity_type": "STAY_ID"  
          }
        ]
       }
      ],
    "opportunity": {  
      "title": "You're missing out on bookings for the most popular dates in your area",  
            "destination_api": "Unassigned",  
            "implementation": "PROVIDER",  
            "description": "We noticed your property is unavailable for bookings on some dates that are in high demand by guests looking for stays in your area. We have highlighted these dates, alongside your most popular rooms, for you to take action on. Add more availability right away to start gaining bookings!",  
            "opportunity_id": "high_demand_dates_inventory",
        },  
    "pagination": {  
      "page_size": 50,  
      "total_count": 263,  
      "page": 1,  
      "total_pages": 6  
    },     
  "meta": {
    "ruid": "UmFuZG9tSVYkc2RlIyd4ggzfY4dZasPGAUcglKEyRzk2/HbSzspV7O+mQdkB4hP2dlEyQkjV+iI71VQFka7vNa5MAta305nepI2yvXTv4="
  },
  "errors": [],
  "warnings": []
  }
}
```

### Provider type response body

The following table describes the elements of the response body:

| Element | Description | Type | Notes |
|  --- | --- | --- | --- |
| `meta` | Contains the meta data that comes with the response. | object |  |
| **>** | `ruid` | Specifies the unique ID of the request. | string |
| `data` | Contains the response data. | object |  |
| **>** `opportunity` | Contains the specified opportunity information. | array |  |
| **>>** `opportunity_id` | Specifies the unique ID of the opportunity. | string |  |
| **>>** `title` | Specifies a recommendation for introducing the opportunity. | string |  |
| **>>** `description` | Specifies a recommendation for describing the opportunity. | string |  |
| **>>** `implementation` | Specifies the type of implementation. | string | The three possible implementation types are `TOGGLE`, `REDIRECT`, and `PROVIDER`. |
| **>>** `destination_api` | Specifies the api to which an opportunity belongs. | string |  |
| **>** `properties` | Contains the eligible opportunities. | array |  |
| **>>** `property_id` | Specifies the unique ID of the eligible property. | string |  |
| **>>** `implementation_data` | Contains the data specific to implementing the `PROVIDER` type opportunities. | array |  |
| **>>>** `entity_id` | Specifies the room ID and the date on which the demand is high. | string |  |
| **>>>** `stay_id` | Specifies the type of the `PROVIDER` opportunity. | string | The only possible value is `STAY_ID`, which contains the room ID and the date. |
| **>** `pagination` | Contains the pagination information. | object |  |
| **>>** `page` |  | Specifies the page number that you requested. If you didn't specify the number, it returns page 1. | integer |
| **>>** `page_size` | Specifies the number of properties per page. If you didn't specify the amount, it returns 100 properties per page. | integer |  |
| **>>** `page_count` | Specifies the number of pages with properties. | integer |  |
| **>>** `total_count` | Specifies the total amount of properties connected to your machine account. | integer |  |
| `warnings` | Contains potential warnings. These can help you improve your requests. | array |  |
| `errors` |  | Contains potential errors. These can help you understand what went wrong with your request. | array |