Mews Companionships API
The Companionships API from Mews — 1 operation(s) for companionships.
The Companionships API from Mews — 1 operation(s) for companionships.
openapi: 3.0.4
info:
title: Connector Account notes Companionships API
description: General-purpose API that enables partners of Mews to access data and services in Mews Operations
termsOfService: https://www.mews.com/en/terms-conditions/partners
contact:
name: Partner success
email: partnersuccess@mews.com
version: v1
servers:
- url: https://api.mews.com
tags:
- name: Companionships
paths:
/api/connector/v1/companionships/getAll:
post:
tags:
- Companionships
summary: Get all companionships
description: 'Returns all companionships based on customers, reservations or reservation groups. One of them must be specified in the request.
Note this operation uses [Pagination](https://mews-systems.gitbook.io/connector-api/guidelines/pagination/) and supports [Portfolio Access Tokens](https://mews-systems.gitbook.io/connector-api/concepts/multi-property).'
operationId: companionships_getAll
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CompanionshipFilterParameters'
example:
ClientToken: E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D
AccessToken: C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D
Client: Sample Client 1.0.0
EnterpriseIds:
- 3fa85f64-5717-4562-b3fc-2c963f66afa6
- 4d0201db-36f5-428b-8d11-4f0a65e960cc
CompanionshipIds:
- 72d4b117-1f84-44a3-1f84-8b2c0635ac60
CustomerIds:
- 35d4b117-4e60-44a3-9580-c582117eff98
ReservationIds:
- bfee2c44-1f84-4326-a862-5289598f6e2d
ReservationGroupIds:
- c704dff3-7811-4af7-a3a0-7b2b0635ac59
UpdatedUtc:
StartUtc: '2020-02-05T00:00:00Z'
EndUtc: '2020-02-10T00:00:00Z'
Limitation:
Count: 10
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CompanionshipResult'
example:
Companionships:
- Id: 72d4b117-1f84-44a3-1f84-8b2c0635ac60
CustomerId: 35d4b117-4e60-44a3-9580-c582117eff98
ReservationGroupId: c704dff3-7811-4af7-a3a0-7b2b0635ac59
ReservationId: bfee2c44-1f84-4326-a862-5289598f6e2d
Customers: null
Reservations: null
ReservationGroups: null
Cursor: 72d4b117-1f84-44a3-1f84-8b2c0635ac60
'400':
description: Error caused by the client app, e.g. in case of malformed request or invalid identifier of a resource. In most cases, such an error signifies a bug in the client app (consumer of the API).
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectorApiExceptionResult'
'401':
description: Error caused by usage of invalid ClientToken, AccessToken, or you may not have the necessary permission to use the endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectorApiExceptionResult'
'403':
description: Server error that should be reported to the end user of the client app. Happens for example when the server-side validation fails or when a business-logic check is violated.
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectorApiExceptionResult'
'408':
description: Error caused by heavy request that takes too long to process (typically tens of seconds). To get around this, request data in smaller batches. For more information, see [Request timeouts](https://mews-systems.gitbook.io/connector-api/guidelines/requests#request-timeouts)
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectorApiExceptionResult'
'204':
description: Server has successfully fulfilled the request and there is no additional information to send back.
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectorApiExceptionResult'
'429':
description: Error caused by too many requests sent in a given amount of time. Response contains `Retry-After` header indicating how long the user agent should wait before making a follow-up request. For more information, see [Request limits](https://mews-systems.gitbook.io/connector-api/guidelines/requests#request-limits).
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectorApiExceptionResult'
'500':
description: Unexpected error on the Mews side. This may be due to a software fault. If such a situation occurs, the error will be logged and the development team notified, however you can raise an issue through GitHub on our [documentation repository](https://github.com/MewsSystems/gitbook-connector-api).
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectorApiExceptionResult'
components:
schemas:
Limitation:
title: Limitation
required:
- Count
type: object
properties:
Count:
type: integer
format: int32
Cursor:
type: string
format: uuid
nullable: true
additionalProperties: false
description: Limitation on the quantity of data returned.
x-schema-id: Limitation
TimeFilterInterval:
title: Time interval
type: object
properties:
StartUtc:
type: string
format: date-time
nullable: true
EndUtc:
type: string
format: date-time
nullable: true
additionalProperties: false
description: "When a time interval is used for **filtering** (for example in parameters such as `CreatedUtc.StartUtc` / `CreatedUtc.EndUtc`), the following rules apply:\r\n\r\n- **Start equals End (equality mode)** \r\n If `StartUtc` and `EndUtc` are exactly the same timestamp, the filter is treated as an equality check for that precise moment in time:\r\n \r\n ```\r\n CreatedUtc == StartUtc\r\n ```\r\n \r\n This does not represent an interval; only records with `CreatedUtc` equal to that exact instant are returned.\r\n\r\n- **Start differs from End (interval mode)** \r\n If `StartUtc` and `EndUtc` are different, the filter is evaluated as a half-open interval:\r\n \r\n ```\r\n StartUtc <= CreatedUtc < EndUtc\r\n ```\r\n \r\n In other words, the start is inclusive and the end is exclusive.\r\n\r\nMake sure your integration takes inclusive Start / exclusive End behavior of time intervals into account so that no records at the boundaries are omitted."
x-schema-id: TimeFilterInterval
ReservationGroupOld:
title: Reservation groups (ver 2017-04-12)
type: object
properties:
Id:
type: string
description: Unique identifier of the reservation group.
format: uuid
Name:
type: string
description: Name of the reservation group.
nullable: true
additionalProperties: false
x-schema-id: ReservationGroupOld
SexEnum:
title: Sex
enum:
- Male
- Female
type: string
description: '
Male
Female'
x-enumNames:
- Male
- Female
x-enumDescriptions:
- ''
- ''
IdentityDocumentTypeEnum:
title: Document type
enum:
- IdentityCard
- Passport
- Visa
- DriversLicense
type: string
description: '
IdentityCard
Passport
Visa
DriversLicense'
x-enumNames:
- IdentityCard
- Passport
- Visa
- DriversLicense
x-enumDescriptions:
- ''
- ''
- ''
- ''
CancellationReason:
enum:
- Other
- ConfirmationMissed
- BookedElsewhere
- ForceMajeure
- GuestComplaint
- NoShow
- PriceTooHigh
- ServiceNotAvailable
- InputError
- InvalidPayment
- TravelAgency
- RequestedByGuest
- Update
- BookingAbandoned
- RequestedByBooker
type: string
CompanionshipExtent:
title: Companionship extent
type: object
properties:
Reservations:
type: boolean
description: Whether the response should contain reservations.
nullable: true
ReservationGroups:
type: boolean
description: Whether the response should contain reservation groups.
nullable: true
Customers:
type: boolean
description: Whether the response should contain customers.
nullable: true
additionalProperties: false
description: ''
x-schema-id: CompanionshipExtent
ReservationPersonCount:
title: Age category parameters
required:
- AgeCategoryId
- Count
type: object
properties:
AgeCategoryId:
type: string
description: Unique identifier of the [Age category](https://mews-systems.gitbook.io/connector-api/operations/agecategories#age-category).
format: uuid
Count:
type: integer
description: Number of people of a given age category. Only positive value is accepted.
format: int32
additionalProperties: false
x-schema-id: ReservationPersonCount
Companionship:
title: Companionship
type: object
properties:
Id:
type: string
description: Unique identifier of `Companionship`.
format: uuid
CustomerId:
type: string
description: Unique identifier of Customer.
format: uuid
ReservationGroupId:
type: string
description: Unique identifier of ReservationGroup.
format: uuid
ReservationId:
type: string
description: Unique identifier of reservation.
format: uuid
nullable: true
additionalProperties: false
x-schema-id: Companionship
Title:
title: Title
enum:
- Mister
- Miss
- Misses
type: string
description: "Type of the title prefix of the customer.\r\n\r\nNote that the value should not be used as-is, but localized. For example, the value `Misses` should be displayed as `Mrs.` in English and `Fr.` in German.\n\nMister (Mr.)\n\nMiss (Ms.)\n\nMisses (Mrs.)"
x-enumNames:
- Mister
- Miss
- Misses
x-enumDescriptions:
- Mr.
- Ms.
- Mrs.
x-schema-id: Title
x-showDescription: true
CompanionshipFilterParameters:
title: CompanionshipFilterParameters
required:
- AccessToken
- Client
- ClientToken
- Extent
- Limitation
type: object
properties:
ClientToken:
minLength: 1
type: string
description: Token identifying the client application.
AccessToken:
minLength: 1
type: string
description: Access token of the client application.
Client:
minLength: 1
type: string
description: Name and version of the client application.
Limitation:
allOf:
- $ref: '#/components/schemas/Limitation'
description: Limitation on the quantity of data returned and optional Cursor for the starting point of data.
EnterpriseIds:
maxItems: 1000
minItems: 1
type: array
items:
type: string
format: uuid
description: Unique identifiers of the Enterprises. If not specified, the operation returns data for all enterprises within scope of the Access Token.
nullable: true
CompanionshipIds:
maxItems: 1000
minItems: 1
type: array
items:
type: string
format: uuid
description: Unique identifiers of `Companionship`. Required if no other filter is provided.
nullable: true
Extent:
title: Companionship extent
allOf:
- $ref: '#/components/schemas/CompanionshipExtent'
description: Extent of data to be returned. E.g. it is possible to specify that together with the companionships, customers, reservations, and reservation groups should be also returned.
ReservationIds:
maxItems: 1000
minItems: 1
type: array
items:
type: string
format: uuid
description: Unique identifiers of `Reservation`. Required if no other filter is provided.
nullable: true
CustomerIds:
maxItems: 1000
minItems: 1
type: array
items:
type: string
format: uuid
description: Unique identifiers of `Customer`. Required if no other filter is provided.
nullable: true
ReservationGroupIds:
maxItems: 1000
minItems: 1
type: array
items:
type: string
format: uuid
description: Unique identifiers of `ReservationGroup`. Required if no other filter is provided.
nullable: true
UpdatedUtc:
title: Time interval
allOf:
- $ref: '#/components/schemas/TimeFilterInterval'
description: Interval in which the `Companionship` was updated. Must be used together with at least one another filter.
nullable: true
x-max-interval-in-months: 3
additionalProperties: false
x-schema-id: CompanionshipFilterParameters
CustomerClassificationEnum:
title: Customer classification
enum:
- PaymasterAccount
- Blacklist
- Media
- LoyaltyProgram
- PreviousComplaint
- Returning
- Staff
- FriendOrFamily
- TopManagement
- Important
- VeryImportant
- Problematic
- Cashlist
- DisabledPerson
- Military
- Airline
- HealthCompliant
- InRoom
- WaitingForRoom
- Student
- Blocklist
type: string
description: '
PaymasterAccount
Blacklist (Deprecated, use Blocklist instead.)
Media
LoyaltyProgram
PreviousComplaint
Returning
Staff
FriendOrFamily
TopManagement
Important
VeryImportant
Problematic
Cashlist
DisabledPerson
Military
Airline
HealthCompliant
InRoom
WaitingForRoom
Student
Blocklist'
x-enumNames:
- PaymasterAccount
- Blacklist
- Media
- LoyaltyProgram
- PreviousComplaint
- Returning
- Staff
- FriendOrFamily
- TopManagement
- Important
- VeryImportant
- Problematic
- Cashlist
- DisabledPerson
- Military
- Airline
- HealthCompliant
- InRoom
- WaitingForRoom
- Student
- Blocklist
x-enumDescriptions:
- ''
- Deprecated, use Blocklist instead.
- ''
- ''
- ''
- ''
- ''
- ''
- ''
- ''
- ''
- ''
- ''
- ''
- ''
- ''
- ''
- ''
- ''
- ''
- ''
CustomerOptionsEnum:
title: Customer option
enum:
- None
- SendMarketingEmails
- Invoiceable
- BillAddressObjection
- SendMarketingPostalMail
- SendPartnerMarketingEmails
- SendPartnerMarketingPostalMail
- WithdrawCardConsent
- GuestPhotoConsent
- IdPhotosConsent
type: string
description: '
None
SendMarketingEmails
Invoiceable
BillAddressObjection
SendMarketingPostalMail
SendPartnerMarketingEmails
SendPartnerMarketingPostalMail
WithdrawCardConsent
GuestPhotoConsent
IdPhotosConsent'
x-enumNames:
- None
- SendMarketingEmails
- Invoiceable
- BillAddressObjection
- SendMarketingPostalMail
- SendPartnerMarketingEmails
- SendPartnerMarketingPostalMail
- WithdrawCardConsent
- GuestPhotoConsent
- IdPhotosConsent
x-enumDescriptions:
- ''
- ''
- ''
- ''
- ''
- ''
- ''
- ''
- ''
- ''
ReservationOld:
title: Reservation (ver 2017-04-12)
required:
- AssignedResourceLocked
- CompanionIds
- CreatedUtc
- CustomerId
- EndUtc
- GroupId
- Id
- Number
- Options
- Origin
- OwnerId
- PersonCounts
- RateId
- RequestedCategoryId
- ServiceId
- StartUtc
- State
- UpdatedUtc
type: object
properties:
Id:
type: string
description: Unique identifier of the reservation.
format: uuid
ServiceId:
type: string
description: Unique identifier of the Service that is reserved.
format: uuid
GroupId:
type: string
description: Unique identifier of the Reservation group.
format: uuid
Number:
minLength: 1
type: string
description: Confirmation number of the reservation in Mews.
ChannelNumber:
type: string
description: Number of the reservation within the Channel (i.e. OTA, GDS, CRS, etc) in case the reservation group originates there (e.g. Booking.com confirmation number).
nullable: true
ChannelManagerNumber:
type: string
description: Unique number of the reservation within the reservation group.
nullable: true
ChannelManagerGroupNumber:
type: string
description: Number of the reservation group within a Channel manager that transferred the reservation from Channel to Mews.
nullable: true
ChannelManager:
type: string
description: Name of the Channel manager (e.g. AvailPro, SiteMinder, TravelClick, etc).
nullable: true
State:
$ref: '#/components/schemas/ServiceOrderStateOld'
Origin:
$ref: '#/components/schemas/ReservationOldOrigin'
OriginDetails:
type: string
description: Details about the reservation origin.
nullable: true
Purpose:
anyOf:
- $ref: '#/components/schemas/ReservationPurpose'
description: Purpose of the reservation.
nullable: true
CreatedUtc:
minLength: 1
type: string
description: Creation date and time of the reservation in UTC timezone in ISO 8601 format.
UpdatedUtc:
minLength: 1
type: string
description: Last update date and time of the reservation in UTC timezone in ISO 8601 format.
CancelledUtc:
type: string
description: Cancellation date and time in UTC timezone in ISO 8601 format.
nullable: true
StartUtc:
minLength: 1
type: string
description: Start of the reservation in UTC timezone in ISO 8601 format. This is either the scheduled reservation start time, or the actual customer check-in time if this is earlier than the scheduled start time.
EndUtc:
minLength: 1
type: string
description: End of the reservation (departure) in UTC timezone in ISO 8601 format.
ReleasedUtc:
type: string
description: Date when the optional reservation is released in UTC timezone in ISO 8601 format.
nullable: true
RequestedCategoryId:
type: string
description: Identifier of the requested Resource category.
format: uuid
AssignedSpaceId:
type: string
description: Identifier of the assigned Space.
format: uuid
nullable: true
deprecated: true
x-deprecatedMessage: Use `AssignedResourceId` instead.
AssignedSpaceLocked:
type: boolean
description: Whether the reservation is locked to the assigned Space and cannot be moved.
deprecated: true
x-deprecatedMessage: Use `AssignedResourceLocked` instead.
AssignedResourceId:
type: string
description: Identifier of the assigned Resource.
format: uuid
nullable: true
AssignedResourceLocked:
type: boolean
description: Whether the reservation is locked to the assigned Resource and cannot be moved.
BusinessSegmentId:
type: string
description: Identifier of the reservation Business segment.
format: uuid
nullable: true
CompanyId:
type: string
description: Identifier of the Company on behalf of which the reservation was made.
format: uuid
nullable: true
TravelAgencyId:
type: string
description: Identifier of the Company that mediated the reservation.
format: uuid
nullable: true
AvailabilityBlockId:
type: string
description: Unique identifier of the Availability block the reservation is assigned to.
format: uuid
nullable: true
RateId:
type: string
description: Identifier of the reservation Rate.
format: uuid
VoucherId:
type: string
description: Unique identifier of the Voucher that has been used to create reservation.
format: uuid
nullable: true
CreditCardId:
type: string
description: Unique identifier of the Credit card.
format: uuid
nullable: true
CancellationReason:
anyOf:
- $ref: '#/components/schemas/CancellationReason'
description: Cancellation reason of the reservation.
nullable: true
AdultCount:
type: integer
description: Count of adults the reservation was booked for.
format: int32
deprecated: true
x-deprecatedMessage: Use `PersonCounts` instead.
ChildCount:
type: integer
description: Count of children the reservation was booked for.
format: int32
deprecated: true
x-deprecatedMessage: Use `PersonCounts` instead.
PersonCounts:
type: array
items:
$ref: '#/components/schemas/ReservationPersonCount'
description: Number of people per age category the reservation was booked for.
OwnerId:
type: string
description: Unique identifier of the Customer or Company who owns the reservation.
format: uuid
CustomerId:
type: string
description: Unique identifier of the Customer who owns the reservation.
format: uuid
deprecated: true
x-deprecatedMessage: Use `OwnerId` instead.
BookerId:
type: string
description: Unique identifier of the Customer on whose behalf the reservation was made.
format: uuid
nullable: true
CompanionIds:
type: array
items:
type: string
format: uuid
description: Unique identifiers of the `Customer`s that will use the resource.
deprecated: true
x-deprecatedMessage: Use `companionships/getAll` instead.
ChannelManagerId:
type: string
description: Channel Manager number.
nullable: true
deprecated: true
x-deprecatedMessage: Use `ChannelManagerNumber` instead.
Options:
title: Reservation options
allOf:
- $ref: '#/components/schemas/ReservationOptions'
description: Options of the reservation.
additionalProperties: false
description: ''
x-schema-id: ReservationOld
ResourceFeatureClassification:
title: Resource feature classification
enum:
- SeaView
- RiverView
- OceanView
- TwinBeds
- DoubleBed
- RollawayBed
- UpperBed
- LowerBed
- Balcony
- AccessibleBathroom
- AccessibleRoom
- ElevatorAccess
- HighFloor
- Kitchenette
- AirConditioning
- PrivateJacuzzi
- PrivateSauna
- EnsuiteRoom
- PrivateBathroom
- SharedBathroom
type: string
description: Classification of `ResourceFeature`.
ReservationPurpose:
title: Reservation purpose
enum:
- Leisure
- Business
- Student
type: string
IdentityDocument:
title: Identity document
type: object
properties:
Id:
type: string
description: Unique identifier of the document.
format: uuid
CustomerId:
type: string
description: Identifier of the `Customer`.
format: uuid
Type:
title: Document type
allOf:
- $ref: '#/components/schemas/IdentityDocumentTypeEnum'
description: 'Type of the document.
IdentityCard
Passport
Visa
DriversLicense'
x-enumNames:
- IdentityCard
- Passport
- Visa
- DriversLicense
x-enumDescriptions:
- ''
- ''
- ''
- ''
Number:
type: string
description: Number of the document (e.g. passport number).
nullable: true
Expiration:
type: string
description: Expiration date in ISO 8601 format.
format: date
nullable: true
Issuance:
type: string
description: Date of issuance in ISO 8601 format.
format: date
nullable: true
IssuingCountryCode:
type: string
description: ISO 3166-1 code of the `Country`.
nullable: true
IssuingCountrySubdivisionCode:
type: string
description: Identifier of the country subdivision where the document was issued (province, state or region).
nullable: true
IssuingCity:
type: string
description: City where the document was issued.
nullable: true
IdentityDocumentSupportNumber:
type: string
description: Identity document support number. Only required for Spanish identity cards in Spanish hotels.
nullable: true
additionalProperties: false
x-schema-id: IdentityDocument
ServiceOrderStateOld:
title: Service order state (ver 2017-04-12)
enum:
- Enquired
- Confirmed
- Started
- Processed
- Canceled
- Optional
- Requested
type: string
CompanionshipResult:
title: CompanionshipResult
type: object
properties:
Companionships:
type: array
items:
$ref: '#/components/schemas/Companionship'
description: Companionships.
nullable: true
Reservations:
type: array
items:
$ref: '#/components/schemas/ReservationOld'
description: The accompanied reservations.
nullable: true
ReservationGroups:
type: array
items:
$ref: '#/components/schemas/ReservationGroupOld'
description: The accompanied reservation groups.
nullable: true
Customers:
type: array
items:
$ref: '#/components/schemas/Customer'
description: Customers that belong to the companionships.
nullable: true
Cursor:
type: string
description: Unique identifier of the item one newer in time order than the items to be returned. If Cursor is not specified, i.e. null, then the latest or most recent items will be returned.
format: uuid
nullable: true
additionalProperties: false
x-schema-id: CompanionshipResult
ConnectorApiExceptionResult:
title: ConnectorApiExceptionResult
type: object
properties:
Message:
type: string
nullable: true
RequestId:
type: string
nullable: true
Details:
nullable: true
additionalProperties: false
x-schema-id: ConnectorApiExceptionResult
OldAddress:
title: Address
type: object
properties:
Id:
type: string
description: Unique identifier of the address.
format: uuid
Line1:
type: string
description: First line of the address.
nullable: true
Line2:
type: string
description: Second line of the address.
nullable: true
City:
type: string
description: The city.
nullable: true
PostalCode:
type: string
description: Postal code.
nullable: true
CountryCode:
type: string
description: ISO 3166-1 code of the `Country`.
nullable: true
CountrySubdivisionCode:
type: string
description: ISO 3166-2 code of the administrative division, e.g. `DE-BW`.
nullable: true
Latitude:
type: number
description: The latitude.
format: double
nullable: true
Longitude:
type: number
description: The longitude.
format: double
nullable: true
additionalProperties: false
description: ''
x-schema-id: OldAddress
Customer:
title: Customer
required:
- ChainId
- Classifications
- CreatedUtc
- CreatorProfileId
- Id
- IsActive
- LastName
- Number
- Options
- PreferredSpaceFeatures
- UpdatedUtc
- UpdaterProfileId
type: object
properties:
Id:
type: string
description: Unique identifier of the customer.
format: uuid
ChainId:
type: string
description: Unique identifier of the chain.
format: uuid
Number:
maxLength: 19
minLength: 1
type: string
description: Unique number of the customer (max 19 digits).
Title:
allOf:
- $ref: '#/components/schemas/Title'
description: 'Title of the customer.
Mister (Mr.)
Miss (Ms.)
Misses (Mrs.)'
nullable: true
Sex:
allOf:
- $ref: '#/components/schemas/SexEnum'
description: 'Sex of the customer.
Male
Female'
nullable: true
FirstName:
type: string
description: First name of the customer.
nullable: true
LastName:
minLength: 1
type: string
description: Last name of the customer.
SecondLastName:
type: string
description: Second last name of the customer.
nullable: true
NationalityCode:
type: string
description: ISO 3166-1 code of the [Country](https://mews-systems.gitbook.io/connector-api/operations/countries/#country).
nullable: true
PreferredLanguageCode:
type: string
description: 'Language and culture code of the customer''s preferred language, according to their profile. For example: `en-GB`, `fr-CA`.'
nullable: true
LanguageCode:
type: string
description: Language and culture code of the customer's language, based on multiple sources. These sources include the preferred language specified in internal data based on previous bookings, and the preferred language of the customer specified in their profile. If neither of these sources are p
# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mews/refs/heads/main/openapi/mews-companionships-api-openapi.yml