Connector API
Search…
⌃K

Customers

Get all customers

Returns all customers filtered by identifiers, emails, names and other filters. Note this operation uses Pagination.

Request

[PlatformAddress]/api/connector/v1/customers/getAll
{
"ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D",
"AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D",
"Client": "Sample Client 1.0.0",
"CustomerIds": [
"35d4b117-4e60-44a3-9580-c582117eff98"
],
"Emails": [
"[email protected]"
],
"FirstNames": [
"John",
"Jane"
],
"LastNames": [
"Doe"
],
"LoyaltyCodes": [
"LL810213"
],
"CreatedUtc": {
"StartUtc": "2019-12-05T00:00:00Z",
"EndUtc": "2019-12-10T00:00:00Z"
},
"UpdatedUtc": {
"StartUtc": "2019-12-10T00:00:00Z",
"EndUtc": "2019-12-17T00:00:00Z"
},
"ActivityStates": [
"Active"
],
"Extent" : {
"Customers": "true",
"Documents": "true",
"Addresses": "false"
},
"Limitation":{
"Cursor": "e7f26210-10e7-462e-9da8-ae8300be8ab7",
"Count": 10
}
}
Property
Type
Contract
Description
ClientToken
string
required
Token identifying the client application.
AccessToken
string
required
Access token of the client application.
Client
string
required
Name and version of the client application.
CustomerIds
array of string
optional, max 1000 items
Unique identifiers of Customers. Required if no other filter is provided.
Emails
array of string
optional, max 1000 items
Emails of the Customers.
FirstNames
array of string
optional, max 1000 items
First names of the Customers.
LastNames
array of string
optional, max 1000 items
Last names of the Customers.
LoyaltyCodes
array of string
optional, max 1000 items
Loyalty codes of the Customers.
CreatedUtc
optional, max length 3 months
Interval in which Customer was created.
UpdatedUtc
optional, max length 3 months
Interval in which Customer was updated.
DeletedUtc
optional, max length 3 months
Interval in which Customer was deleted. ActivityStates value Deleted should be provided with this filter to get expected results.
ActivityStates
array of string Activity state​
optional
Whether return only active, only deleted or both records.
Extent
required
Extent of data to be returned.
Limitation
required
Limitation on the quantity of customers returned.

Time interval

Property
Type
Contract
Description
StartUtc
string
required
Start of the interval in UTC timezone in ISO 8601 format.
EndUtc
string
required
End of the interval in UTC timezone in ISO 8601 format.

Customer extent

Property
Type
Contract
Description
Customers
bool
required
Whether the response should contain information about customers.
Documents
bool
required
Whether the response should contain identity documents of customers.
Addresses
bool
required
Whether the response should contain addresses of customers.

Response

{
"Customers": [
{
"Address": {
"Line1": "Somerford Road Hello House/135",
"Line2": null,
"City": "Christchurch",
"PostalCode": "BH23 3PY",
"CountryCode": "GB",
"Latitude": null,
"Longitude": null
},
"BirthDate": null,
"BirthPlace": null,
"CategoryId": null,
"Classifications": [],
"CreatedUtc": "2016-01-01T00:00:00Z",
"Email": null,
"FirstName": "John",
"Sex": "Male",
"Id": "35d4b117-4e60-44a3-9580-c582117eff98",
"IdentityCard": null,
"LanguageCode": null,
"LastName": "Smith",
"LoyaltyCode": null,
"AccountingCode": null,
"BillingCode": null,
"NationalityCode": "US",
"Notes": "",
"CarRegistrationNumber": null,
"Options": [],
"Number": "1",
"Phone": "00420123456789",
"SecondLastName": null,
"TaxIdentificationNumber": null,
"Title": null,
"UpdatedUtc": "2016-01-01T00:00:00Z",
"CompanyId": "cb7d4a2f-10e0-4163-a176-ad03007efa8a",
"MergeTargetId": null,
"ActivityState": "Active"
}
],
"Documents": [
{
"Id": "e8a72a69-c20b-4278-b699-ab0400a32ecc",
"CustomerId": "35d4b117-4e60-44a3-9580-c582117eff98",
"Type": "IdentityCard",
"Number": "123456",
"Expiration": "2020-01-01",
"Issuance": "2016-01-01",
"IssuingCountryCode": "CZ"
}
],
"Cursor": "8d02142f-31cf-4115-90bf-ae5200c7a1ba"
}
Property
Type
Contract
Description
Customers
array of Customer​
required
The customers.
Documents
array of Document​
required
The identity documents of customers.
Cursor
string
required
Unique identifier of the last and hence oldest customer item returned. This can be used in Limitation in a subsequent request to fetch the next batch of older customers. If Limitation is specified in the request message, then Cursor will always be included in the response message; this is true even when using Extents set to false so that no actual data is returned.

Customer

Property
Type
Contract
Description
Id
string
required
Unique identifier of the customer.
Number
string
required
Number of the customer.
FirstName
string
optional
First name of the customer.
LastName
string
required
Last name of the customer.
SecondLastName
string
optional
Second last name of the customer.
Title
string Title​
optional
Title prefix of the customer.
Sex
string Sex​
optional
Sex of the customer.
NationalityCode
string
optional
ISO 3166-1 code of the Country.
LanguageCode
string
optional
Language and culture code of the customers preferred language. E.g. en-US or fr-FR.
BirthDate
string
optional
Date of birth in ISO 8601 format.
BirthPlace
string
optional
Place of birth.
Email
string
optional
Email address of the customer.
Phone
string
optional
Phone number of the customer (possibly mobile).
TaxIdentificationNumber
string
optional
Tax identification number of the customer.
LoyaltyCode
string
optional
Loyalty code of the customer.
AccountingCode
string
optional
Accounting code of the customer.
BillingCode
string
optional
Billing code of the customer.
Notes
string
optional
Internal notes about the customer.
CarRegistrationNumber
string
optional
Registration number of the customer's car.
Classifications
required
Classifications of the customer.
Options
array of Customer option​
required
Options of the customer.
Address
​Address​
optional
Address of the customer.
CreatedUtc
string
required
Creation date and time of the customer in UTC timezone in ISO 8601 format.
UpdatedUtc
string
required
Last update date and time of the customer in UTC timezone in ISO 8601 format.
ItalianDestinationCode
string
optional
Value of Italian destination code.
ItalianFiscalCode
string
optional
Value of Italian fiscal code.
CompanyId
string
optional
Unique identifier of Company the customer is associated with.
MergeTargetId
string
optional
Unique identifier of the account (Customer) to which this customer is linked.
ActivityState
string
required
​Activity State of customer record, i.e. whether active or deleted.

Title

  • Mister
  • Miss
  • Misses

Sex

  • Male
  • Female

Document

Property
Type
Contract
Description
Id
string
required
Unique identifier of the document.
CustomerId
string
required
Identifier of the Customer.
Type
string Document type​
required
Type of the document.
Number
string
optional
Number of the document (e.g. passport number).
Expiration
string
optional
Expiration date in ISO 8601 format.
Issuance
string
optional
Date of issuance in ISO 8601 format.
IssuingCountryCode
string
optional
ISO 3166-1 code of the Country.

Document type

  • Passport
  • IdentityCard
  • Visa
  • DriversLicense

Customer classification

  • PaymasterAccount
  • Blacklist
  • Media
  • LoyaltyProgram
  • PreviousComplaint
  • Returning
  • Staff
  • FriendOrFamily
  • TopManagement
  • Important
  • VeryImportant
  • Problematic
  • Cashlist
  • DisabledPerson
  • Military
  • ...

Customer option

  • SendMarketingEmails
  • ...

Activity State

  • Active
  • Deleted

Search customers

Searches for customers that are active at the moment in the enterprise (e.g. companions of checked-in reservations or paymasters).

Request

[PlatformAddress]/api/connector/v1/customers/search
{
"ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D",
"AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D",
"Client": "Sample Client 1.0.0",
"Name": "Smith",
"ResourceId": null,
"Extent": {
"Customers": true,
"Documents": false,
"Addresses": false
}
}
Property
Type
Contract
Description
ClientToken
string
required
Token identifying the client application.
AccessToken
string
required
Access token of the client application.
Client
string
required
Name and version of the client application.
Name
string
optional
Name to search by (applies to first name, last name and full name).
ResourceId
string
optional
Identifier of Resource to search by (members of Reservation assigned there will be returned).
Extent
required
Extent of data to be returned.

Response

{
"Customers": [
{
"Customer": {
"Address": null,
"BirthDate": null,
"BirthPlace": null,
"CategoryId": null,
"Classifications": [],
"CreatedUtc": "2016-01-01T00:00:00Z",
"Email": null,
"FirstName": "John",
"Sex": "Male",
"Id": "35d4b117-4e60-44a3-9580-c582117eff98",
"IdentityCard": null,
"LanguageCode": null,
"LastName": "Smith",
"LoyaltyCode": null,
"NationalityCode": "US",
"Notes": "",
"Number": "1",
"Options": [],
"Passport": null,
"Phone": "00420123456789",
"SecondLastName": null,
"TaxIdentificationNumber": null,
"Title": null,
"UpdatedUtc": "2016-01-01T00:00:00Z",
"Visa": null
},
"Reservation": null
}
]
}
Property
Type
Contract
Description
Customers
required
The customer search results.

Customer search result

Property
Type
Contract
Description
Customer
​Customer​
required
The found customer.
Reservation
optional
Reservation of the customer in case he currently stays in the enterprise.

Get customers open items

Returns all open items of the specified customers, i.e. all unpaid items and all deposited payments. Sum of the open items is the balance of the customer. If the Currency is specified, costs of the items are converted to that currency.

Request

[PlatformAddress]/api/connector/v1/customers/getOpenItems
{
"ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D",
"AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D",
"Client": "Sample Client 1.0.0",
"CustomerIds": [
"2a1a4315-7e6f-4131-af21-402cec59b8b9"
]
}
Property
Type
Contract
Description
ClientToken
string
required
Token identifying the client application.
AccessToken
string
required
Access token of the client application.
Client
string
required
Name and version of the client application.
CustomerIds
array of string
required, max 1000 items
Unique identifiers of the Customers.
Currency
string
optional
ISO-4217 code of the Currency the item costs should be converted to.

Response

{
"Customers": [
{
"CustomerId": "2a1a4315-7e6f-4131-af21-402cec59b8b9",
"OrderItems": [
{
"Id": "35820535-b988-4d6f-80cf-ecb19cdc3e58",
"AccountId": "2a1a4315-7e6f-4131-af21-402cec59b8b9",
"OrderId": "6645113e-72cc-4f99-ab77-e4452911bf20",
"BillId": null,
"AccountingCategoryId": "d250149e-a29d-4c70-b607-a1759faf7320",
"Amount": {
"Currency": "GBP",
"NetValue": -5.00,
"GrossValue": -5.00,
"TaxValues": [
{
"Code": "UK-Z",
"Value": 0.0
}
],
"Breakdown": {
"Items": [
{
"TaxRateCode": "UK-Z",
"NetValue": -5.00,
"TaxValue": 0.0
}
]
}
},
"RevenueType": "Additional",
"ConsumedUtc": "2017-04-04T15:13:39Z",
"ClosedUtc": null,
"AccountingState": "Open",
"Data": {
"Discriminator": "Rebate",
"Value": {
"RebatedItemId": null
}
}
}
],
"PaymentItems": []
}
]
}
Property
Type
Contract
Description
Customers
array of Customer items​
required
The customers with their items.

Customer items

Property
Type
Contract
Description
CustomerId
string
required
Unique identifier of the Customer.
OrderItems
array of Order item​
required
The open order items (consumed items such as nights or products).
PaymentItems
array of Payment item​
required
The open payment items (such as cash, credit card payments or invoices).

Add customer

Adds a new customer to the system and returns details of the added customer. If a customer with the specified email already exists, and OverwriteExisting is set to true, then the existing customer profile information is overwritten and the existing customer data returned. If OverwriteExisting is set to false, an error response is returned.

Request

[PlatformAddress]/api/connector/v1/customers/add
{
"ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D",
"AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D",
"Client": "Sample Client 1.0.0",
"OverwriteExisting": false,
"FirstName": "John",
"LastName": "Doe",
"SecondLastName": "the Second",
"Title": "Mister",
"Sex": "Male",
"NationalityCode": "US",
"BirthDate": "2000-01-01",
"BirthPlace": "Prague, Czech Republic",
"Email": "[email protected]",
"Phone": "00420123456789",
"LoyaltyCode": null,
"Notes": null,
"IdentityCard": {
"Number": "123456",
"Expiration": "2020-01-01",
"Issuance": "2016-01-01",
"IssuingCountryCode": "US"
},
"Passport": null,
"Visa": null,
"DriversLicense": null,
"Address": {
"Line1": "Astronautů 2",
"Line2": "",
"City": "Havířov",
"PostalCode": "736 01",
"CountryCode": "CZ",
"CountrySubdivisionCode": null,
},
"ItalianDestinationCode": "1234567"
}
Property
Type
Contract
Description
ClientToken
string
required
Token identifying the client application.
AccessToken
string
required
Access token of the client application.
Client
string
required
Name and version of the client application.
OverwriteExisting
bool
required
Whether an existing customer should be overwritten in case of duplicity. This applies only to basic personal information (Title, FirstName, LastName, ...).
FirstName
string
optional
First name of the customer.
LastName
string
required
Last name of the customer.
SecondLastName
string
optional
Second last name of the customer.
Title
string Title​
optional
Title prefix of the customer.
Sex
string Sex​
optional
Sex of the customer.
NationalityCode
string
optional
ISO 3166-1 code of the Country.
BirthDate
string
optional
Date of birth in ISO 8601 format.
BirthPlace
string
optional
Place of birth.
Email
string
optional
Email address of the customer.
Phone
string
optional
Phone number of the customer (possibly mobile).
LoyaltyCode
string
optional
Loyalty code of the customer.
Notes
string
optional
Internal notes about the customer.
CarRegistrationNumber
string
optional
Registration number of the customer's car.
TaxIdentificationNumber
string
optional
Tax identification number of the customer.
IdentityCard
​Document​
optional
Identity card details of the customer.
Passport
​Document​
optional
Passport details of the customer.
Visa
​Document​
optional
Visa details of the customer.
DriversLicense
​Document​
optional
Drivers license details of the customer.
Address
optional
Address of the customer.
Classifications
optional
Classifications of the customer.
Options
array of Customer option​
optional
Options of the customer.