openapi: 3.0.3
info:
  title: parcelLab Campaigns Place Info API
  description: 'parcelLab API v4 Enhanced — the REST API for the parcelLab post-purchase

    experience platform. Send orders and trackings, retrieve order status,

    look up pickup/drop-off locations, predict delivery dates, manage return

    registrations and configurations, evaluate marketing campaigns, and

    publish surveys to your customers.


    Regional base URLs are available for EU and US workloads in addition to

    the global endpoint.

    '
  version: '4'
  contact:
    name: parcelLab Developer Support
    url: https://docs.parcellab.com/docs/developers/readme
  license:
    name: Proprietary
    url: https://parcellab.com/legal/terms-of-service/
servers:
- url: https://api.parcellab.com
  description: Global production endpoint
- url: https://api.eu.parcellab.com
  description: EU regional endpoint
- url: https://api.us.parcellab.com
  description: US regional endpoint
security:
- parcellabApiToken: []
tags:
- name: Place Info
  description: Look up nearby pickup and drop-off (PUDO) locations.
paths:
  /v4/track/place-info/lookup/:
    post:
      tags:
      - Place Info
      summary: Look Up Pickup/Drop-Off Locations
      operationId: lookupPlaceInfo
      description: Find nearby PUDO points for one or more couriers, ranked by distance from a geo-coordinate or address.
      parameters:
      - in: query
        name: account
        schema:
          type: array
          items:
            type: integer
      - in: query
        name: ordering
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlaceInfoLookupRequest'
      responses:
        '200':
          description: Matching PUDO points.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PlaceInfoLookupResponseItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
components:
  responses:
    Forbidden:
      description: Token lacks required permissions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid payload or query parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    Address:
      type: object
      properties:
        name:
          type: string
        street:
          type: string
        house_no:
          type: string
        city:
          type: string
        postal_code:
          type: string
        country_iso3:
          type: string
        state:
          type: string
        phone:
          type: string
        email:
          type: string
          format: email
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
        errors:
          type: object
          additionalProperties: true
    PlaceInfoLookupRequest:
      type: object
      required:
      - account
      - lookups
      - country_iso3
      properties:
        account:
          type: integer
        country_iso3:
          type: string
        lookups:
          type: array
          minItems: 1
          maxItems: 3
          items:
            $ref: '#/components/schemas/PlaceInfoLookupItem'
        location:
          type: object
          properties:
            latitude:
              type: number
            longitude:
              type: number
        external_reference:
          type: string
        location_address:
          $ref: '#/components/schemas/Address'
    PlaceInfoLookupItem:
      type: object
      properties:
        courier:
          type: string
        service_level:
          type: string
        query:
          type: string
    PlaceInfoLookupResponseItem:
      type: object
      properties:
        courier:
          type: string
        place_type:
          type: string
          enum:
          - default
          - self-service
          - partner
          - store
          - other
        address:
          $ref: '#/components/schemas/Address'
        location:
          type: object
          properties:
            latitude:
              type: number
            longitude:
              type: number
        opening_hours:
          type: object
          additionalProperties: true
        distance_meters:
          type: integer
        services:
          type: array
          items:
            type: string
        phone:
          type: string
        website:
          type: string
          format: uri
        external_reference:
          type: string
  securitySchemes:
    parcellabApiToken:
      type: apiKey
      in: header
      name: Authorization
      description: '`Authorization: Parcellab-API-Token <base64(account_id:token)>`. App- generated tokens may instead use the `Bearer <token>` scheme.'