Mews Exports API

openapi: 3.0.4
info:
  title: Connector Account notes Exports 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: Exports
paths:
  /api/connector/v1/exports/add:
    post:
      tags:
      - Exports
      summary: Add export
      description: Creates a new pending export for all entities of the specified `EntityType`. If an export with status Pending or Processing already exists for the same entity type, the request will be rejected. Successfully created exports remain available for download until the expiration date specified in ExpiresUtc. This operation supports [Portfolio Access Tokens](https://mews-systems.gitbook.io/connector-api/concepts/multi-property/).
      operationId: exports_add
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportAddParameters'
            example:
              ClientToken: E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D
              AccessToken: C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D
              Client: Sample Client 1.0.0
              EntityType: Reservation
              Scope:
                EnterpriseIds:
                - 3fa85f64-5717-4562-b3fc-2c963f66afa6
              Filters:
                UpdatedUtc:
                  StartUtc: '2020-11-04T00:00:00Z'
                  EndUtc: '2020-11-05T00:00:00Z'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportAddResult'
              example:
                Export:
                  Id: 09708665-0e31-4b23-b337-b0a000be0df0
                  Status: Pending
                  EntityType: Reservation
                  Scope:
                    EnterpriseIds:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    ChainIds: null
                  Files: []
                  ExpiresUtc: null
                  Filters:
                    UpdatedUtc:
                      StartUtc: '2020-11-04T00:00:00Z'
                      EndUtc: '2020-11-05T00:00:00Z'
                    LedgerEntryFilters: null
        '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'
      x-restricted: true
  /api/connector/v1/exports/getAll:
    post:
      tags:
      - Exports
      summary: Get all exports
      description: Returns exports for the given `ExportIds`. This operation supports [Portfolio Access Tokens](https://mews-systems.gitbook.io/connector-api/concepts/multi-property/).
      operationId: exports_getAll
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportFilterParameters'
            example:
              ClientToken: E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D
              AccessToken: C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D
              Client: Sample Client 1.0.0
              ExportIds:
              - 3fa85f64-5717-4562-b3fd-2c963f66afa6
              - 5f51c9ef-fc1d-4438-90ad-6b925ab7d7a9
              - 706dc6d5-9511-4751-825e-538ce99da2ce
              - f776f20a-6f1a-4ddf-93f4-9dae95261415
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportResult'
              example:
                Exports:
                - Id: 3fa85f64-5717-4562-b3fd-2c963f66afa6
                  Status: Success
                  EntityType: OrderItem
                  Scope:
                    EnterpriseIds:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    - 4d0201db-36f5-428b-8d11-4f0a65e960cc
                    ChainIds: null
                  Files:
                  - Url: https://example.com/exports/3fa85f64-5717-4562-b3fd-2c963f66afa6-1.jsonl?example=signature
                    SizeInBytes: 1215279
                  - Url: https://example.com/exports/3fa85f64-5717-4562-b3fd-2c963f66afa6-2.jsonl?example=signature
                    SizeInBytes: 1398362
                  ExpiresUtc: '2023-10-26T11:42:28Z'
                  Filters:
                    UpdatedUtc:
                      StartUtc: '2020-11-04T00:00:00Z'
                      EndUtc: '2020-11-05T00:00:00Z'
                    LedgerEntryFilters: null
                - Id: 5f51c9ef-fc1d-4438-90ad-6b925ab7d7a9
                  Status: Pending
                  EntityType: LedgerEntry
                  Scope:
                    EnterpriseIds:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    ChainIds: null
                  Files: []
                  ExpiresUtc: null
                  Filters:
                    UpdatedUtc: null
                    LedgerEntryFilters:
                      Posting:
                        Start: '2024-01-01'
                        End: '2024-01-31'
                - Id: 706dc6d5-9511-4751-825e-538ce99da2ce
                  Status: Processing
                  EntityType: Company
                  Scope:
                    EnterpriseIds: null
                    ChainIds:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  Files: []
                  ExpiresUtc: null
                  Filters: null
                - Id: f776f20a-6f1a-4ddf-93f4-9dae95261415
                  Status: Expired
                  EntityType: OrderItem
                  Scope:
                    EnterpriseIds:
                    - 3fa85f64-5717-4562-b3fc-2c963f66afa6
                    ChainIds: null
                  Files: []
                  ExpiresUtc: '2023-10-24T14:12:30Z'
                  Filters: null
        '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'
      x-restricted: true
components:
  schemas:
    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
    ExportScope:
      title: Export scope
      type: object
      properties:
        EnterpriseIds:
          maxItems: 1000
          minItems: 1
          type: array
          items:
            type: string
            format: uuid
          description: Unique identifiers of enterprises for which the data is exported.
          nullable: true
        ChainIds:
          maxItems: 1000
          minItems: 1
          type: array
          items:
            type: string
            format: uuid
          description: Unique identifiers of chains for which the data is exported.
          nullable: true
      additionalProperties: false
      x-schema-id: ExportScope
    ExportStatusEnum:
      title: Export status
      enum:
      - Pending
      - Processing
      - Success
      - Failed
      - Expired
      type: string
      description: 'Current status of the export.


        Pending


        Processing


        Success


        Failed


        Expired'
      x-enumNames:
      - Pending
      - Processing
      - Success
      - Failed
      - Expired
      x-enumDescriptions:
      - ''
      - ''
      - ''
      - ''
      - ''
    ExportEntityTypeEnum:
      title: Exported entity type
      enum:
      - OrderItem
      - Payment
      - Reservation
      - Customer
      - Company
      - Bill
      - AvailabilityAdjustment
      - AvailabilityBlock
      - ResourceBlock
      - LedgerEntry
      type: string
      description: 'Type of exported entities


        OrderItem


        Payment


        Reservation


        Customer


        Company


        Bill


        AvailabilityAdjustment


        AvailabilityBlock


        ResourceBlock


        LedgerEntry (**Beta testing - subject to change.** See [Ledger entry type](https://docs.mews.com/connector-api/operations/_export-types#ledger-entry).)'
      x-enumNames:
      - OrderItem
      - Payment
      - Reservation
      - Customer
      - Company
      - Bill
      - AvailabilityAdjustment
      - AvailabilityBlock
      - ResourceBlock
      - LedgerEntry
      x-enumDescriptions:
      - ''
      - ''
      - ''
      - ''
      - ''
      - ''
      - ''
      - ''
      - ''
      - '**Beta testing - subject to change.** See [Ledger entry type](https://docs.mews.com/connector-api/operations/_export-types#ledger-entry).'
    ExportDataFilters:
      title: Export data filters
      type: object
      properties:
        UpdatedUtc:
          title: Time interval
          allOf:
          - $ref: '#/components/schemas/TimeFilterInterval'
          description: Filters entities by the specified UTC update interval. The end of the interval must be no later than 5 minutes in the past. The maximum interval is 180 days.
          nullable: true
        LedgerEntryFilters:
          title: Export ledger entry data filters
          allOf:
          - $ref: '#/components/schemas/ExportLedgerEntryDataFilters'
          description: Filters specific to the `LedgerEntry` entity type. Required when `EntityType` is `LedgerEntry`.
          nullable: true
      additionalProperties: false
      x-schema-id: ExportDataFilters
    ExportLedgerEntryDataFilters:
      title: Export ledger entry data filters
      required:
      - Posting
      type: object
      properties:
        Posting:
          title: Date filter interval
          allOf:
          - $ref: '#/components/schemas/DateFilterInterval'
          description: Filters ledger entries by their posting date within the specified date interval, inclusive of both the start and end dates.
      additionalProperties: false
      x-schema-id: ExportLedgerEntryDataFilters
    ExportAddParameters:
      title: ExportAddParameters
      required:
      - AccessToken
      - Client
      - ClientToken
      - EntityType
      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.
        EntityType:
          allOf:
          - $ref: '#/components/schemas/ExportEntityTypeEnum'
          description: 'Specifies the type of entity which should be exported.


            OrderItem


            Payment


            Reservation


            Customer


            Company


            Bill


            AvailabilityAdjustment


            AvailabilityBlock


            ResourceBlock


            LedgerEntry (**Beta testing - subject to change.** See [Ledger entry type](https://docs.mews.com/connector-api/operations/_export-types#ledger-entry).)'
        Scope:
          title: Export scope parameters
          allOf:
          - $ref: '#/components/schemas/ExportScopeParameters'
          description: Selects enterprises or chains for which the data should be exported. Which one is used depends on `EntityType`. If not specified, the export will include all enterprises or chains the client has access to.
          nullable: true
        Filters:
          title: Export data filters
          allOf:
          - $ref: '#/components/schemas/ExportDataFilters'
          description: Specifies filters to apply on the exported data set. If omitted, the export will include all available data.
          nullable: true
      additionalProperties: false
      x-schema-id: ExportAddParameters
    ExportFileEntry:
      title: Export file entry
      required:
      - SizeInBytes
      - Url
      type: object
      properties:
        Url:
          minLength: 1
          type: string
          description: Download URL for the exported file in JSON Lines format. The link remains valid for 10 minutes after it is returned.
          format: uri
        SizeInBytes:
          type: integer
          description: Total size of the exported file in bytes.
          format: int64
      additionalProperties: false
      x-schema-id: ExportFileEntry
    Export:
      title: Export
      required:
      - EntityType
      - Files
      - Id
      - Scope
      - Status
      type: object
      properties:
        Id:
          type: string
          description: Unique identifier of the export.
          format: uuid
        Status:
          title: Export status
          allOf:
          - $ref: '#/components/schemas/ExportStatusEnum'
          description: 'Export status.


            Pending


            Processing


            Success


            Failed


            Expired'
          x-enumNames:
          - Pending
          - Processing
          - Success
          - Failed
          - Expired
          x-enumDescriptions:
          - ''
          - ''
          - ''
          - ''
          - ''
        EntityType:
          title: Exported entity type
          allOf:
          - $ref: '#/components/schemas/ExportEntityTypeEnum'
          description: 'Exported entity type.


            OrderItem


            Payment


            Reservation


            Customer


            Company


            Bill


            AvailabilityAdjustment


            AvailabilityBlock


            ResourceBlock


            LedgerEntry (**Beta testing - subject to change.** See [Ledger entry type](https://docs.mews.com/connector-api/operations/_export-types#ledger-entry).)'
          x-enumNames:
          - OrderItem
          - Payment
          - Reservation
          - Customer
          - Company
          - Bill
          - AvailabilityAdjustment
          - AvailabilityBlock
          - ResourceBlock
          - LedgerEntry
          x-enumDescriptions:
          - ''
          - ''
          - ''
          - ''
          - ''
          - ''
          - ''
          - ''
          - ''
          - '**Beta testing - subject to change.** See [Ledger entry type](https://docs.mews.com/connector-api/operations/_export-types#ledger-entry).'
        Scope:
          title: Export scope
          allOf:
          - $ref: '#/components/schemas/ExportScope'
          description: The scope of the export, i.e. which enterprises or chains the data is exported for.
        Files:
          type: array
          items:
            $ref: '#/components/schemas/ExportFileEntry'
          description: Files with exported data. Empty if no files are available or the export is expired.
        ExpiresUtc:
          type: string
          description: Expiration date and time of the export in UTC timezone in ISO 8601 format. After this time the Exported files may no longer be available for download.
          format: date-time
          nullable: true
        Filters:
          title: Export data filters
          allOf:
          - $ref: '#/components/schemas/ExportDataFilters'
          description: Filters applied to the exported data set. If omitted, all available data is included in the export.
          nullable: true
      additionalProperties: false
      x-schema-id: Export
    ExportAddResult:
      title: ExportAddResult
      required:
      - Export
      type: object
      properties:
        Export:
          allOf:
          - $ref: '#/components/schemas/Export'
          description: Added export.
      additionalProperties: false
      x-schema-id: ExportAddResult
    DateFilterInterval:
      title: Date filter interval
      required:
      - End
      - Start
      type: object
      properties:
        Start:
          minLength: 1
          type: string
          description: Starting date of the interval in ISO 8601 format.
          format: date
        End:
          minLength: 1
          type: string
          description: Ending date of the interval in ISO 8601 format.
          format: date
      additionalProperties: false
      x-schema-id: DateFilterInterval
    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
    ExportResult:
      title: ExportResult
      required:
      - Exports
      type: object
      properties:
        Exports:
          type: array
          items:
            $ref: '#/components/schemas/Export'
          description: Requested exports.
      additionalProperties: false
      x-schema-id: ExportResult
    ExportScopeParameters:
      title: Export scope parameters
      type: object
      properties:
        EnterpriseIds:
          maxItems: 1000
          minItems: 1
          type: array
          items:
            type: string
            format: uuid
          description: Unique identifiers of the enterprises to export data for. If not specified, data for all enterprises within the access token's scope will be returned.
          nullable: true
        ChainIds:
          maxItems: 1000
          minItems: 1
          type: array
          items:
            type: string
            format: uuid
          description: Unique identifiers of the chains to export data for. If not specified, data for all chains within the access token's scope will be returned.
          nullable: true
      additionalProperties: false
      x-schema-id: ExportScopeParameters
    ExportFilterParameters:
      title: Export filter parameters
      required:
      - AccessToken
      - Client
      - ClientToken
      - ExportIds
      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.
        ExportIds:
          maxItems: 1000
          minItems: 1
          type: array
          items:
            type: string
            format: uuid
          description: Unique identifiers of the [Exports](https://mews-systems.gitbook.io/connector-api/operations/#export).
      additionalProperties: false
      x-schema-id: ExportFilterParameters