Skip to main content

How to Use the Reseller & Agent Management API

Learn how to use Ventrata's Reseller & Agent Management API to programmatically create, update, retrieve, and delete resellers and their agents.

Updated over a month ago

Overview

The Reseller & Agent Management API allows you to:

  • create and manage resellers via API

  • create and manage agents under a specific reseller

  • update individual fields using PATCH

  • fully automate reseller and agent setup workflows

This is useful if you:

  • sync resellers from an external CRM or ERP

  • automate onboarding of new partners

  • maintain reseller data consistency across systems

Authentication & Base URL

The Reseller & Agent Management API is part of the Ventrata Dashboard API and requires a Backoffice-mode API connection.

Required Headers

All requests to the Reseller & Agent Management API must include the following headers:

Header

Purpose

Authorization: Bearer <token>

Authenticates the request

Content-Type: application/json

Indicates JSON payload

Octo-Capabilities: ventrata/dashboard

Confirms enabled capability

Base Path

All endpoints described in this article are prefixed with: 

/ventrata/dashboard

Authentication Example

Include the API token in the Authorization header of each request:

Authorization: Bearer YOUR_API_TOKEN

📒 NOTE

You can find your API token in the Backoffice-mode connection detail next to API Key. Click the eye icon to reveal the token, then copy and paste it in the Authorization header of your request.

API Key

❗️IMPORTANT

Your API Key is a confidential credential that provides access to your Ventrata account. Never share it with anyone over chat or email.

Resellers

Reseller Endpoints

Method

Endpoint

GET

/ventrata/dashboard/resellers

GET

/ventrata/dashboard/resellers/:resellerId

POST

/ventrata/dashboard/resellers

PATCH

/ventrata/dashboard/resellers/:resellerId

DELETE

/ventrata/dashboard/resellers/:resellerId

📒 NOTE

The PATCH endpoint supports partial updates. Only the fields included in the request body will be updated. All other fields remain unchanged.

Example PATCH curl request

curl -X PATCH "https://api.ventrata.com/octo/ventrata/dashboard/resellers/:resellerId" \
  -H "Authorization: Bearer YOUR_DASHBOARD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Octo-Capabilities: ventrata/dashboard" \
  -d '{
    "creditLimit": 500000,
    "tags": ["OTA", "VIP"]
  }'

Supported Fields (POST/PATCH)

The following fields are supported when creating or updating a reseller:

active  
name  
reference  
tags[]  
creditLimit  
defaultCurrency  
availableCurrencies[]  
settlementMethods[]  
billingAccountCode  
billingCustomerCode  
billingStreetAddress  
billingCity  
billingCompany  
billingCompanyNumber  
billingCompanyTaxOffice  
billingPostalCode  
billingCountry  
billingContact.fullName  
billingContact.emailAddress  
billingContact.phoneNumber

📘 EXAMPLE

Example JSON payload

{
  "active": true,
  "name": "Viator",
  "reference": "VIA",
  "tags": ["OTA"],

  "creditLimit": 1000000,
  "defaultCurrency": "USD",
  "availableCurrencies": ["USD", "GBP", "EUR"],
  "settlementMethods": ["VOUCHER"],

  "billingCompany": "Viator Inc",
  "billingCompanyNumber": "GB123456789",
  "billingStreetAddress": "123 Example Street",
  "billingCity": "London",
  "billingPostalCode": "EC1A 1AA",
  "billingCountry": "GB",

  "billingContact": {
    "fullName": "Accounts Payable",
    "emailAddress": "[email protected]",
    "phoneNumber": "+44 20 0000 0000"
  }
}

Agents

Agents are always managed within the context of a reseller.

  • Agents are returned as part of reseller GET responses under the agents field

  • Each agent has a unique id

  • Use agents[].id as :agentId for updates or deletion

Agents Endpoints

Method

Endpoint

POST

/ventrata/dashboard/resellers/:resellerId/agents

PATCH

/ventrata/dashboard/resellers/:resellerId/agents/:agentId

DELETE

/ventrata/dashboard/resellers/:resellerId/agents/:agentId

📒 NOTE

The PATCH endpoint supports partial updates. Only the fields included in the request body will be updated. All other fields remain unchanged.

Example PATCH curl request

curl -X PATCH "https://api.ventrata.com/octo/ventrata/dashboard/resellers/resellerId/agents/:agentId" \
  -H "Authorization: Bearer YOUR_DASHBOARD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Octo-Capabilities: ventrata/dashboard" \
  -d '{
    "active": false,
    "tags": ["VIP", "Temporary"]
  }'

Supported Fields (POST / PATCH)

active  
name  
reference  
tags[]  
emailAddress  
phoneNumber

📘 EXAMPLE

Example JSON payload

{
  "active": true,
  "name": "Jane Doe",
  "reference": "JDOE",
  "tags": ["VIP"],
  "emailAddress": "[email protected]",
  "phoneNumber": "+1 555 000 0000"
}

Automatic Agent Welcome Email

When an agent is created via the API, the agent welcome email is automatically sent.

This behaviour is identical to creating an agent via the Dashboard UI.

Create Backoffice-Mode Connection

You must create a Backoffice-mode connection to generate an API token with access to dashboard endpoints.

📗 TIP

If you are already using the Reporting & Export API, you can reuse the same connection and token, as long as it is a Backoffice-mode connection.

  1. In your Ventrata Dashboard, go to Connections > Connections.

    Connections

  2. Press the + New Connection button.

    New Connection

  3. In the Partner gallery, press the + New Connection link in the far right.

    You do not need to select a partner.

    New Connection

  4. Give the connection a descriptive name.

    Name

  5. Select 'Backoffice' mode.

    Backoffice Mode

  6. Make sure the connection has both 'Read' and 'Write' permissions.

    Permissions

  7. Press the Create Octo Connection button.

    Create Octo Connection

Create Reseller

  1. Open the connection. In the API Key field, you will find your authentication token.

    API Key

  2. Paste the following curl request into your terminal emulator.

    curl -X POST "https://api.ventrata.com/octo/ventrata/dashboard/resellers" \
      -H "Authorization: Bearer YOUR_DASHBOARD_API_TOKEN" \
      -H "Content-Type: application/json" \
      -H "Octo-Capabilities: ventrata/dashboard" \
      -d '{
        "active": true,
        "name": "Viator",
        "reference": "VIA",
        "tags": ["OTA"],

        "creditLimit": 1000000,
        "defaultCurrency": "USD",
        "availableCurrencies": ["USD", "GBP", "EUR"],
        "settlementMethods": ["VOUCHER"],

        "billingCompany": "Viator Inc",
        "billingCompanyNumber": "GB123456789",
        "billingStreetAddress": "123 Example Street",
        "billingCity": "London",
        "billingPostalCode": "EC1A 1AA",
        "billingCountry": "GB",

        "billingContact": {
          "fullName": "Accounts Payable",
          "emailAddress": "[email protected]",
          "phoneNumber": "+44 20 0000 0000"
        }
      }'

  3. Replace:

    • YOUR_DASHBOARD_API_TOKEN with your API Key from your Backoffice-mode connection

  4. Run the request.

  5. Go back to your Ventrata dashboard and refresh your dashboard page. The newly created reseller account is immediately visible.

Create Agent

  1. Open the connection. In the API Key field, you will find your authentication token.

    API Key

  2. Paste the following curl request into your terminal emulator.

    curl -X POST "https://api.ventrata.com/octo/ventrata/dashboard/resellers/:resellerId/agents" \
      -H "Authorization: Bearer YOUR_DASHBOARD_API_TOKEN" \
      -H "Content-Type: application/json" \
      -H "Octo-Capabilities: ventrata/dashboard" \
      -d '{
        "active": true,
        "name": "Jane Doe",
        "reference": "JDOE",
        "tags": ["VIP"],
        "emailAddress": "[email protected]",
        "phoneNumber": "+1 555 000 0000"
      }'

  3. Replace:

    • YOUR_DASHBOARD_API_TOKEN with your API Key from your Backoffice-mode connection

    • :resellerId with the reseller ID, access through the reseller detail

      Reseller ID

  4. Run the request.

  5. Go back to your Ventrata dashboard and refresh your dashboard page. The newly created agent is immediately visible.

Related Articles
Reservotron Operator Connection
Zaui Operator Connection
How to Connect Resellers and Operators Using Ventrata to Ventrata Connection
How to Use Reporting and Export API Endpoints
Bókun Operator Connection
Did this answer your question?