Self-Service Mapping

Send a list of listings to get the supplier to map them themselves

To use this capability, add octo/mappings to your Octo-Capabilities header.

This capability allows you to send a "mapping sheet" of products that you need to map. This is then given to the supplier in a user-friendly form they can select which product each item maps to in their Ventrata system. Once the mapping has been set a webhook URL is called to notify your system of the change.

The mappings endpoints are available under /octo.

Update Mappings

put

Send the complete list of mappings for this connection.

The request upserts by resellerReference and removes any existing mappings not included in the payload.

Body

application/json

Responses

200

Returns the updated mapping rows.

application/json

From capability octo/mappings.

resellerReferencestringRequired

Reseller reference value.

Example: RES-BOOK-10045

resellerStatusstring · nullableOptional

Reseller status value.

Example: CONFIRMED

resellerProductstring · nullableOptional

Reseller product value.

Example: grand-canyon-day-tour

productIdstring · nullableOptional

Product identifier.

Example: e7cc8bb4-8d1c-4848-8824-5dbedb718681

optionIdstring · nullableRequired

Option identifier.

Example: 94cdd032-3d32-416d-b0a4-abf8b7495b8b

unitIdstring · nullableOptional

Unit identifier.

Example: unit_adult

optionRequiredbooleanOptional

Whether option required is enabled.

Example: true

unitRequiredbooleanOptional

Whether unit required is enabled.

Example: true

validityDaysinteger · nullableOptional

Validity days numeric value.

Example: 2

webhookUrlstring · uri · nullableOptional

Webhook url URL.

Example: https://www.city-sightseeing.com

put

/mappings

HTTPcURLJavaScriptPython

PUT /octo/mappings HTTP/1.1
Host: api.ventrata.com
Content-Type: application/json
Accept: */*
Content-Length: 354

{
  "mappings": [
    {
      "resellerReference": "RES-BOOK-10045",
      "resellerStatus": "CONFIRMED",
      "resellerProduct": "grand-canyon-day-tour",
      "productId": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
      "optionId": "94cdd032-3d32-416d-b0a4-abf8b7495b8b",
      "unitId": "unit_adult",
      "optionRequired": true,
      "unitRequired": true,
      "validityDays": 2,
      "webhookUrl": "https://www.city-sightseeing.com"
    }
  ]
}

200

Returns the updated mapping rows.

[
  {
    "resellerReference": "RES-BOOK-10045",
    "resellerStatus": "CONFIRMED",
    "resellerProduct": "grand-canyon-day-tour",
    "productId": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
    "optionId": "94cdd032-3d32-416d-b0a4-abf8b7495b8b",
    "unitId": "unit_adult",
    "optionRequired": true,
    "unitRequired": true,
    "validityDays": 2,
    "webhookUrl": "https://www.city-sightseeing.com"
  }
]

Body must be a JSON array of mapping rows.

See the PUT /mappings operation above for request schema examples.

resellerReference is required on each item. Items are upserted by resellerReference, and any existing mappings not included in the array are removed.

Whenever a product in your system for this supplier has been changed, updated or deleted, you should repeat this request with all mappings. PUT synchronizes the full set for the connection.

After you make the request and new mappings are added, Ventrata sends a notification to the supplier to complete them.

Once the supplier chooses a product and option for a mapping, Ventrata sends a POST request to the URL provided in webhookUrl for that mapping row. The webhook body follows the mapping object schema and includes resolved productId, optionId, and unitId values.

The unitId and optionId will be null in the webhook request body if we set unitRequired and optionRequired to false respectively on the original mappings request.

Your response to this request must be 2XX (for example 200 OK), otherwise we retry until we receive a 2XX response.

List Mappings

get

Gets the current state of all mappings for the connection.

Query parameters

optionIdstringRequired

Filter by one mapped option ID (DEFAULT supported).

Example: 94cdd032-3d32-416d-b0a4-abf8b7495b8b

resellerReferencestringOptional

Filter by one reseller reference.

Example: RES-BOOK-10045

resellerStatusstringOptional

Filter by reseller status.

Example: CONFIRMED

productIdstringOptional

Filter by one mapped product ID.

Example: e7cc8bb4-8d1c-4848-8824-5dbedb718681

productIds[]arrayOptional

Filter by multiple mapped product IDs.

Example: [{"id":"89fe0192-ddcd-430a-b285-e1396a4725d2","title":"Sample"}]

optionIds[]arrayOptional

Filter by multiple mapped option IDs (DEFAULT supported).

Example: [{"id":"89fe0192-ddcd-430a-b285-e1396a4725d2","title":"Sample"}]

Responses

200

Returns an array of mapping rows.

application/json

From capability octo/mappings.

resellerReferencestringRequired

Reseller reference value.

Example: RES-BOOK-10045

resellerStatusstring · nullableOptional

Reseller status value.

Example: CONFIRMED

resellerProductstring · nullableOptional

Reseller product value.

Example: grand-canyon-day-tour

productIdstring · nullableOptional

Product identifier.

Example: e7cc8bb4-8d1c-4848-8824-5dbedb718681

optionIdstring · nullableRequired

Option identifier.

Example: 94cdd032-3d32-416d-b0a4-abf8b7495b8b

unitIdstring · nullableOptional

Unit identifier.

Example: unit_adult

optionRequiredbooleanOptional

Whether option required is enabled.

Example: true

unitRequiredbooleanOptional

Whether unit required is enabled.

Example: true

validityDaysinteger · nullableOptional

Validity days numeric value.

Example: 2

webhookUrlstring · uri · nullableOptional

Webhook url URL.

Example: https://www.city-sightseeing.com

get

/mappings

HTTPcURLJavaScriptPython

GET /octo/mappings?optionId=text HTTP/1.1
Host: api.ventrata.com
Accept: */*

200

Returns an array of mapping rows.

[
  {
    "resellerReference": "RES-BOOK-10045",
    "resellerStatus": "CONFIRMED",
    "resellerProduct": "grand-canyon-day-tour",
    "productId": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
    "optionId": "94cdd032-3d32-416d-b0a4-abf8b7495b8b",
    "unitId": "unit_adult",
    "optionRequired": true,
    "unitRequired": true,
    "validityDays": 2,
    "webhookUrl": "https://www.city-sightseeing.com"
  }
]

Query Parameters

If both productId and productIds[] are provided, productId is used. If both optionId and optionIds[] are provided, optionId is used. Use repeated query keys for arrays, for example productIds[]=id1&productIds[]=id2. DEFAULT on optionId/optionIds[] filters for mappings without a stored option.

optionId and unitId may be null when no mapping has been selected yet, or when optionRequired / unitRequired is false.

Booking and Availability Responses

When this capability is enabled, booking and availability responses include a mappings field. The array contains mappings for the response product/option combination.

• Booking responses include booking.mappings.

• Availability responses include availability[].mappings.

Each mappings[] item uses the same schema as the mappings list response.

Schema Additions (JSON)

These are additive fragments showing only fields introduced by this capability.

Availability

{
  "// ...rest of availability object": "...",
  "mappings": [
    {
      "resellerReference": "RES-BOOK-10045",
      "optionId": "94cdd032-3d32-416d-b0a4-abf8b7495b8b",
      "productId": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
      "resellerStatus": "CONFIRMED"
    }
  ]
}

AvailabilityBatchRow

{
  "// ...rest of availability batch row object": "...",
  "mappings": [
    {
      "resellerReference": "RES-BOOK-10045",
      "optionId": "94cdd032-3d32-416d-b0a4-abf8b7495b8b",
      "productId": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
      "resellerStatus": "CONFIRMED"
    }
  ]
}

Booking

{
  "// ...rest of booking object": "...",
  "mappings": [
    {
      "resellerReference": "RES-BOOK-10045",
      "optionId": "94cdd032-3d32-416d-b0a4-abf8b7495b8b",
      "resellerStatus": "CONFIRMED",
      "resellerProduct": "grand-canyon-day-tour",
      "productId": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
      "unitId": "unit_adult",
      "optionRequired": true,
      "unitRequired": true,
      "validityDays": 2,
      "webhookUrl": "https://www.city-sightseeing.com"
    }
  ]
}

MappingUpsertRequest

{
  "// ...rest of mapping upsert request object": "...",
  "mappings": [
    {
      "resellerReference": "RES-BOOK-10045",
      "productId": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
      "optionId": "94cdd032-3d32-416d-b0a4-abf8b7495b8b"
    }
  ]
}

PackageAvailability

{
  "// ...rest of package availability object": "...",
  "mappings": [
    {
      "resellerReference": "RES-BOOK-10045",
      "optionId": "94cdd032-3d32-416d-b0a4-abf8b7495b8b",
      "productId": "e7cc8bb4-8d1c-4848-8824-5dbedb718681",
      "resellerStatus": "CONFIRMED"
    }
  ]
}