openapi: 3.2.0
info:
  title: travelperk-api-v1 Trips API
  version: '1.5'
servers:
- url: https://api.travelperk.com/
security:
- sec0: []
tags:
- name: Trips
paths:
  /trips:
    get:
      summary: List all trips
      description: Trips listed in descending order of `modified` time.
      operationId: list-all-trips
      parameters:
      - name: modified_gte
        in: query
        description: Find Trips with modified greater than or equal to this time
        schema:
          type: string
          format: date
      - name: modified_lt
        in: query
        description: Find Trips with modified less than this time
        schema:
          type: string
          format: date
      - name: status
        in: query
        description: Filter for trips with this status
        schema:
          type: string
      - name: offset
        in: query
        description: Pagination offset index, 0 based
        schema:
          type: integer
          format: int32
          default: 0
      - name: limit
        in: query
        description: Pagination maximum number of elements to return. See more info in [Pagination](reference#pagination-1)
        schema:
          type: integer
          format: int32
          default: 10
      - name: traveler_id
        in: query
        description: Filter Trips by the users that they have on the trip
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value: "{\n    \"trips\": [\n        {\n            \"id\": \"172\",\n            \"trip_name\": \"The Great Voyage\",\n            \"start\": \"2020-11-20T00:00:00\",\n            \"end\": \"2020-11-25T00:00:00\",\n            \"status\": \"booked\",\n            \"modified\": \"2020-09-16T07:08:06.290253+00:00\",\n            \"booker_id\": \"123\",\n            \"start_location\": \n                {\n                    \"name\": \"Location Name\",\n                    \"address\": \"Address Info\",\n                    \"latitude\": \"59.5468062\",\n                    \"longitude\": \"113.9913155\",\n                    \"iata_code\": null,\n                },\n            \"end_location\": \n          \t\t\t{\n                    \"name\": \"Location Name\",\n                    \"address\": \"Address Info\",\n                    \"latitude\": \"59.5468062\",\n                    \"longitude\": \"113.9913155\",\n                    \"iata_code\": null,\n              \t}\n        },\n        {\n            \"id\": \"205\",\n            \"trip_name\": \"Road trip Barcelona\",\n            \"start\": \"2020-09-25T10:00:00+00:00\",\n            \"end\": \"2020-09-26T10:00:00+00:00\",\n            \"status\": \"booked\",\n            \"modified\": \"2020-09-14T12:55:06.720754+00:00\",\n\t\t\t\t\t\t\"booker_id\": \"123\",\n\t\t\t\t\t\t\"start_location\": \n                {\n                    \"name\": \"Location Name\",\n                    \"address\": \"Address Info\",\n                    \"latitude\": \"59.5468062\",\n                    \"longitude\": \"113.9913155\",\n                    \"iata_code\": null,\n                },\n            \"end_location\": \n          \t\t\t{\n                    \"name\": \"Location Name\",\n                    \"address\": \"Address Info\",\n                    \"latitude\": \"59.5468062\",\n                    \"longitude\": \"113.9913155\",\n                    \"iata_code\": null,\n              \t}\n        }\n    ],\n    \"limit\": 10,\n    \"offset\": 0,\n    \"total\": 2\n}"
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value: "{\n  \"error\":{\n    \"type\":\"bad_request\",\n    \"errors\":[\n      {\n        \"reason\":\"The status filter must be one of: booked, cancelled\"\n      }\n    ]\n  }\n}"
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        example: bad_request
                      errors:
                        type: array
                        items:
                          type: object
                          properties:
                            reason:
                              type: string
                              example: 'The status filter must be one of: booked, cancelled'
      deprecated: false
      x-readme:
        code-samples:
        - language: curl
          code: "curl -i \\\n  -H 'Authorization: ApiKey 123456.abcdefghijklmnopqrstuvwxyz123456' \\\n  -H 'Api-Version: 1' \\\n  -X GET https://api.travelperk.com/trips"
          name: cURL
        samples-languages:
        - curl
      tags:
      - Trips
  /trips/{id}:
    get:
      summary: Retrieve a Trip by ID
      description: Get a single trip with the Trip ID
      operationId: retrieve-a-trip-by-id
      parameters:
      - name: id
        in: path
        schema:
          type: integer
          format: int32
        required: true
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value: "{\n    \"id\": \"75\",\n    \"trip_name\": \"E2E cancel Openrail train ticket\",\n    \"start\": \"2025-04-18T10:57:38.762779+00:00\",\n    \"start_datetime_utc\": \"2025-04-18T08:57:38.762779+00:00\",\n    \"start_datetime_local\": \"2025-04-18T10:57:38.762779+02:00\",\n    \"end\": \"2025-04-18T10:57:38.762779+00:00\",\n    \"end_datetime_utc\": \"2025-04-18T08:57:38.762779+00:00\",\n    \"end_datetime_local\": \"2025-04-18T10:57:38.762779+02:00\",\n    \"status\": \"booked\",\n    \"modified\": \"2025-04-15T10:57:38.777869+00:00\",\n    \"start_location\": {\n        \"name\": \"Barcelona\",\n        \"address\": \"Barcelona - Barcelona, ES\",\n        \"latitude\": \"41.382270729\",\n        \"longitude\": \"2.177385092\",\n        \"iata_code\": null\n    },\n    \"end_location\": {\n        \"name\": \"Madrid\",\n        \"address\": \"Madrid - Madrid, ES\",\n        \"latitude\": \"40.416824000\",\n        \"longitude\": \"-3.703733000\",\n        \"iata_code\": null\n    },\n    \"booker_id\": \"18\"\n}"
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: '75'
                  trip_name:
                    type: string
                    example: E2E cancel Openrail train ticket
                  start:
                    type: string
                    example: '2025-04-18T10:57:38.762779+00:00'
                  start_datetime_utc:
                    type: string
                    example: '2025-04-18T08:57:38.762779+00:00'
                  start_datetime_local:
                    type: string
                    example: '2025-04-18T10:57:38.762779+02:00'
                  end:
                    type: string
                    example: '2025-04-18T10:57:38.762779+00:00'
                  end_datetime_utc:
                    type: string
                    example: '2025-04-18T08:57:38.762779+00:00'
                  end_datetime_local:
                    type: string
                    example: '2025-04-18T10:57:38.762779+02:00'
                  status:
                    type: string
                    example: booked
                  modified:
                    type: string
                    example: '2025-04-15T10:57:38.777869+00:00'
                  start_location:
                    type: object
                    properties:
                      name:
                        type: string
                        example: Barcelona
                      address:
                        type: string
                        example: Barcelona - Barcelona, ES
                      latitude:
                        type: string
                        example: '41.382270729'
                      longitude:
                        type: string
                        example: '2.177385092'
                      iata_code: {}
                  end_location:
                    type: object
                    properties:
                      name:
                        type: string
                        example: Madrid
                      address:
                        type: string
                        example: Madrid - Madrid, ES
                      latitude:
                        type: string
                        example: '40.416824000'
                      longitude:
                        type: string
                        example: '-3.703733000'
                      iata_code: {}
                  booker_id:
                    type: string
                    example: '18'
        '404':
          description: '404'
          content:
            application/json:
              examples:
                Result:
                  value: "{\n    \"error\": {\n        \"type\": \"not_found\",\n        \"errors\": [\n            {\n                \"reason\": \"Trip not found\"\n            }\n        ]\n    }\n}"
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        example: not_found
                      errors:
                        type: array
                        items:
                          type: object
                          properties:
                            reason:
                              type: string
                              example: Trip not found
      deprecated: false
      tags:
      - Trips
  /trips/{trip_id}/custom-fields:
    get:
      summary: Retrieve custom fields
      description: Get all custom field values associated with a trip.
      operationId: retrieve-custom-fields
      parameters:
      - name: trip_id
        in: path
        description: Unique identifier for the trip
        schema:
          type: string
        required: true
      - name: Authorization
        in: header
        description: API Key or OAuth access token. See Authentication documentation for details
        schema:
          type: string
          default: ApiKey 123456.abcdefghijklmnopqrstuvwxyz123456
      - name: Api-Version
        in: header
        description: The version of the API to call
        required: true
        schema:
          type: integer
          format: int32
          default: 1
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value: "{\n  \"trip_id\": 1234,\n  \"created_date\": \"2024-07-21\",\n  \"custom_fields\": [\n    {\n      \"name\": \"Event\",\n      \"value\": \"Christmas Party\"\n    }\n}"
      deprecated: false
      tags:
      - Trips
components:
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      x-default: ''
      name: Authorization
      x-bearer-format: token
x-readme-fauxas: true
x-provenance:
  method: searched
  source: https://developers.perk.com/reference
  harvested: '2026-10-14'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://developers.perk.com/reference/companies-1.md
  - https://developers.perk.com/reference/delete-webhook-subscription.md
  - https://developers.perk.com/reference/download-pdf.md
  - https://developers.perk.com/reference/get-invoice.md
  - https://developers.perk.com/reference/get-subscription-details.md
  - https://developers.perk.com/reference/list-all-bookings.md
  - https://developers.perk.com/reference/list-all-suppliers.md
  - https://developers.perk.com/reference/list-all-trips.md
  - https://developers.perk.com/reference/list-all-users-1.md
  - https://developers.perk.com/reference/list-events.md
  - https://developers.perk.com/reference/list-invoice-lines-1.md
  - https://developers.perk.com/reference/list-invoice-profiles.md
  - https://developers.perk.com/reference/list-invoice.md
  - https://developers.perk.com/reference/list-webhooks.md
  - https://developers.perk.com/reference/retrieve-a-trip-by-id.md
  - https://developers.perk.com/reference/retrieve-custom-fields.md
  - https://developers.perk.com/reference/subscribe-to-event.md
  - https://developers.perk.com/reference/test-webhook.md
  - https://developers.perk.com/reference/update-subscription.md
  merge:
    pages: 19
    deduped: 18
    conflicts_kept_first: 0