Accounts

City Connect does not differentiate between suppliers and agents, we treat both as regular "accounts" allowing you to supply products and sell tickets or both.

All accounts are identified by an email or domain. The API documented here is split into a supplier and agent guide. It is the supplier's responsibility to accept bookings and return barcodes scannable by their point of sale systems.

Create Account

POST https://api.cityconnect.net/v1/account

Use this endpoint to create a new account, with the following fields:

Field	Description	Example
`name`	The name of your brand.	Cape Town Tours
`email`	The administrator email on the account. We'll send login credentials and booking notifications to this address.	[email protected]
`callback_url`	The base URL that gets called for reservation and booking callbacks.	https://api.example.com/cc/callbacks
`notification_url`	The URL that gets called when a booking has been confirmed or a ticket has been redeemed.	https://api.example.com/cc/notifications

For example:

{
  "name": "Cape Town Tours",
  "email": "[email protected]",
  "callback_url": "https://api.example.com/cc/callbacks",
  "notification_url": "https://api.example.com/cc/notifications"
}

Note that the callback_url and notification_url must start with https://.

You are encouraged to secure the URLs against forged requests, you can do so by including HTTP basic authentication credentials within the URL. For example:

https://user:[email protected]/cc/callbacks

This will make all requests to https://api.example.com/cc/callbacks with the HTTP Basic Authentication header with the values of user and pass as the username and password respectively, which you can check.

The account creation response will contain an authentication token which you should use along with your email for making authenticated requests to the City Connect API.

{
  "verified": false,
  "domain": null,
  "token": "XjWNW66RCylqeMU556UaYw"
}

The verified field indicates whether your email has been verified. We will send you an email verification email after you create your account which you should verify.

Account Update

PATCH https://api.cityconnect.net/v1/account

This is an authenticated request, we require you use your account identifier (email or domain) as well as the token returned in account creation. See the section on Authentication for details on how to do this. The parameters are identical to account creation.

Note you cannot change your email after your account has been verified.

Account Lookup

You can lookup existing accounts by maybe a request to:

GET https://api.cityconnect.net/v1/account/:id

For example:

GET https://api.cityconnect.net/v1/account/viator.com
GET https://api.cityconnect.net/v1/account/[email protected]

Will return a JSON response with:

{
	"name": "Viator",
  "email": "[email protected]",
  "verified": true,
  "domain": "viator.com"
}

This is a public API that does not require any authentication. If you do authenticate, leaving the :id blank will return details for your account.

Registering a Domain

Your account will always be associated by your email. This is what will be given to suppliers and other accounts when you make availability requests or bookings.

For example, to be identified as viator.com instead of [email protected]

It is possible instead to have your account identified by a domain, to do so please contact our support team [email protected] and we'll walk you through the steps.