openapi: 3.0.1
info:
  title: Contacts endpoint
  description: Contains Contacts endpoint specification.
  contact: {}
  license: {}
  version: '1.0'
paths:
  /properties/{propertyId}/contacts:
    get:
      tags:
        - Contacts
      summary: Read all Contact(s) for a Property
      operationId: getAllContacts
      parameters:
        - name: Accept-Version
          in: header
          schema:
            type: string
        - name: propertyId
          in: path
          description: The Property ID of which you wish to retrieve the data
          required: true
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactInfoResponse'
    put:
      tags:
        - Contacts
      summary: Overlay multiple Contacts for a Property
      description: Contacts not sent will be reset/deleted.
      operationId: overwriteContacts
      parameters:
        - name: Accept-Version
          in: header
          schema:
            type: string
        - name: propertyId
          in: path
          description: The Property ID of which you wish to update the data
          required: true
          schema:
            type: integer
            format: int32
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactInfo'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
components:
  schemas:
    ApiError:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
        details:
          $ref: '#/components/schemas/ObjectNode'
    Contact:
      required:
        - contact_person
        - contact_profiles
        - email
        - phones
      type: object
      properties:
        contact_profiles:
          type: array
          description: >-
            Type of Contact Profiles. Each value corresponds with a similarly
            named heading on the Contacts page.

            Validation: Must be one of provided values.

            [Current
            Documentation](/connectivity/docs/api-reference/contactinfo/#contactprofiletype)

            DataMapping: ContactInfo/ContactProfileType
          items:
            $ref: '#/components/schemas/ContactProfile'
        address:
          $ref: '#/components/schemas/ContactAddress'
        contact_person:
          $ref: '#/components/schemas/ContactPerson'
        phones:
          type: array
          description: |-
            Validation: Cannot be null/empty
            PhoneTechType 1 can have at most 3 entries.
            PhoneTechType 3 and 5 can have at most 1 entry.
            Extension can only be provided for PhoneTechType 1
            DataMapping: ContactInfo/Phones
          items:
            $ref: '#/components/schemas/ContactPhone'
        email:
          type: string
          description: |-
            Email address for a contact person/point.
            Validation: Email must be of a standard format.
            [Current Documentation](/connectivity/docs/api-reference/email/)
            DataMapping: ContactInfo/Emails/Email
      description: One Single Contact Object
    ContactAddress:
      required:
        - country_code
      type: object
      properties:
        city_name:
          type: string
          description: >-
            The name of the city, town, or village.

            Validation: We do not allow CJK Unified Ideographs

            [Current Documentation:
            CityName](/connectivity/docs/api-reference/address/)

            DataMapping: ContactInfo/Addresses/CityName
        country_code:
          type: string
          description: >-
            The country code of the contact address.

            Validation: One of [Two-letter country
            code](/connectivity/docs/b_xml-countries/).

            Country codes follow ISO 3166

            [Current Documentation:
            CountryName](/connectivity/docs/api-reference/address)

            DataMapping: ContactInfo/Addresses/CountryName
        postal_code:
          type: string
          description: >-
            Postal/zip code.

            Validation: We validate against country specific post code formats.

            [Current Documentation:
            PostalCode](/connectivity/docs/api-reference/address)

            DataMapping: ContactInfo/Addresses/PostalCode
        address_line:
          maxLength: 255
          minLength: 1
          type: string
          description: >-
            The full street name and number.

            Should not contain abbreviations (such as "Rd." for "Road") and
            should not exceed 255 characters.

            Validations: Minimum 1 at most 255 characters. We also do not allow
            CJK Unified Ideographs.

            [Current Documentation:
            AddressLine](/connectivity/docs/api-reference/address)

            DataMapping: ContactInfo/Addresses/AddressLine
        language_code:
          type: string
          description: >-
            The language code for the address details.

            Validation: One of [Booking.com Language
            Code](/connectivity/docs/codes-bcl/)

            Default: en

            [Current Documentation:
            Language](/connectivity/docs/api-reference/address)

            DataMapping: ContactInfo/Addresses/Language
    ContactInfo:
      required:
        - contacts
      type: object
      properties:
        contacts:
          type: array
          description: >-
            General contact type is mandatory for setting up the property.

            Validation: ContactProfileType entries cannot be repeated within the
            same array.

            General contact can have only 1 entry in total.

            [Current Documentation: ContactInfo Root
            Object](/connectivity/docs/api-reference/contactinfo)
          items:
            $ref: '#/components/schemas/Contact'
      description: List of all contacts
    ContactInfoResponse:
      type: object
      properties:
        ruid:
          type: string
          writeOnly: true
        data:
          $ref: '#/components/schemas/ContactInfo'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/ApiError'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiError'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    ContactPerson:
      required:
        - language_code
        - name
      type: object
      properties:
        gender:
          pattern: male|female
          type: string
          description: >-
            Contact person's gender.

            Validation: One of valid value.

            [Current Documentation:
            Gender](/connectivity/docs/api-reference/name)

            DataMapping: ContactInfo/Names/Gender
          enum:
            - male, female
        name:
          type: string
          description: >-
            Contact person's given name/full name.

            Validation: Cannot be empty or null.

            [Current Documentation:
            GivenName](/connectivity/docs/api-reference/name)

            DataMapping: ContactInfo/Names/GivenName
        job_title:
          type: string
          description: >-
            The contact's Job Title.

            Validation: One of valid [Booking.com Job Title
            Code](/connectivity/docs/codes-bcjt/).

            Default: Unknown

            [Current Documentation:
            JobTitle](/connectivity/docs/api-reference/name)

            DataMapping: ContactInfo/Names/JobTitle
        language_code:
          type: string
          description: >-
            The contact's spoken language.

            Validation: One of valid language codes provided [Booking.com
            Language Code](/connectivity/docs/codes-bcl/)

            [Current Documentation:
            Language](/connectivity/docs/api-reference/name)

            DataMapping: ContactInfo/Names/Language
      description: |
        Name details for a contact person.
        [Current Documentation](/connectivity/docs/api-reference/name)
    ContactPhone:
      required:
        - phone_number
        - phone_tech_type
      type: object
      properties:
        phone_number:
          type: string
          description: >-
            The international phone number.

            Validation: We validate for country specific formats for the number
            against the address provided.

            [Current Documentation:
            PhoneNumber](/connectivity/docs/api-reference/phone/)

            DataMapping: ContactInfo/Phones/PhoneNumber
        phone_tech_type:
          type: integer
          description: >-
            The type of phone line/device.

            Validations: One of a valid value.

            [Current Documentation:
            PhoneTechType](/connectivity/docs/api-reference/phone)

            DataMapping: ContactInfo/Phones/PhoneTechType
          format: int32
          enum:
            - null
        extension:
          type: string
          description: >-
            The extension number that must be dialled in addition to the
            @PhoneNumber.

            Validation: Only accepted when @PhoneTechType= "1".

            [Current Documentation:
            Extension](/connectivity/docs/api-reference/phone/)

            DataMapping: ContactInfo/Phones/Extension
      description: |-
        Phone number details for a contact person/point. Can be more than 1.
        [Current Documentation](/connectivity/docs/api-reference/phone)
    ContactProfile:
      required:
        - type
      type: object
      properties:
        type:
          type: string
          description: >-
            Type of Contact Profile. Each value corresponds with a similarly
            named heading on the Contacts page.

            [Current
            Documentation](/connectivity/docs/api-reference/contactinfo/#contactprofiletype)

            DataMapping: ContactInfo/ContactProfileType
          enum:
            - general
            - contract
            - reservations
            - invoices
            - availability
            - site_content
            - parity
            - requests
            - central_reservations
      description: One Single Contact Profile Object
    ObjectNode:
      type: object
    ResponseMeta:
      type: object
      properties:
        ruid:
          type: string
    ApiResponse:
      type: object
      properties:
        ruid:
          type: string
          writeOnly: true
        data:
          type: object
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/ApiError'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiError'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
