PUDO locations

Retrieve PUDO Locations

Searches the pick-up/drop-off locations (parcel lockers, service points, post offices, parcel shops) of your configured carriers, with standardized addresses, location types, and operating hours. Feed a selected location’s pudo_location_uuid into Create Booking to route the label there.

Required search criteria: provide either pudo_location_uuid (to fetch one location — it takes priority over every other filter) or postal_code together with country_code. For the widest results, add coordinates with radius_meters (default 100 km): filter-based search is exact-match, while area-based search returns everything in range, sorted by distance_meters.

No match returns HTTP 200 with count: 0 and empty data.

Deprecations: the uuid parameter/field is replaced by pudo_location_uuid (removal end of July 2026); the single-value location_type / mapped_location_type address fields are replaced by the list fields location_types / mapped_location_types (removal end of August 2026).

GET

pudo-locations

Retrieve PUDO Locations

curl --request GET \
  --url https://api.perform.ai/v5/pudo-locations/ \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.perform.ai/v5/pudo-locations/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.perform.ai/v5/pudo-locations/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.perform.ai/v5/pudo-locations/"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.perform.ai/v5/pudo-locations/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "message": "<string>",
  "count": 123,
  "data": [
    {
      "pudo_location_uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "carrier_id": "<string>",
      "pudo_location_id": "<string>",
      "address": {
        "location_types": [
          "<string>"
        ],
        "mapped_location_types": [
          "<string>"
        ],
        "location_type": "<string>",
        "mapped_location_type": "<string>",
        "entity_reference": "<string>",
        "address_name": "<string>",
        "full": "<string>",
        "line1": "<string>",
        "line2": "<string>",
        "line3": "<string>",
        "street_name": "<string>",
        "house_number": "<string>",
        "postal_code": "<string>",
        "city": "<string>",
        "state_or_province": "<string>",
        "region": "<string>",
        "country": "<string>",
        "country_code": "<string>",
        "phone": "<string>"
      },
      "lat": 123,
      "lng": 123,
      "distance_meters": 123,
      "operating_hours_calc": [
        {
          "service_name": "<string>",
          "operating_day": "<string>",
          "time_zone": "<string>",
          "first_open_hours": "<string>",
          "second_open_hours": "<string>",
          "first_cutoff": "<string>",
          "second_cutoff": "<string>"
        }
      ],
      "opening_hours": [
        {
          "day_of_week": "<string>",
          "open_hour": "<string>",
          "close_hour": "<string>"
        }
      ],
      "cutoff_hours": [
        {
          "service": "<string>",
          "day_of_week": "<string>",
          "cutoff_at": "<string>"
        }
      ],
      "closing_periods": [
        {
          "from_date": "<string>",
          "to_date": "<string>",
          "reason": "<string>"
        }
      ],
      "validity_period": {
        "from_date": "<string>",
        "to_date": "<string>"
      },
      "services": [
        "<string>"
      ],
      "additional_info": {},
      "updated_date": "<string>"
    }
  ]
}

{
  "api_response": "<string>",
  "message": "<string>",
  "errors": {}
}

{
  "api_response": 403,
  "message": "Key not authorized"
}

{
  "api_response": 429,
  "message": "Throttled"
}

{
  "api_response": "500",
  "message": "System error"
}

Authorizations

Authorization

string

header

required

Used by every functional endpoint. Generate the token with POST /auth/oauth/token/ and send it as Authorization: Bearer {token}.

Query Parameters

pudo_location_uuid

string<uuid>

Fetch one specific location. Takes priority over all other filters.

uuid

string<uuid>

Legacy name for pudo_location_uuid. Removed end of July 2026.

postal_code

string

Postal code to search in, together with country_code. Required when pudo_location_uuid is not provided.

country_code

string

ISO 3166-1 alpha-2 country code, together with postal_code. Required when pudo_location_uuid is not provided.

pudo_location_id

string

Carrier-unique PUDO location ID.

carrier_ids

string

Comma-separated Perform.AI carrier IDs (from Carrier configurations) to filter by carrier.

coordinates

string

latitude,longitude for area search and distance calculation, e.g. 52.5200,13.4050.

radius_meters

integer

default:100000

Search radius for coordinate search. Default 100 km.

string

Full address string (street, number, postal code, city) used to find nearby locations and compute distance.

location_types

string

Comma-separated carrier-original location types to filter by.

mapped_location_types

string

Comma-separated Perform.AI standardized location types to filter by.

limit

integer

default:25

Locations per page.

Required range: 1 <= x <= 100

page

integer

default:1

Page number.

Response

Matching locations (empty data and count: 0 when none). Note this endpoint's envelope has no api_response field.

message

string

E.g. Total pages: 2.

count

integer

Locations in this response.

data

object[]

Show child attributes

Retrieve PUDO Locations

curl --request GET \
  --url https://api.perform.ai/v5/pudo-locations/ \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.perform.ai/v5/pudo-locations/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.perform.ai/v5/pudo-locations/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.perform.ai/v5/pudo-locations/"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.perform.ai/v5/pudo-locations/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "message": "<string>",
  "count": 123,
  "data": [
    {
      "pudo_location_uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "carrier_id": "<string>",
      "pudo_location_id": "<string>",
      "address": {
        "location_types": [
          "<string>"
        ],
        "mapped_location_types": [
          "<string>"
        ],
        "location_type": "<string>",
        "mapped_location_type": "<string>",
        "entity_reference": "<string>",
        "address_name": "<string>",
        "full": "<string>",
        "line1": "<string>",
        "line2": "<string>",
        "line3": "<string>",
        "street_name": "<string>",
        "house_number": "<string>",
        "postal_code": "<string>",
        "city": "<string>",
        "state_or_province": "<string>",
        "region": "<string>",
        "country": "<string>",
        "country_code": "<string>",
        "phone": "<string>"
      },
      "lat": 123,
      "lng": 123,
      "distance_meters": 123,
      "operating_hours_calc": [
        {
          "service_name": "<string>",
          "operating_day": "<string>",
          "time_zone": "<string>",
          "first_open_hours": "<string>",
          "second_open_hours": "<string>",
          "first_cutoff": "<string>",
          "second_cutoff": "<string>"
        }
      ],
      "opening_hours": [
        {
          "day_of_week": "<string>",
          "open_hour": "<string>",
          "close_hour": "<string>"
        }
      ],
      "cutoff_hours": [
        {
          "service": "<string>",
          "day_of_week": "<string>",
          "cutoff_at": "<string>"
        }
      ],
      "closing_periods": [
        {
          "from_date": "<string>",
          "to_date": "<string>",
          "reason": "<string>"
        }
      ],
      "validity_period": {
        "from_date": "<string>",
        "to_date": "<string>"
      },
      "services": [
        "<string>"
      ],
      "additional_info": {},
      "updated_date": "<string>"
    }
  ]
}

{
  "api_response": "<string>",
  "message": "<string>",
  "errors": {}
}

{
  "api_response": 403,
  "message": "Key not authorized"
}

{
  "api_response": 429,
  "message": "Throttled"
}

{
  "api_response": "500",
  "message": "System error"
}

Overview

Authentication

Shipments

Booking

Documents

PUDO locations

Carrier configurations

Events

Returns

Webhooks

Checkout

Retrieve PUDO Locations

Authorizations

Query Parameters

Response