diff --git a/docs/API-Keys/authorization.md b/docs/API-Keys/authorization.md
index 76bb8aec..33aa8304 100644
--- a/docs/API-Keys/authorization.md
+++ b/docs/API-Keys/authorization.md
@@ -29,8 +29,10 @@ The following example uses `cURL` to request a new token:
 ```bash
 curl "https://test.api.amadeus.com/v1/security/oauth2/token" \
      -H "Content-Type: application/x-www-form-urlencoded" \
-     -d "grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}"
+     -d "grant_type=client_credentials&client_id=<YOUR-CLIENT-ID>&client_secret=<YOUR-CLIENT-SECRET>"
 ```
+Replace `<YOUR-CLIENT-ID>` with your API Key and `<YOUR-CLIENT-SECRET>` with your API Secret in the command above.
+
 Note that the `-X POST` parameter is not needed in the `cURL` command. As we are sending a body, `cURL` sends the request as `POST` automatically.
 
 ## Response
@@ -67,14 +69,15 @@ The response will contain the following parameters:
 
 Once the token has been retrieved, you can authenticate your requests to Amadeus Self-Service APIs.
 
-Each API call must contain the `authorization` HTTP header with the value `Bearer {access_token}`, where `acess_token` is the token you have just retrieved.
+Each API call must contain the `authorization` HTTP header with the value `Bearer <access_token>`, where `<acess_token>` is the token you have just retrieved.
 
 The following example is a call to the `Flight Check-in Links` API to retrieve the check-in URL for Iberia \(`IB`\):
 
 ```bash
 curl "https://test.api.amadeus.com/v2/reference-data/urls/checkin-links?airline=IB" \
-     -H "Authorization: Bearer CpjU0sEenniHCgPDrndzOSWFk5mN"
+     -H "Authorization: Bearer <YOUR-BEARER-TOKEN>"
 ```
+Replace `<YOUR-BEARER-TOKEN>` with the token you received from the authorization call.
 
 ## Managing tokens from your source code
 
@@ -92,10 +95,11 @@ Example of initializing the client and authenticating with the `Node` SDK:
 var Amadeus = require('amadeus');
 
 var amadeus = new Amadeus({
-  clientId: '[API Key]',
-  clientSecret: '[API Secret]'
+  clientId: '<YOUR-CLIENT-ID>',
+  clientSecret: '<YOUR-CLIENT-SECRET>'
 });
 ```
+Replace `<YOUR-CLIENT-ID>` with your API Key and `<YOUR-CLIENT-SECRET>` with your API Secret.
 
 You can then call the API. The following example is a call to the `Flight Check-in Links` API to retrieve the check-in URL for Iberia \(`IB`\):
 
@@ -104,8 +108,8 @@ You can then call the API. The following example is a call to the `Flight Check-
 var Amadeus = require('amadeus');
 
 var amadeus = new Amadeus({
-  clientId: '[API Key]',
-  clientSecret: '[API Secret]'
+  clientId: '<YOUR-CLIENT-ID>',
+  clientSecret: '<YOUR-CLIENT-SECRET>'
 });
 
 amadeus.referenceData.urls.checkinLinks.get({
@@ -116,4 +120,5 @@ amadeus.referenceData.urls.checkinLinks.get({
   console.log(responseError.code);
 });
 ```
+Replace `<YOUR-CLIENT-ID>` with your API Key and `<YOUR-CLIENT-SECRET>` with your API Secret.
 
diff --git a/docs/API-Keys/moving-to-production.md b/docs/API-Keys/moving-to-production.md
index ab698a0e..e6adc20d 100644
--- a/docs/API-Keys/moving-to-production.md
+++ b/docs/API-Keys/moving-to-production.md
@@ -7,9 +7,9 @@ When your application is ready to be deployed to the Real World™, you can requ
 To request a **production key**, you must complete the following steps:
 
 1. [Sign in](https://developers.amadeus.com/signin){:target="\_blank"} to your account and enter [My Self-Service Workspace](https://developers.amadeus.com/my-apps){:target="\_blank"}.
-2. Select the application to move to `Production` and click `Get Production environment` :
+2. Select the application to move to `Production` and click `Get production environment` :
 
-   ![request_prod](../images/api-keys/moving-to-production/request_production_key.png)
+    ![request_prod](../images/api-keys/moving-to-production/request_production_key.png)
 
 3. Complete the form with your personal information, billing address, and app information.
 4. Indicate whether your application uses `Flight Create Orders` in the checkbox at the bottom of the form. This API has special access requirements detailed below in the `Moving to Production with Flight Create Orders` section of this guide.
@@ -25,8 +25,8 @@ You will receive a notification that your application is validated and the statu
 
 ![live](../images/api-keys/moving-to-production/app_live.png)
 
-> Production keys are valid for all Self-Service APIs except `Flight Create Orders API`, which has special requirements. See the `Moving to Production with Flight Create Orders` of this guide for more information.
-
+!!!information
+    Production keys are valid for all Self-Service APIs except `Flight Create Orders API`, which has special requirements. See the `Moving to Production with Flight Create Orders` of this guide for more information.
 
 Remember that once you exceed your free transactions threshold, you will be billed automatically for your transactions every month. You can manage and track your app usage in [My Self-Service Workspace](https://developers.amadeus.com/my-apps){:target="\_blank"}.
 
@@ -43,8 +43,8 @@ If you are using [Amadeus for Developers SDKs](https://github.com/amadeus4dev){:
 from amadeus import Client, ResponseError
 
 amadeus = Client(
-    client_id='REPLACE_BY_YOUR_API_KEY',
-    client_secret='REPLACE_BY_YOUR_API_SECRET',
+    client_id='<YOUR-CLIENT-ID>',
+    client_secret='<YOUR-CLIENT-SECRET>',
     hostname='production'
 )
 
@@ -57,7 +57,8 @@ try:
     print(response.data)
 except ResponseError as error:
     print(error)
-```
+```  
+Replace `<YOUR-CLIENT-ID>` with your API Key and `<YOUR-CLIENT-SECRET>` with your API Secret in the command above.
 
 ## Video Tutorial
 
@@ -79,7 +80,7 @@ Applications using `Flight Create Orders` must meet special requirements before
 
 2. **There are no restrictions in your country**. Though we are working to make Self-Service flight booking available worldwide, `Flight Create Orders` API is currently not available to companies in the following countries: 
 
-   *Algeria, Bangladesh, Bhutan, Bulgaria, Croatia, Egypt, Finland, Iceland,
+    *Algeria, Bangladesh, Bhutan, Bulgaria, Croatia, Egypt, Finland, Iceland,
 Iran, Iraq, Jordan, Kuwait, Kosovo, Lebanon, Libya, Madagascar, Maldives,
 Montenegro, Morocco, Nepal, Pakistan, Palestine, Qatar, Saudi Arabia, Serbia, Sri Lanka, Sudan, Syria, Tahiti, Tunisia, United Arab Emirates and
 Yemen* 
diff --git a/docs/developer-tools/graphql/rest-to-graphql-export.md b/docs/developer-tools/graphql/rest-to-graphql-export.md
index 2ffe0856..827f87f7 100644
--- a/docs/developer-tools/graphql/rest-to-graphql-export.md
+++ b/docs/developer-tools/graphql/rest-to-graphql-export.md
@@ -78,3 +78,4 @@ server.listen().then(({ url }) => {
   console.log(`🚀 Server ready at ${url}`);
 });
 ```
+Replace `<path-to-generated-graphql-schema>` with the path to the schema generated in the **Convert** step.
diff --git a/docs/developer-tools/graphql/rest-to-graphql-node.md b/docs/developer-tools/graphql/rest-to-graphql-node.md
index a2b5b744..c131ed7f 100644
--- a/docs/developer-tools/graphql/rest-to-graphql-node.md
+++ b/docs/developer-tools/graphql/rest-to-graphql-node.md
@@ -142,9 +142,10 @@ Now that we have the server running, we can send requests to it. The most straig
 ```shell
 curl -X POST \
   -H "Content-Type: application/json" \
-  -H "Authorization: <your_bearer_token>" \
+  -H "Authorization: <YOUR-BEARER-TOKEN>" \
   -d '{ "query": "{ getCities(keyword: \"PARIS\") { name } }" }' \
   http://localhost:4000/
 ```
+Replace `<YOUR-BEARER-TOKEN>` with the token you received from the authorization call.
 
 If your token is valid, the above command will return a list of city names that contain the word `Paris`.
diff --git a/docs/developer-tools/graphql/rest-to-graphql-python.md b/docs/developer-tools/graphql/rest-to-graphql-python.md
index 833d5471..05ef0d97 100644
--- a/docs/developer-tools/graphql/rest-to-graphql-python.md
+++ b/docs/developer-tools/graphql/rest-to-graphql-python.md
@@ -121,9 +121,10 @@ Now that we have the server running, we can send requests to it. The most straig
 ```shell
 curl -X POST \
   -H "Content-Type: application/json" \
-  -H "Authorization: <your_bearer_token>" \
+  -H "Authorization: <YOUR-BEARER-TOKEN>" \
   -d '{ "query": "{ getCities(keyword: \"PARIS\") { name } }" }' \
   http://localhost:8000/
 ```
+Replace `<YOUR-BEARER-TOKEN>` with the token you received from the authorization call.
 
 If your token is valid, the above command will return a list of city names that contain the word `Paris`.
diff --git a/docs/developer-tools/java.md b/docs/developer-tools/java.md
index 317d561d..f066ff3c 100644
--- a/docs/developer-tools/java.md
+++ b/docs/developer-tools/java.md
@@ -28,12 +28,12 @@ compile "com.amadeus:amadeus-java:7.0.0"
 
 **Further information:**
 
-You can check the library in the [Maven repository](https://mvnrepository.com/artifact/com.amadeus/amadeus-java/latest){:target="\_blank"} for futher information.
+You can check the library in the [Maven repository](https://mvnrepository.com/artifact/com.amadeus/amadeus-java/latest){:target="\_blank"} for further information.
 
 ### Step-by-step example
 
 This tutorial will guide you through the process of creating a simple Java
-application which calls the Flight Inspiration Search API using the Amadeus
+application which calls the [Flight Inspiration Search API](https://developers.amadeus.com/self-service/category/flights/api-doc/flight-inspiration-search){:target="\_blank"} using the Amadeus
 for Developers Java SDK.
 
 ### Using the Amadeus Java SDK
@@ -85,9 +85,10 @@ public class FlightSearch {
 Before testing the example, export your credentials in your terminal:
 
 ```bash
-export AMADEUS_CLIENT_ID=YOUR_CLIENT_ID
-export AMADEUS_CLIENT_SECRET=YOUR_CLIENT_SECRET
+export AMADEUS_CLIENT_ID=<YOUR-CLIENT-ID>
+export AMADEUS_CLIENT_SECRET=<YOUR-CLIENT-SECRET>
 ```
+Replace `<YOUR-CLIENT-ID>` with your API Key and `<YOUR-CLIENT-SECRET>` with your API Secret in the command above.
 
 Let's build and run the code to make sure that everything is working properly:
 
@@ -152,4 +153,4 @@ You can also check the video tutorial on how to get started with the Java SDK.
 
 ### Managing API rate limits
 
-[Amadeus Self-Service APIs](https://developers.amadeus.com/self-service){:target="\_blank"} have [rate limits](../api-rate-limits.md){:target="\_blank"} in place to protect against abuse by third parties. You can find Rate limit example in Java using the Amadeus Java SDK [here](https://github.com/amadeus4dev-examples/APIRateLimits/tree/master/Java){:target="\_blank"}. 
\ No newline at end of file
+[Amadeus Self-Service APIs](https://developers.amadeus.com/self-service){:target="\_blank"} have [rate limits](../api-rate-limits.md){:target="\_blank"} in place to protect against abuse by third parties. You can find Rate limit example in Java using the Amadeus Java SDK [here](https://github.com/amadeus4dev-examples/APIRateLimits/tree/master/Java){:target="\_blank"}. 
diff --git a/docs/developer-tools/node.md b/docs/developer-tools/node.md
index 024fda0c..309054fe 100644
--- a/docs/developer-tools/node.md
+++ b/docs/developer-tools/node.md
@@ -20,8 +20,8 @@ To make your first API call, you will need to [register](https://developers.amad
 ```js
 var Amadeus = require('amadeus');
 var amadeus = new Amadeus({
-  clientId: 'REPLACE_BY_YOUR_API_KEY',
-  clientSecret: 'REPLACE_BY_YOUR_API_SECRET'
+  clientId: '<YOUR-CLIENT-ID>',
+  clientSecret: '<YOUR-CLIENT-SECRET>'
 });
 
 amadeus.shopping.flightOffersSearch.get({
@@ -35,6 +35,7 @@ amadeus.shopping.flightOffersSearch.get({
   console.log(responseError.code);
 });
 ```
+Replace `<YOUR-CLIENT-ID>` with your API Key and `<YOUR-CLIENT-SECRET>` with your API Secret in the command above.
 
 ### Initialization
 
@@ -44,10 +45,11 @@ The client can be initialized directly as below. Your credentials `client Id` an
 ```js
 // Initialize using parameters
 var amadeus = new Amadeus({
-  clientId: 'REPLACE_BY_YOUR_API_KEY',
-  clientSecret: 'REPLACE_BY_YOUR_API_SECRET'
+  clientId: '<YOUR-CLIENT-ID>',
+  clientSecret: '<YOUR-CLIENT-SECRET>'
 });
 ```
+Replace `<YOUR-CLIENT-ID>` with your API Key and `<YOUR-CLIENT-SECRET>` with your API Secret in the command above.
 
 !!! warning
     Remember that hardcoding your credentials is not the best practice due to the potential exposure to others. Read more about best practices for [secure API key storage](https://developers.amadeus.com/blog/best-practices-api-key-storage){:target="\_blank"}.
@@ -62,9 +64,10 @@ npm install dotenv
 Put your API credentials in `.env` file:
 
 ```sh
-AMADEUS_CLIENT_ID=REPLACE_BY_YOUR_API_KEY,
-AMADEUS_CLIENT_SECRET=REPLACE_BY_YOUR_API_SECRET
+AMADEUS_CLIENT_ID=<YOUR-CLIENT-ID>,
+AMADEUS_CLIENT_SECRET=<YOUR-CLIENT-SECRET>
 ```
+Replace `<YOUR-CLIENT-ID>` with your API Key and `<YOUR-CLIENT-SECRET>` with your API Secret in the command above.
 
 Initialize using dotenv package:
 
@@ -81,10 +84,11 @@ If you don't want to use another package, you can also simply export your key in
 Export your credentials in terminal:
 
 ```sh
-export AMADEUS_CLIENT_ID="REPLACE_BY_YOUR_API_KEY"
-export AMADEUS_CLIENT_SECRET="REPLACE_BY_YOUR_API_SECRET"
-
+export AMADEUS_CLIENT_ID="<YOUR-CLIENT-ID>"
+export AMADEUS_CLIENT_SECRET="<YOUR-CLIENT-SECRET>"
 ```
+Replace `<YOUR-CLIENT-ID>` with your API Key and `<YOUR-CLIENT-SECRET>` with your API Secret in the command above.
+
 Initialize:
 
 ```js
@@ -149,4 +153,4 @@ You can also check the video tutorial on how to get started with the Node SDK.
 
 ### Managing API rate limits
 
-[Amadeus Self-Service APIs](https://developers.amadeus.com/self-service){:target="\_blank"} have [rate limits](../api-rate-limits.md){:target="\_blank"} in place to protect against abuse by third parties. You can find Rate limit example in Node using the Amadeus Node SDK [here](https://github.com/amadeus4dev-examples/APIRateLimits){:target="\_blank"}. 
\ No newline at end of file
+[Amadeus Self-Service APIs](https://developers.amadeus.com/self-service){:target="\_blank"} have [rate limits](../api-rate-limits.md){:target="\_blank"} in place to protect against abuse by third parties. You can find Rate limit example in Node using the Amadeus Node SDK [here](https://github.com/amadeus4dev-examples/APIRateLimits){:target="\_blank"}. 
diff --git a/docs/developer-tools/php.md b/docs/developer-tools/php.md
index 91e4ce4f..8a994b89 100644
--- a/docs/developer-tools/php.md
+++ b/docs/developer-tools/php.md
@@ -30,7 +30,7 @@ use Amadeus\Exceptions\ResponseException;
 require __DIR__ . '/vendor/autoload.php'; // include composer autoloader
 
 try {
-    $amadeus = Amadeus::builder("REPLACE_BY_YOUR_API_KEY", "REPLACE_BY_YOUR_API_SECRET")
+    $amadeus = Amadeus::builder("<YOUR-CLIENT-ID>", "<YOUR-CLIENT-SECRET>")
         ->build();
 
     // Flight Offers Search GET
@@ -72,6 +72,8 @@ try {
     print $e;
 }
 ```
+Replace `<YOUR-CLIENT-ID>` with your API Key and `<YOUR-CLIENT-SECRET>` with your API Secret in the command above and execute it.
+
 
 #### Handling the response  
 
@@ -117,4 +119,4 @@ For the `post` endpoints:
 
 ```php
 $amadeus->getClient()->postWithStringBody("/v1/shopping/availability/flight-availabilities", $body);
-```
\ No newline at end of file
+```
diff --git a/docs/developer-tools/python.md b/docs/developer-tools/python.md
index 60134a3e..b42bacac 100644
--- a/docs/developer-tools/python.md
+++ b/docs/developer-tools/python.md
@@ -57,8 +57,8 @@ This tutorial will guide you through the process of creating a simple Python app
 from amadeus import Client, Location, ResponseError
 
 amadeus = Client(
-    client_id='AMADEUS_CLIENT_ID',
-    client_secret='AMADEUS_CLIENT_SECRET'
+    client_id='<YOUR-CLIENT-ID>',
+    client_secret='<YOUR-CLIENT-SECRET>'
 )
 
 try:
@@ -70,6 +70,7 @@ try:
 except ResponseError as error:
     print(error)
 ```
+Replace `<YOUR-CLIENT-ID>` with your API Key and `<YOUR-CLIENT-SECRET>` with your API Secret in the command above.
 
 - Once you import the amadeus library, you initialize the client by adding your credentials in the `builder` method. The library can also be initialized without any parameters when the environment variables `AMADEUS_CLIENT_ID` and `AMADEUS_CLIENT_SECRET` are present.
 - The authentication process is handled by the SDK and the access token is renewed every 30 minutes.
@@ -141,7 +142,7 @@ To follow along with the tutorial you will need the followings:
 
 `aiohttp` is a Python library for making asynchronous HTTP requests build top of `asyncio`. The library provides a simple way of making HTTP requests and handling the responses in a non-blocking way.
 
-In the example below you can call the the Amadeus Flight-Checkin link API using the `aiohttp` library and the code runs in an async way.
+In the example below you can call the the [Amadeus Flight-Checkin link API](https://developers.amadeus.com/self-service/category/flights/api-doc/flight-check-in-links) using the `aiohttp` library and the code runs in an async way.
 
 ```python
 import aiohttp
@@ -151,8 +152,8 @@ import requests
 AUTH_ENDPOINT = "https://test.api.amadeus.com/v1/security/oauth2/token"
 headers = {"Content-Type": "application/x-www-form-urlencoded"}
 data = {"grant_type": "client_credentials",
-        "client_id": 'YOUR_AMADEUS_API_KEY',
-        "client_secret": 'YOUR_AMADEUS_API_SECRET'}
+        "client_id": '<YOUR-CLIENT-ID>',
+        "client_secret": '<YOUR-CLIENT-SECRET>'}
 response = requests.post(AUTH_ENDPOINT,
                         headers=headers,
                         data=data)
@@ -174,6 +175,7 @@ async def main():
                 
 asyncio.run(main())
 ```
+Replace `<YOUR-CLIENT-ID>` with your API Key and `<YOUR-CLIENT-SECRET>` with your API Secret in the command above.
 
 The above code makes `POST` request to the Authentication API using the `requests` library. The returned access token is then used in the headers of following requests to make 20 asyncronous API calls.
 
@@ -187,8 +189,8 @@ import requests
 from amadeus import Client
 
 amadeus = Client(
-    client_id='YOUR_AMADEUS_API_KEY',
-    client_secret='YOUR_AMADEUS_API_SECRET'
+    client_id='<YOUR-CLIENT-ID>',
+    client_secret='<YOUR-CLIENT-SECRET>'
 )
 
 async def main():
@@ -208,6 +210,7 @@ async def main():
 
 asyncio.run(main())
 ```
+Replace `<YOUR-CLIENT-ID>` with your API Key and `<YOUR-CLIENT-SECRET>` with your API Secret in the command above.
 
 ## OpenAPI Generator
 
@@ -249,8 +252,8 @@ with openapi_client.ApiClient(auth_configuration) as api_client:
 
     body = dict(
         grant_type="client_credentials",
-        client_id="YOUR_API_KEY",
-        client_secret="YOUR_API_SECRET",
+        client_id="<YOUR-CLIENT-ID>",
+        client_secret="<YOUR-CLIENT-SECRET>",
     )
     api_response = api_instance.oauth2_token(
         body=body,
@@ -258,6 +261,7 @@ with openapi_client.ApiClient(auth_configuration) as api_client:
 
 print(api_response.body['access_token'])
 ```
+Replace `<YOUR-CLIENT-ID>` with your API Key and `<YOUR-CLIENT-SECRET>` with your API Secret in the command above.
 
 The code uses the library we have generated to get an OAuth2 access token. With the `o_auth2_access_token_api.OAuth2AccessTokenApi()` we are able to call the `oauth2_token()` method.
 
@@ -265,7 +269,7 @@ The body of the request is being created by passing the `grant_type`, `client_id
 
 ### Call the Flight Offers Search API
 
-Now let's call the Flight Offers Search API. Since thr OpenAPI Generator works with OAS3 you will have to convert the flight search specification to version 3 using the swagger editor (https://editor.swagger.io/){:target="\_blank"}. To do the convertion, navigate to the top menu and select `Edit` then `Convert to OAS 3`.
+Now let's call the Flight Offers Search API. Since the OpenAPI Generator works with OAS3 you will have to convert the flight search specification to version 3 using the [swagger editor](https://editor.swagger.io/){:target="\_blank"}. To do the conversion, navigate to the top menu and select `Edit` then `Convert to OAS 3`.
 
 The process is the same as above. You need to generate the library:
 
@@ -291,7 +295,7 @@ from openapi_client.apis.tags import shopping_api
 
 flight_configuration = openapi_client.Configuration()
 api_client = openapi_client.ApiClient(flight_configuration)
-api_client.default_headers['Authorization'] = 'Bearer YOUR_ACCESS_TOKEN'
+api_client.default_headers['Authorization'] = 'Bearer <YOUR-BEARER-TOKEN>'
 
 api_instance = shopping_api.ShoppingApi(api_client)
 
@@ -310,6 +314,7 @@ try:
 except openapi_client.ApiException as e:
     print("Exception: %s\n" % e)
 ```
+Replace `<YOUR-BEARER-TOKEN>` with the token you received from the authorization call.
 
 The above code uses the generated library to to search for flight offers. It creates an instance of the `shopping_api.ShoppingApi` class and setting the default headers to include the access token.
 
diff --git a/docs/faq.md b/docs/faq.md
index f41ba78b..eba2b572 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -99,7 +99,7 @@ Our Self-Service offer is designed for newcomers to Amadeus, there are no prereq
 
 ### Are there any limitations to the Self-Service API dataset?
 
-We do not return data on American Airlines, Delta, British Airways and Low cost carriers. For other arlines we only return published rates. We do not return negotiated rates or any other special rates. The Flight Offers Search only returns the bag allowance information for one passenger type code. Airlines blacklisted in the EU are not returned using the Flight Offers Search GET, e.g., Iraqi Airways. There is a possibility to override this with the POST method.
+We do not return data on American Airlines, Delta, British Airways and Low cost carriers. For other airlines we only return published rates. We do not return negotiated rates or any other special rates. The Flight Offers Search only returns the bag allowance information for one passenger type code. Airlines blacklisted in the EU are not returned using the Flight Offers Search GET, e.g., Iraqi Airways. There is a possibility to override this with the POST method.
 
 ### How can I do group booking?
 
@@ -202,11 +202,11 @@ The information returned in test environment is from [limited data collections](
 
 ### Why didn't I get any results for Flight Inspiration Search?
 
-This API works with cached data in the test environment and not all airports are cached. You can find a list of airports included in the cached data in our guides section. When combining these searches with the Airport Nearest Relevant API, it is better to search using the city code rather than the airport code.
+This API works with cached data in the test environment and not all airports are cached. You can find a list of airports included in the cached data in our guides section. When combining these searches with the [Airport Nearest Relevant API](https://developers.amadeus.com/self-service/category/flights/api-doc/airport-nearest-relevant){:target="\_blank"}, it is better to search using the city code rather than the airport code.
 
 ### Why are some origin and destination pairings not returning results?
 
-The Flight Inspiration Search and Flight Cheapest Date Search APIs are built on top of a pre-computed cache of selected origin-destination pairs. This is why, even in production, you cannot find all possible origin-destination pairs. If you need to access more results, you need to use the live Flight Offers Search API.
+The [Flight Inspiration Search](https://developers.amadeus.com/self-service/category/flights/api-doc/flight-inspiration-search){:target="\_blank"} and [Flight Cheapest Date Search](https://developers.amadeus.com/self-service/category/flights/api-doc/flight-cheapest-date-search){:target="\_blank"} APIs are built on top of a pre-computed cache of selected origin-destination pairs. This is why, even in production, you cannot find all possible origin-destination pairs. If you need to access more results, you need to use the live [Flight Offers Search API](https://developers.amadeus.com/self-service/category/flights/api-doc/flight-offers-search){:target="\_blank"}.
 
 ## Airport routes
 
@@ -218,18 +218,18 @@ This is the expected behavior. The IATA code in the response corresponds to the
 
 ### Why isn't the Airport Nearest Relevant API returning a specific airport near me?
 
-This may be because an airport is near a national boarder. If so, please check the API parameters for location. Also, please keep in mind that our Airport Nearest Relevant API excludes private and military airports.
+This may be because an airport is near a national boarder. If so, please check the API parameters for location. Also, please keep in mind that our [Airport Nearest Relevant API](https://developers.amadeus.com/self-service/category/flights/api-doc/airport-nearest-relevant){:target="\_blank"} excludes private and military airports.
 
 ## Flight Offers Search
 
 ### Why are the prices returned more expensive than on other websites?
 
-The API only returns published rates, which are the standard rates given by airlines. Amadeus then redistributes them to the travel agencies around the world. However, big players in the industry can negotiate their rates directly with the airlines, which can help them be more competitive or maximise returns made form selling tickets.
+The API only returns published rates, which are the standard rates given by airlines. Amadeus then redistributes them to the travel agencies around the world. However, big players in the industry can negotiate their rates directly with the airlines, which can help them be more competitive or maximise returns made from selling tickets.
 
 
 ### What does nonHomogeneous mean in the API response?
 
-PNRs are designed to be homogeneous, meaning that one PNR contains the same type of content (e.g., flights only) and number of passengers. However, nowadays, there can be a mix of different content, such as air and hotel. When nonHomogeneous is true, it means that a single PNR can contain records that would initially be split across different PNRs.
+PNRs are designed to be homogeneous, meaning that one PNR contains the same type of content (e.g., flights only) and number of passengers. However, nowadays, there can be a mix of different content, such as air and hotel. When `nonHomogeneous` is true, it means that a single PNR can contain records that would initially be split across different PNRs.
 
 ### Why the dataWindow parameter returns less results with I3D or I2D?
 
@@ -237,7 +237,7 @@ This is normal behaviour. Flight Offers Search returns the cheapest option for a
 
 ### How can I add a loyalty program to a booking?
 
-Flight Offers Price and SeatMap Display both accept frequent flyer information, so end-users can benefit from their loyalty program. When adding frequent flyer information, please remember that each airline policy is different, and some require additional information like passenger name, email, or phone number to validate the account. If validation fails, your user won’t receive their loyalty program advantages.
+[Flight Offers Price API](https://developers.amadeus.com/self-service/category/flights/api-doc/flight-offers-search){:target="\_blank"} and [SeatMap Display API](https://developers.amadeus.com/self-service/category/flights/api-doc/seatmap-display){:target="\_blank"} both accept frequent flyer information, so end-users can benefit from their loyalty program. When adding frequent flyer information, please remember that each airline policy is different, and some require additional information like passenger name, email, or phone number to validate the account. If validation fails, your user won’t receive their loyalty program advantages.
 
 ### POST and GET do not return the same results
 
@@ -245,7 +245,7 @@ By default the GET method does not return airlines blacklisted in Europe. Howeve
 
 ### How do I add bags to a check in bag for flight reservation? 
 
-You can add a checked-in bag to a flight booking using the ‘’additionalServices’’ element in the flight offer when calling Flight Offers Price. For more details, please check our guide on [adding baggage with Amadeus flight booking APIs](https://developers.amadeus.com/blog/add-baggage-amadeus-flight-booking-api). 
+You can add a checked-in bag to a flight booking using the `additionalServices` element in the flight offer when calling Flight Offers Price. For more details, please check our guide on [adding baggage with Amadeus flight booking APIs](https://developers.amadeus.com/blog/add-baggage-amadeus-flight-booking-api). 
 
 ### How do I add bags to a cabin bag for flight reservation? 
 
@@ -365,7 +365,7 @@ To access Flight Create Orders in production, you must have a contract signed wi
 
 ### How can I retrieve booking made with Flight Create Orders in Self-Service?
 
-You can consult booking made through Flight Create Orders using the Flight Order Management API. This API works using a unique identifier(the flight offer id) that is returned by the Flight Create Orders API.
+You can consult booking made through Flight Create Orders using the [Flight Order Management API](https://developers.amadeus.com/self-service/category/flights/api-doc/flight-order-management){:target="\_blank"}. This API works using a unique identifier(the flight offer id) that is returned by the [Flight Create Orders API](https://developers.amadeus.com/self-service/category/flights/api-doc/flight-create-orders){:target="\_blank"}.
 
 ### Does Amadeus pay a commission for flights booked with Flight Create Orders in Self-Service?
 
@@ -378,7 +378,7 @@ Getting the error message: `INVALID DATA RECEIVED`. Some of the data in the quer
 
 ### Why do I get the SEGMENT SELL FAILURE error?
 
-Getting the error message: `SEGMENT SELL FAILURE` means that you were not able to book the seat in the airline inventory. Most of the time, it comes from the flight being full. This often happens in the test environment, as you can perform many bookings without restrictions (no real payment). But the inventory is a copy of the real one, so if you book many seats, the inventory can get empty and you won't be able to book anymore. The good practice here is to use Flight Offers Price right before booking and avoid last-minute flights that tend to quickly get full.
+Getting the error message: `SEGMENT SELL FAILURE` means that you were not able to book the seat in the airline inventory. Most of the time, it comes from the flight being full. This often happens in the test environment, as you can perform many bookings without restrictions (no real payment). But the inventory is a copy of the real one, so if you book many seats, the inventory can get empty and you won't be able to book anymore. The good practice here is to use [Flight Offers Price](https://developers.amadeus.com/self-service/category/flights/api-doc/flight-offers-price){:target="\_blank"} right before booking and avoid last-minute flights that tend to quickly get full.
 
 ### How does payment work when I book a flight?
 
@@ -390,7 +390,7 @@ There are two things to consider regarding payments for flight booking:
 
 ### How can I cancel a flight?
 
-Cancellation is possible with the Flight Orders Management API as long as the booking has not been issued by the consolidator yet. If the booking has been issued, it will need to be canceled by the consolidator directly.
+Cancellation is possible with the [Flight Orders Management API](https://developers.amadeus.com/self-service/category/flights/api-doc/flight-order-management){:target="\_blank"} as long as the booking has not been issued by the consolidator yet. If the booking has been issued, it will need to be canceled by the consolidator directly.
 
 ### How to make the airline consolidator wait before issuing a ticket?
 
@@ -441,11 +441,11 @@ The current version of the Hotel Booking API only supports credit card payments.
 
 ### Can I markup the room prices?
 
-It is not possible to markup the prices of the hotel rooms with the current version of the Hotel Booking API. The reason is that the content we offer today in our Hotel Search/Book API is post-paid, meaning the traveler will pay directly at the hotel. The Hotel Booking API is here to enable making a reservation but not to pay directly. We are working on adding more hotel offers, especially offers that will be pre-paid, meaning you will be able to charge the travelers directly and add a markup. However, you still need to add a credit card while booking in case of cancellations or no-shows.
+It is not possible to markup the prices of the hotel rooms with the current version of the [Hotel Booking API](https://developers.amadeus.com/self-service/category/hotels/api-doc/hotel-booking){:target="\_blank"}. The reason is that the content we offer today in our Hotel Search/Book API is post-paid, meaning the traveler will pay directly at the hotel. The [Hotel Booking API](https://developers.amadeus.com/self-service/category/hotels/api-doc/hotel-booking){:target="\_blank"} is here to enable making a reservation but not to pay directly. We are working on adding more hotel offers, especially offers that will be pre-paid, meaning you will be able to charge the travelers directly and add a markup. However, you still need to add a credit card while booking in case of cancellations or no-shows.
 
 ### Payment providers and gateways
 
-The Hotel Booking API works by using the guest's payment information and sending it to a chosen hotel for the reservation. You can use a payment gateway in your app, but this will not change the way the API works. The hotels will never collect any money from you. Instead, the payments are always done at the time of checkout between the guest and the hotel. During the booking process, Amadeus passes the payment and guest information to the hotel but does not validate information, so it doesn’t play the role of payment gateway. Be sure to validate the payment and guest information as invalid information may result in the reservation being canceled. As soon as your application stores, transmits, or processes cardholder information, you will need to comply with the PCI Data Security Standard (PCI DSS). For more information, visit the [PCI Security Council website](https://www.pcisecuritystandards.org/merchants/).
+The [Hotel Booking API](https://developers.amadeus.com/self-service/category/hotels/api-doc/hotel-booking){:target="\_blank"} works by using the guest's payment information and sending it to a chosen hotel for the reservation. You can use a payment gateway in your app, but this will not change the way the API works. The hotels will never collect any money from you. Instead, the payments are always done at the time of checkout between the guest and the hotel. During the booking process, Amadeus passes the payment and guest information to the hotel but does not validate information, so it doesn’t play the role of payment gateway. Be sure to validate the payment and guest information as invalid information may result in the reservation being canceled. As soon as your application stores, transmits, or processes cardholder information, you will need to comply with the PCI Data Security Standard (PCI DSS). For more information, visit the [PCI Security Council website](https://www.pcisecuritystandards.org/merchants/).
 
 ### Why do I get 500 status code?
 
@@ -457,7 +457,7 @@ You can find the list of supported hotel chains in [our data collection](https:/
 
 ### What is considered a query?
 
-When you make an initial call to the Hotel Search API with a cityCode parameter, it is considered one query that returns 10 hotels. If you then click on each hotel to view room details and other information, you are making additional API calls using the second endpoint of the Hotel Search. Each hotel that you click on generates another API call. For example, if you click on 5 hotels to see room details, you will be making a total of 5 additional queries.
+When you make an initial call to the [Hotel Search API](https://developers.amadeus.com/self-service/category/hotels/api-doc/hotel-search){:target="\_blank"} with a `cityCode` parameter, it is considered one query that returns 10 hotels. If you then click on each hotel to view room details and other information, you are making additional API calls using the second endpoint of the Hotel Search. Each hotel that you click on generates another API call. For example, if you click on 5 hotels to see room details, you will be making a total of 5 additional queries.
 
 ### Do I need any legal documents to make a booking?
 
@@ -472,7 +472,7 @@ The room type code is a 3-character identifier that indicates the room type cate
 There is no way to cancel hotel bookings through the APIs. This needs to be done offline by ringing the hotels. 
 
 ### Why is Hotel Search returning empty responses ‘{"data": []}’?
-You are returning this because this specific hotel is closed or unavailable for this specific date. You can either try to change the check-in date or use the ''includeClosed'' parameter set to ''true''. The latter will return further information on the hotel, but you will not be able to book it.
+You are returning this because this specific hotel is closed or unavailable for this specific date. You can either try to change the check-in date or use the `includeClosed` parameter set to `true`. The latter will return further information on the hotel, but you will not be able to book it.
 
 ### Do you return hotel images?
 Hotel images are not available through our Self-Service catalog.
@@ -507,7 +507,7 @@ Refunds must be handled offline directly with your consolidator.
 
 ### Can I use multiple consolidators?
 
-Yes you can use different consolidator, but you will need to tell us so we can connect both your accounts. Once we open the access, you can decide where you want your booking to go using the ‘’queuingOfficeId’’ parameter in the Flight Create Orders request.
+Yes you can use different consolidator, but you will need to tell us so we can connect both your accounts. Once we open the access, you can decide where you want your booking to go using the `queuingOfficeId` parameter in the [Flight Create Orders API](https://developers.amadeus.com/self-service/category/flights/api-doc/flight-create-orders){:target="\_blank"} request.
 
 ## Destination Experiences
 
@@ -518,7 +518,7 @@ You can search and book activities with our [Tours and Activities API](https://d
 ## Cars & Transfers 
 
 ### Who are the providers available in the Car & Transfers APIs?
-The Transfers APIs will allow you to offer private transfers, hourly services, taxis, shared transfers, airport express, airport buses, private jets, and helicopter transfer. The API uses the following providers:
+The [Transfers APIs](https://developers.amadeus.com/self-service/category/cars-and-transfers){:target="\_blank"} will allow you to offer private transfers, hourly services, taxis, shared transfers, airport express, airport buses, private jets, and helicopter transfer. The API uses the following providers:
 
 | Name             | Code |
 |------------------|------|
diff --git a/docs/index.md b/docs/index.md
index 2dec5138..573e6900 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -6,7 +6,7 @@ Our main focus here is on the [Self-Service APIs](https://developers.amadeus.com
 
 ## What are the Self-Service APIs?
 
-Target independent developers and start-ups that wish to connect to Amadeus APIs in a quick and easy manner. You can access and start to test these new REST/JSON APIs in less than 3 minutes, and get quick access to production data with a flexible pay-as-you-go pricing model. Please note that the catalog includes some selected APIs, although we will be constantly releasing new APIs. Currently, you can find APIs around flights, destination Experiences, cars & transfers, market insights, hotels, and itinerary management.
+Target independent developers and start-ups that wish to connect to Amadeus APIs in a quick and easy manner. You can access and start to test these new REST/JSON APIs in less than 3 minutes, and get quick access to production data with a flexible pay-as-you-go pricing model. Please note that the catalog includes some selected APIs, although we will be constantly releasing new APIs. Currently, you can find APIs around flights, destination experiences, cars & transfers, market insights, hotels, and itinerary management.
 
 Self-Service users have at their disposal detailed documentation, guides, and SDKs to be able to integrate the APIs in their apps. 
 
diff --git a/docs/quick-start.md b/docs/quick-start.md
index 264d057d..c621ec19 100644
--- a/docs/quick-start.md
+++ b/docs/quick-start.md
@@ -7,7 +7,7 @@ The first step to start using Amadeus Self-Service APIs is to register and creat
 * Open the [Amadeus Developers Portal](https://developers.amadeus.com/){:target="\_blank"}.
 * Click on [Register](https://developers.amadeus.com/register){:target="\_blank"}.
 * Complete the form using a valid email address and click on the `Create account` button. An automatic confirmation email will be sent to the email address you provided.
-* In the confirmation email you receive, click on `Activate your account`. 
+* Click on the `Activate your account` link in the confirmation email you receive.
 
 You can now log in to the portal with your new credentials! Welcome to **Amadeus for Developers**!
 
@@ -41,13 +41,14 @@ For our first call, let's get a list of possible destinations from Paris for a m
 
 ### Creating the Request
 
-Before making your first API call, you need to get your **access token**. For security purposes, we implemented the `oauth2` process that will give you an access token based on your `API Key` and `API Secret.` To retrieve the **token**, you need to send a `POST` request to the endpoint `/v1/security/oauth2/token`with the correct `Content-Type` header and body. Replace `{client_id}` with your API Key and `{client_secret}` with your API Secret in the command below and execute it:
+Before making your first API call, you need to get your **access token**. For security purposes, we implemented the `oauth2` process that will give you an access token based on your `API Key` and `API Secret.` To retrieve the **token**, you need to send a `POST` request to the endpoint `/v1/security/oauth2/token`with the correct `Content-Type` header and body. 
 
 ```bash
 curl "https://test.api.amadeus.com/v1/security/oauth2/token" \
      -H "Content-Type: application/x-www-form-urlencoded" \
-     -d "grant_type=client_credentials&client_id={client_id}&client_secret={client_secret}"
+     -d "grant_type=client_credentials&client_id=<YOUR-CLIENT-ID>&client_secret=<YOUR-CLIENT-SECRET>"
 ```
+Replace `<YOUR-CLIENT-ID>` with your API Key and `<YOUR-CLIENT-SECRET>` with your API Secret in the command above and execute it.
 
 !!! warning
     Please take a look at our [Authorization guide](API-Keys/authorization.md) to understand how the process works in depth.
@@ -58,8 +59,10 @@ Our call is therefore:
 
 ```bash
 curl 'https://test.api.amadeus.com/v1/shopping/flight-destinations?origin=PAR&maxPrice=200' \
-      -H 'Authorization: Bearer ABCDEFGH12345'
+      -H 'Authorization: Bearer <YOUR-BEARER-TOKEN>'
 ```
+Replace `<YOUR-BEARER-TOKEN>` with the token you received from the authorization call.
+
 
 Note how we add the `Authorization` header to the request with the value `Bearer` string concatenated with the token previously requested.
 
diff --git a/docs/resources/cars-transfers.md b/docs/resources/cars-transfers.md
index 13d737f6..dd5f3650 100644
--- a/docs/resources/cars-transfers.md
+++ b/docs/resources/cars-transfers.md
@@ -15,7 +15,7 @@ Have a look at our dedicated [Postman collection](../developer-tools/postman.md)
 
 ## Search for a transfer
 
-The search is carried out through a POST API call to /shopping​/transfer-offers. The API request includes parameters like the start and end locations, type of transfer, number of passengers, provider codes, and other optional parameters.
+The search is carried out through a POST API call to `/shopping/transfer-offers`. The API request includes parameters like the start and end locations, type of transfer, number of passengers, provider codes, and other optional parameters.
 
 
 In the following example request, we have multiple parameters each with its own specific meaning and structure:
@@ -469,6 +469,7 @@ The main endpoint URL is `https://test.api.amadeus.com/v1/ordering/transfer-orde
   }
 }
 ```
+
 - **`data`**: Root level object encapsulating all the necessary data for the transfer order.
     - **`note`**: A string containing a note intended for the driver. (Example: "Note to driver")
     - **`passengers`**: An array of objects, each representing a passenger with the following properties:
@@ -528,10 +529,11 @@ The [Transfer Management API](https://developers.amadeus.com/self-service/catego
 
 For example:
 
-`POST https://test.api.amadeus.com/v1/ordering/transfer-orders/{orderId}/transfers/cancellation`
-
+```bash
+POST https://test.api.amadeus.com/v1/ordering/transfer-orders/<orderId>/transfers/cancellation
+```
 
-The `{orderId}` in the URL should be replaced with the unique identifier of the order that was previously generated when the order was created. For instance, the `orderId` could be something like `0cb11574-4a02-11e8-842f-0ed5f89f718b`.
+Replace the `<orderId>` with the unique identifier of the order that was previously generated when the order was created. For instance, the `orderId` could be something like `0cb11574-4a02-11e8-842f-0ed5f89f718b`.
 
 The `confirmNbr` is a unique confirmation number associated with the transfer that is to be cancelled. 
 
diff --git a/docs/resources/destination-experiences.md b/docs/resources/destination-experiences.md
index 551d36bd..24d5628a 100644
--- a/docs/resources/destination-experiences.md
+++ b/docs/resources/destination-experiences.md
@@ -77,7 +77,7 @@ As you can see, the API returns a unique activity Id along with the activity nam
 - `name` and `shortDescription` contains the information about the activity. 
 - `geoCode` is a structure that contains geolocation information: latitude and longitude of the location.
 - `rating` is a rating of the activity. 
-- `pictures` and `booking link` are external links to check the relevant pictures and to go to the booking URL from the activity provider.
+- `pictures` and `bookingLink` are external links to check the relevant pictures and to go to the booking URL from the activity provider.
 - `price` is the price of the fare, which can be alpha-numeric. Ex- 500.20 or 514.13A, `A` signifies additional collection.
 
 ### Retrieve by Id
@@ -147,4 +147,4 @@ The results are probably rather predictable:
 
 First of all we see the French capital at the top of the list. The second result refers to the town Le Touquet-Paris-Plage, whose official name contains three letters that match our keyword. If we want to see more results, we can always adjust the `max` number of results.
 
-The main difference between the [Airport & City Search API](https://developers.amadeus.com/self-service/category/air/api-doc/airport-and-city-search){:target="\_blank"} and [City Search API](https://developers.amadeus.com/self-service/category/trip/api-doc/city-search){:target="\_blank"} is that the [Airport & City Search API](https://developers.amadeus.com/self-service/category/air/api-doc/airport-and-city-search){:target="\_blank"} only shows cities that have an airport, while the [City Search API](https://developers.amadeus.com/self-service/category/trip/api-doc/city-search){:target="\_blank"} retrieves any city that matches a keyword.
\ No newline at end of file
+The main difference between the [Airport & City Search API](https://developers.amadeus.com/self-service/category/air/api-doc/airport-and-city-search){:target="\_blank"} and [City Search API](https://developers.amadeus.com/self-service/category/trip/api-doc/city-search){:target="\_blank"} is that the [Airport & City Search API](https://developers.amadeus.com/self-service/category/air/api-doc/airport-and-city-search){:target="\_blank"} only shows cities that have an airport, while the [City Search API](https://developers.amadeus.com/self-service/category/trip/api-doc/city-search){:target="\_blank"} retrieves any city that matches a keyword.
diff --git a/docs/resources/flights.md b/docs/resources/flights.md
index 1f812b1f..2a6fc50e 100644
--- a/docs/resources/flights.md
+++ b/docs/resources/flights.md
@@ -403,11 +403,15 @@ The `POST` endpoint consumes JSON data in the format described below. So, instea
 
 If you want your search to return flights with only specified airlines, you can use the parameter `includedAirlineCodes` to consider specific airlines. For example, there is a traveler who wants to travel from Berlin to Athens only with Aegean Airlines (A3): 
 
-`GET https://test.api.amadeus.com/v2/shopping/flight-offers?max=3&adults=1&includedAirlineCodes=A3&originLocationCode=BER&destinationLocationCode=ATH&departureDate=2022-12-06`
+```bash 
+GET https://test.api.amadeus.com/v2/shopping/flight-offers?max=3&adults=1&includedAirlineCodes=A3&originLocationCode=BER&destinationLocationCode=ATH&departureDate=2022-12-06
+```
 
 With the parameter `excludedAirlineCodes` you can ignore specific airlines. For example, there is a traveler who wants to travel from Berlin to Athens ignoring both Aegean Airlines (A3) and Iberia (IB):
 
-`GET https://test.api.amadeus.com/v2/shopping/flight-offers?max=3&adults=1&excludedAirlineCodes=A3,IB&originLocationCode=BER&destinationLocationCode=ATH&departureDate=2021-09-06`
+```bash
+GET https://test.api.amadeus.com/v2/shopping/flight-offers?max=3&adults=1&excludedAirlineCodes=A3,IB&originLocationCode=BER&destinationLocationCode=ATH&departureDate=2021-09-06
+```
 
 #### Interactive code examples
 
@@ -427,14 +431,15 @@ Let’s look at flight offers for a Madrid-New York round trip (limiting to four
 
 ```bash
 curl --request GET \
-     --header 'Authorization: Bearer <token>' \
+     --header 'Authorization: Bearer <YOUR-BEARER-TOKEN>' \
      --url https://test.api.amadeus.com/v2/shopping/flight-offers\?origin\=MAD\&destination\=NYC\&departureDate\=2019-08-24\&returnDate\=2019-09-19\&adults\=1 \
 | curl --request POST \
        --header 'content-type: application/json' \
-       --header 'Authorization: Bearer <token>' \
+       --header 'Authorization: Bearer <YOUR-BEARER-TOKEN>' \
        --header 'X-HTTP-Method-Override: POST' \
        --url https://test.api.amadeus.com/v2/shopping/flight-offers/prediction --data @-
 ```
+Replace `<YOUR-BEARER-TOKEN>` with the token you received from the authorization call.
 
 The prediction API returns the same content as the Low Fare search with the
 addition of the `choiceProbability` field for each flight offer element.
@@ -558,9 +563,10 @@ The request will look like this:
 
 ```bash
 curl --request GET \
-     --header 'Authorization: Bearer <token>' \
+     --header 'Authorization: Bearer <YOUR-BEARER-TOKEN>' \
      --url https://test.api.amadeus.com/v1/airport/direct-destinations?departureAirportCode=MAD&max=10 \
 ```
+Replace `<YOUR-BEARER-TOKEN>` with the token you received from the authorization call.
 
 So we can see the the following results:
 
@@ -645,9 +651,10 @@ The request will look like this:
 
 ```bash
 curl --request GET \
-     --header 'Authorization: Bearer <token>' \
+     --header 'Authorization: Bearer <YOUR-BEARER-TOKEN>' \
      --url https://test.api.amadeus.com/v1/airline/destinations?airlineCode=BA&max=2 \
 ```
+Replace `<YOUR-BEARER-TOKEN>` with the token you received from the authorization call.
 
 So we can see the the following results:
 
@@ -683,9 +690,10 @@ If we need to know the IATA code for a particular airline but only have the airl
 
 ```bash
 curl --request GET \
-     --header 'Authorization: Bearer <token>' \
+     --header 'Authorization: Bearer <YOUR-BEARER-TOKEN>' \
      --url https://test.api.amadeus.com/v1/reference-data/airlines?airlineCodes=BA \
 ```
+Replace `<YOUR-BEARER-TOKEN>` with the token you received from the authorization call.
 
 The response is pretty straightforward:
 
@@ -869,8 +877,7 @@ You can build the request by passing the flight-offer object from the [Flight Of
 POST https://test.api.amadeus.com/v1/shopping/flight-offers/upselling
 ```
 
-Please not that the `X-HTTP-Method-Override` header parameter is required to make this call.
-
+Please note that the `X-HTTP-Method-Override` header parameter is required to make this call.
 
 ```json
 { 
@@ -1010,7 +1017,7 @@ Please not that the `X-HTTP-Method-Override` header parameter is required to mak
 }  
 ```
 
-The API will procide the following JSON in the response:
+The API will provide the following JSON in the response:
 
 ```json
 {
@@ -1166,7 +1173,9 @@ The [Travel Recommendations API](https://developers.amadeus.com/self-service/cat
 
 For example, for a traveler based in San Francisco who has searched for multiple flights to Barcelona, what other similar destinations the API could recommend? The API takes as input the country of the traveler and the IATA code of the city that was searched, in our case this will be US and BCN respectively. 
 
-`GET https://test.api.amadeus.com/v1/reference-data/recommended-locations?cityCodes=BCN&travelerCountryCode=US`
+```bash
+GET https://test.api.amadeus.com/v1/reference-data/recommended-locations?cityCodes=BCN&travelerCountryCode=US
+```
 
 The response will look like this:
 
@@ -1221,8 +1230,9 @@ With the [Airport Nearest Relevant API](https://developers.amadeus.com/self-serv
     To get the latitude and longitude of a city you can use the [Airport & City Search API](https://developers.amadeus.com/self-service/category/air/api-doc/airport-and-city-search){:target="\_blank"} using the city's IATA code.
 
 Let's call the [Airport Nearest Relevant API](https://developers.amadeus.com/self-service/category/air/api-doc/airport-nearest-relevant){:target="\_blank"} to find airports within the 500km radius of Madrid.
-
-`GET https://test.api.amadeus.com/v1/reference-data/locations/airports?latitude=40.416775&longitude=-3.703790&radius=500`
+```bash
+GET https://test.api.amadeus.com/v1/reference-data/locations/airports?latitude=40.416775&longitude=-3.703790&radius=500
+```
 
 A part of the response looks like:
  
@@ -1263,8 +1273,9 @@ A part of the response looks like:
 What we want to do at this point, is to find the cheapest dates for all these destinations. 
 
 We can do this by calling the [Flight Cheapest Date Search API](https://developers.amadeus.com/self-service/category/air/api-doc/flight-cheapest-date-search){:target="\_blank"} which finds the cheapest dates to travel from one city to another. Let's see, for example, the cheapest dates to fly to Barcelona in November 2021. 
-
-`GET https://test.api.amadeus.com/v1/shopping/flight-dates?origin=MAD&destination=BCN&departureDate=2021-05-01,2021-05-30`
+```bash
+GET https://test.api.amadeus.com/v1/shopping/flight-dates?origin=MAD&destination=BCN&departureDate=2021-05-01,2021-05-30
+```
 
 ```json
 {
@@ -1314,8 +1325,9 @@ As you can see above, in the results we have a list of dates for a roundtrip fro
 
 In the last step, we want to let the traveler perform a flight search for any of the above dates that are convenient for them. That is very easy with our APIs, as the [Flight Cheapest Date Search API](https://developers.amadeus.com/self-service/category/air/api-doc/flight-cheapest-date-search){:target="\_blank"} for each result contains a link to the [Flight Offers Search API](https://developers.amadeus.com/self-service/category/air/api-doc/flight-offers-search){:target="\_blank"}. For example, if we want to perform a flight search for the first result, we only have to take the link provided and make an API call:
 
-
-`GET https://test.api.amadeus.com/v2/shopping/flight-offers?originLocationCode=MAD&destinationLocationCode=BCN&departureDate=2021-05-29&returnDate=2021-06-11&adults=1&nonStop=false`
+```bash
+GET https://test.api.amadeus.com/v2/shopping/flight-offers?originLocationCode=MAD&destinationLocationCode=BCN&departureDate=2021-05-29&returnDate=2021-06-11&adults=1&nonStop=false
+```
 
 
 ### Search for a city that has an airport
@@ -1518,7 +1530,7 @@ This is what we get in the response:
 }
 ```
 
-By default the price will be shown in Euros. In this example we can see that the lowest price for such ticket should be 29.59 Euros and the highest 198.15 Euros. The first, medium and trird choices give you an idea about the possible price ranges for this flight.
+By default the price will be shown in Euros. In this example we can see that the lowest price for such ticket should be 29.59 Euros and the highest 198.15 Euros. The first, medium and third choices give you an idea about the possible price ranges for this flight.
 
 We also have an option to request the result in a different currency. This is done by using the `currencyCode` parameter, which is an ISO 4217 format currency code. In addition, we can specify whether we are inquiring about a round trip or a one way ticket.
 
@@ -1711,7 +1723,8 @@ For each seat, the [Seatmap Display API](https://developers.amadeus.com/self-ser
 - `BLOCKED` – the seat is not occupied but isn’t available to book for the user. This is usually due to the passenger type (e.g., children may not sit in exit rows) or their fare class (e.g., some seats may be reserved for flyers in higher classes).
 - `OCCUPIED` – the seat is  occupied and unavailable to book.
 
-If a flight is fully booked, the API returns an OCCUPIED status for all seats. In most cases, fully booked flights are filtered out during search with the [Flight Offers Search API](https://developers.amadeus.com/self-service/category/air/api-doc/flight-offers-search){:target="\_blank"} or when confirming the price with the [Flight Offers Price API](https://developers.amadeus.com/self-service/category/air/api-doc/flight-offers-price){:target="\_blank"}. The [Flight Create Orders API](https://developers.amadeus.com/self-service/category/air/api-doc/flight-create-orders){:target="\_blank"} returns an error message if you try to book an unavailable seat. For more information on the booking flow, check out how to build a flight booking engine.
+If a flight is fully booked, the API returns an OCCUPIED status for all seats. In most cases, fully booked flights are filtered out during search with the [Flight Offers Search API](https://developers.amadeus.com/self-service/category/air/api-doc/flight-offers-search){:target="\_blank"} or when confirming the price with the [Flight Offers Price API](https://developers.amadeus.com/self-service/category/air/api-doc/flight-offers-price){:target="\_blank"}. The [Flight Create Orders API](https://developers.amadeus.com/self-service/category/air/api-doc/flight-create-orders){:target="\_blank"} returns an error message if you try to book an unavailable seat. For more information on the booking flow, check out [how to build a flight booking engine](https://developers.amadeus.com/get-started/create-a-flight-booking-engine-651).
+
 
 Once your user has selected their seat, the next step is to add the desired seat to the flight offer and prepare them for booking.
 
@@ -2054,9 +2067,10 @@ Suppose we are building an app with an integrated check-in flow for a particular
 
 ```bash
 curl --request GET \
-     --header 'Authorization: Bearer <token>' \
+     --header 'Authorization: Bearer <YOUR-BEARER-TOKEN>' \
      --url https://test.api.amadeus.com/v2/reference-data/urls/checkin-links?airlineCode=BA&language=en-GB \
 ```
+Replace `<YOUR-BEARER-TOKEN>` with the token you received from the authorization call.
 
 This is what we get in the response:
 
@@ -2098,7 +2112,7 @@ Here we've got a dedicated link for web applications, a dedicated link for mobil
 
 Just as you can help users book a flight with the [Flight Create Orders API](https://developers.amadeus.com/self-service/category/air/api-doc/flight-create-orders){:target="\_blank"}, you can now also help them cancel their reservations with the [Flight Order Management](https://developers.amadeus.com/self-service/category/air/api-doc/flight-order-management){:target="\_blank"} API. However, you have a limited window of time to cancel via API. If you’re working with an airline consolidator for ticketing, cancellations via API are generally only allowed while the order is queued for ticketing. Once the ticket has been issued, you’ll have to contact your consolidator directly to handle the cancellation.
 
-To call the [Flight Order Management API](https://developers.amadeus.com/self-service/category/air/api-doc/flight-order-management){:target="\_blank"}, you have pass as a parameter the flight-orderId from the [Flight Create Orders API](https://developers.amadeus.com/self-service/category/air/api-doc/flight-create-orders){:target="\_blank"}.
+To call the [Flight Order Management API](https://developers.amadeus.com/self-service/category/air/api-doc/flight-order-management){:target="\_blank"}, you must pass as a parameter the flight-orderId from the [Flight Create Orders API](https://developers.amadeus.com/self-service/category/air/api-doc/flight-create-orders){:target="\_blank"}.
 
 To retrieve the flight order data:
 
@@ -2117,7 +2131,7 @@ DELETE https://test.api.amadeus.com/v1/booking/flight-orders/eJzTd9f3NjIJdzUGAAp
 
 With the [Flight Order Management API](https://developers.amadeus.com/self-service/category/air/api-doc/flight-order-management){:target="\_blank"} you can consult and check your flight reservation. 
 
-To call the [Flight Order Management API](https://developers.amadeus.com/self-service/category/air/api-doc/flight-order-management){:target="\_blank"}, you have pass as a parameter the flight-orderId from the [Flight Create Orders API](https://developers.amadeus.com/self-service/category/air/api-doc/flight-create-orders){:target="\_blank"}, such as:
+To call the [Flight Order Management API](https://developers.amadeus.com/self-service/category/air/api-doc/flight-order-management){:target="\_blank"}, you must pass as a parameter the flight-orderId from the [Flight Create Orders API](https://developers.amadeus.com/self-service/category/air/api-doc/flight-create-orders){:target="\_blank"}, such as:
 
 ```bash
 GET https://test.api.amadeus.com/v1/booking/flight-orders/eJzTd9f3NjIJdzUGAAp%2fAiY
@@ -2130,7 +2144,7 @@ GET https://test.api.amadeus.com/v1/booking/flight-orders/eJzTd9f3NjIJdzUGAAp%2f
 Self-Service users must work with an airline consolidator that can issue
 tickets on your behalf. In that case, the payment is not processed by the API
 but directly between you and the consolidator. Adding a form of payment to
-the [Flight Create Orders API](https://developers.amadeus.com/self-service/category/air/api-doc/flight-create-orders){:target="\_blank"} will be rejected by error INVALID FORMAT.
+the [Flight Create Orders API](https://developers.amadeus.com/self-service/category/air/api-doc/flight-create-orders){:target="\_blank"} will be rejected by error `INVALID FORMAT`.
 
 ### Price discrepancy 
 
diff --git a/docs/resources/hotels.md b/docs/resources/hotels.md
index e16305c4..a9cabf78 100644
--- a/docs/resources/hotels.md
+++ b/docs/resources/hotels.md
@@ -19,7 +19,13 @@ Let's learn how to get started and help your users book the perfect rooms at ove
 
 ### Get a list of hotels by location 
 
-First, users should be able to search hotels for a given location. The [Hotel List API](https://developers.amadeus.com/self-service/category/hotel/api-doc/hotel-list/api-reference){:target="\_blank"} returns a list of hotels based on a city, a geographic code or the unique Amadeus hotel Id. To answer a question, such as **"what are the hotels closed to the city hall?"** the `Hotel List API` has three endpoints to utilize based on your search criteria. It returns `hotel name`, `location`, and `hotel id` for you to proceed to the next steps of the hotel search. 
+First, users should be able to search hotels for a given location. The [Hotel List API](https://developers.amadeus.com/self-service/category/hotel/api-doc/hotel-list/api-reference){:target="\_blank"} returns a list of hotels based on a city, a geographic code or the unique Amadeus hotel Id. To answer a question, such as **"what are the hotels close to the city hall?"** the `Hotel List API` has three endpoints to utilize based on your search criteria. Each endpoint will return
+
+- **Hotel Name** as `name`
+- **Location** as `geoCode` containing a `latitude` and `longitude`
+- **Hotel Id** as `hotelId`
+
+Use these to proceed to the next steps of the hotel search.
 
 The [Hotel List API](https://developers.amadeus.com/self-service/category/hotel/api-doc/hotel-list/api-reference){:target="\_blank"} contains the following endpoints:
 
@@ -88,7 +94,7 @@ If you are looking for hotels with certain amenities, such as a spa or a swimmin
 The query to find a hotel in Paris with a swimming pool will look like this:
 
 ```bash
-GET https://test.api.amadeus.com/v1/reference-data/locations/hotels/by-city?cityCode=PAR&chainCodes=&amenities=SWIMMING_POOL
+GET https://test.api.amadeus.com/v1/reference-data/locations/hotels/by-city?cityCode=PAR&amenities=SWIMMING_POOL
 ```
 
 If stars rating is important for the search, you can include up to four values separated by comma in the `ratings` parameter:
@@ -184,7 +190,7 @@ If you are looking for hotels with certain amenities, such as a spa or a swimmin
 The query to find a hotel in Paris with a swimming pool will look like this:
 
 ```bash
-GET https://test.api.amadeus.com/v1/reference-data/locations/hotels/by-geocode?latitude=41.397158&longitude=2.160873&chainCodes=&amenities=SWIMMING_POOL&ratings=
+GET https://test.api.amadeus.com/v1/reference-data/locations/hotels/by-geocode?latitude=41.397158&longitude=2.160873&amenities=SWIMMING_POOL&ratings=
 ```
 
 If stars rating is important for the search, you can include up to four values separated by comma in the `ratings` parameter:
@@ -232,7 +238,7 @@ GET https://test.api.amadeus.com/v1/reference-data/locations/hotels/by-hotels?ho
 
 ### Interactive code examples 
 
-Check out this [interactive code example](../examples/live-examples.md) which provides a hotel search form to help you build your app. You can easily customize it and use the Hotel Search API to get the cheapest flight offers.
+Check out this [interactive code example](../examples/live-examples.md) which provides a hotel search form to help you build your app. You can easily customize it and use the Hotel Search API to get the cheapest hotel offers.
 
 ### Autocomplete Hotel Names
 
@@ -376,7 +382,7 @@ GET https://test.api.amadeus.com/v3/shopping/hotel-offers?hotelIds=HLPAR266&adul
 The API returns a list of `offers` objects containing the price of the cheapest available room as well as information including the room description and payment policy. 
 
 !!! Note
-    The response of `Hotel Search V3` contains real-time data, so you don't need an additional validation step anymore. However, as there are thousands of people reserving hotels at any given second, the availability of a given room may change between the moment you search and the moment you decide to book. It is therefore advised that you proceed with booking **as soon as possible** or **add a validation step** by searching by `offerid` described below.
+    The response of `Hotel Search V3` contains real-time data, so you don't need an additional validation step anymore. However, as there are thousands of people reserving hotels at any given second, the availability of a given room may change between the moment you search and the moment you decide to book. It is therefore advised that you proceed with booking **as soon as possible** or **add a validation step** by searching by `offerId` described below.
 
 ```json
 {
@@ -487,9 +493,9 @@ The API returns a list of `offers` objects containing the price of the cheapest
 !!! information
     The commission information returned by the `commission` parameter is for information only. Hotels can voluntary provide commission. They are only obliged to do it if you are a IATA certified travel agency, in which case you need to [contact](https://developers.amadeus.com/support/contact-us-self-service) our Enterprise APIs team to get access to our REST/JSON booking APIs. Once you have moved to the [production environment](../API-Keys/moving-to-production.md) and obtained the offerId, it will be necessary for you to directly communicate with the hotel to receive the commission on this offer.
 
-If the time between displaying prices and booking the room is long enough to allow others to book the same room, you can consider requesting [Hotel Search API](https://developers.amadeus.com/self-service/category/hotel/api-doc/hotel-search/api-reference){:target="\_blank"} again with the `offerid` that you got before. This is not mandatory as you always will see if the offer is available or not when you try to book the offer.
+If the time between displaying prices and booking the room is long enough to allow others to book the same room, you can consider requesting [Hotel Search API](https://developers.amadeus.com/self-service/category/hotel/api-doc/hotel-search/api-reference){:target="\_blank"} again with the `offerId` that you got before. This is not mandatory as you always will see if the offer is available or not when you try to book the offer.
 
-An example to request the offer information with `offer id`: 
+An example to request the offer information with `offerId`: 
 
 ```bash
 GET https://test.api.amadeus.com/v3/shopping/hotel-offers/ZBC0IYFMFV
@@ -562,11 +568,11 @@ As soon as your application stores transmits, or processes cardholder informatio
 
 ## Guide for multiple hotel rooms
 
-Now that we have gone through the hotel booking flow, you may wonder how to proceed to booking more than two rooms in a hotel. 
+Now that we have gone through the hotel booking flow, you may wonder how to proceed to booking more than one room in a hotel. 
 
 ### Check availability and prices for multiple rooms 
 
-The first step to booking multiple rooms is to search for hotels in your destination with the desired number of available rooms. You can do this by specifying the `roomQuantity` parameter when you call the [Hotel Search API](https://developers.amadeus.com/self-service/category/hotel/api-doc/hotel-search/api-reference){:target="\_blank"} using the `hotelid` that you got from the [Hotel List API](https://developers.amadeus.com/self-service/category/hotel/api-doc/hotel-list/api-reference){:target="\_blank"}. 
+The first step to booking multiple rooms is to search for hotels in your destination with the desired number of available rooms. You can do this by specifying the `roomQuantity` parameter when you call the [Hotel Search API](https://developers.amadeus.com/self-service/category/hotel/api-doc/hotel-search/api-reference){:target="\_blank"} using the `hotelId` that you got from the [Hotel List API](https://developers.amadeus.com/self-service/category/hotel/api-doc/hotel-list/api-reference){:target="\_blank"}. 
 
 Here is an example of a search in Hilton Paris for **two rooms** for **three adults**: 
 
diff --git a/docs/resources/market-insight.md b/docs/resources/market-insight.md
index c9ad690f..0fefee8d 100644
--- a/docs/resources/market-insight.md
+++ b/docs/resources/market-insight.md
@@ -133,10 +133,10 @@ Response to the busines period from a given city :
 
 ### Sorting
 
-Sorting is enabled on the "top destinations" endpoints. 
+Sorting is enabled on the [Top Destinations](https://developers.amadeus.com/self-service/category/market-insights/api-doc/flight-most-traveled-destinations/api-reference) endpoints. 
 
-- analytics.flights.score - sort destination by flights score (decreasing)
-- analytics.travelers.score - sort destination by traveler's score (decreasing)
+- `analytics.flights.score` - sort destination by flights score (decreasing)
+- `analytics.travelers.score` - sort destination by traveler's score (decreasing)
 
 For example : 
 
@@ -155,4 +155,4 @@ By default, statistics are given on travelers ARRIVING in the city.
 
 ```bash
 GET https://test.api.amadeus.com/v1/travel/analytics/air-traffic/busiest-period?cityCode=PAR&period=2018&direction=ARRIVING
-```
\ No newline at end of file
+```