For the complete documentation index, see llms.txt. This page is also available as Markdown.

Partner API Key

Optional. Get each Supplier's API key as soon as they set up your connection

This capability is optional. You don't need it to integrate with Ventrata, and nothing else in these docs depends on it. It's an additional, quicker way to get API keys straight away when Suppliers set up your connection. If you're interested, get in touch with your Ventrata contact or email connectivity@ventrata.com.

To use this capability, add ventrata/partners to your Octo-Capabilities header and authenticate with the Ventrata-Partner-Key header.

By default, every Supplier ⇄ Partner connection on Ventrata has its own API key, and the Supplier sends that key to you when they connect. That stays the same. The Partner API Key only speeds up the hand-off. Ventrata issues your platform one partner-level key, and you use it to list every connection Suppliers have created for you, together with the connection's own API key. You then make normal OCTO calls (products, availability, bookings) with each returned apiKey, exactly as you would with a key the Supplier sent you.

It can help platforms that onboard many Suppliers and would rather not have Supplier credentials passing through email or local market teams. Account managers only need to share connection IDs, which are not secret.

How it works

  1. A Supplier enables your platform as a connection in their Ventrata account. They don't need to send you an API key. If they do, you can ignore it.

  2. Your platform calls GET /ventrata/partners/suppliers_connections with your partner key.

  3. The response lists every active connection for your platform, with the Supplier, the connection and the connection's apiKey.

  4. For each connection, call the standard OCTO endpoints with Authorization: Bearer {apiKey}.

  5. Poll the endpoint regularly, for example once an hour, to pick up new and removed connections.

Endpoint summary

Method
Path
Description

GET

/ventrata/partners/suppliers_connections

List your connections, each with its Supplier details and API key. Recommended.

GET

/ventrata/partner/connections

Older, lighter list of your connections: ID, names and API key only.

Base URL: https://api.ventrata.com/octo

Request headers

Header
Required
Description

Ventrata-Partner-Key

Yes

Your partner-level API key.

Octo-Capabilities

Yes

Must include ventrata/partners. Add other capabilities (for example octo/content) to have them applied to the nested Supplier object.

Octo-Fields

No

Sparse fieldset, to return only the fields you need, for example {connection{id},apiKey}.

Don't send an Authorization header on these endpoints. They are authenticated by the partner key only.

List suppliers' connections

GET /ventrata/partners/suppliers_connections

Returns an array with one entry per connection that Ventrata can authenticate. Connections that are disabled, discarded or linked to a discarded resource are left out of the list.

Example request

Example response

Field
Description

supplier

The Supplier that owns the connection. Uses the standard OCTO Supplier object, extended by any capabilities you request.

connection

The connection details: the same object returned by GET /whoami for that connection.

apiKey

The connection's API key. Use it as the Bearer token for all OCTO calls for this Supplier.

List partner connections (older endpoint)

GET /ventrata/partner/connections

Returns a flat list of your connections. Use suppliers_connections for new integrations.

Regions

Call either endpoint in any Ventrata region. The response combines connections from all regions. A connection hosted outside the default region returns an apiKey with a region prefix (for example us1_…). Use the key exactly as returned. The prefix routes your later calls to the right region.

If any region can't be reached, the whole request fails, so you never get a partial list. Retry later.

Parent and child partners

If your organisation is set up in Ventrata as a parent partner with child partners (for example regional brands), the parent key returns the connections of the parent and all of its descendants. A child key returns only that child's connections (and those of its own children), never its parent's or siblings'.

Errors

Authentication errors return HTTP 400 with error: FORBIDDEN.

errorCode

Meaning

PARTNER_API_KEY_INVALID

The Ventrata-Partner-Key header is missing, or doesn't match an active partner.

Once a connection's apiKey is in use, an OCTO call can return CONNECTION_DISABLED or CONNECTION_NOT_FOUND if the Supplier has turned off or removed that connection. Drop it from your cache and refresh the list. See Errors.

Best practices

  • Cache the list. Refresh it on a schedule (hourly is enough) rather than before every booking call. The endpoint fans out across regions and loads every connection.

  • Don't loop it per Supplier. One call returns all Suppliers. Calling it once for each Supplier multiplies the load and gets rate limited (429).

  • Use Octo-Fields to request only the fields you need. The full Supplier object can be large.

  • Key products by connection. Product IDs belong to a Supplier, and a Supplier can have more than one connection to you. Store the connection.id against each product you map.