Search locations

POST

api

{version}

locations

Search locations

curl --request POST \
  --url https://integrations.alvys.com/api/p/v{version}/locations/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json-patch+json' \
  --data '
{
  "Page": 123,
  "PageSize": 123,
  "Status": [
    "<string>"
  ],
  "LocationIds": [
    "<string>"
  ],
  "CreatedDateRange": {
    "Start": "2023-11-07T05:31:56Z",
    "End": "2023-11-07T05:31:56Z"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json-patch+json'},
  body: JSON.stringify({
    Page: 123,
    PageSize: 123,
    Status: ['<string>'],
    LocationIds: ['<string>'],
    CreatedDateRange: {Start: '2023-11-07T05:31:56Z', End: '2023-11-07T05:31:56Z'}
  })
};

fetch('https://integrations.alvys.com/api/p/v{version}/locations/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://integrations.alvys.com/api/p/v{version}/locations/search"

payload = {
    "Page": 123,
    "PageSize": 123,
    "Status": ["<string>"],
    "LocationIds": ["<string>"],
    "CreatedDateRange": {
        "Start": "2023-11-07T05:31:56Z",
        "End": "2023-11-07T05:31:56Z"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json-patch+json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://integrations.alvys.com/api/p/v{version}/locations/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'Page' => 123,
    'PageSize' => 123,
    'Status' => [
        '<string>'
    ],
    'LocationIds' => [
        '<string>'
    ],
    'CreatedDateRange' => [
        'Start' => '2023-11-07T05:31:56Z',
        'End' => '2023-11-07T05:31:56Z'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json-patch+json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://integrations.alvys.com/api/p/v{version}/locations/search"

	payload := strings.NewReader("{\n  \"Page\": 123,\n  \"PageSize\": 123,\n  \"Status\": [\n    \"<string>\"\n  ],\n  \"LocationIds\": [\n    \"<string>\"\n  ],\n  \"CreatedDateRange\": {\n    \"Start\": \"2023-11-07T05:31:56Z\",\n    \"End\": \"2023-11-07T05:31:56Z\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json-patch+json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://integrations.alvys.com/api/p/v{version}/locations/search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json-patch+json")
  .body("{\n  \"Page\": 123,\n  \"PageSize\": 123,\n  \"Status\": [\n    \"<string>\"\n  ],\n  \"LocationIds\": [\n    \"<string>\"\n  ],\n  \"CreatedDateRange\": {\n    \"Start\": \"2023-11-07T05:31:56Z\",\n    \"End\": \"2023-11-07T05:31:56Z\"\n  }\n}")
  .asString();

{
  "Page": 123,
  "PageSize": 123,
  "Total": 123,
  "Items": [
    {
      "Id": "<string>",
      "Name": "<string>",
      "CompanyNumber": "<string>",
      "Type": "<string>",
      "Status": "<string>",
      "Email": [
        "<string>"
      ],
      "Phone": [
        "<string>"
      ],
      "Notes": [
        {
          "id": "<string>",
          "Description": "<string>",
          "NoteType": "<string>",
          "User": "<string>",
          "Time": "2023-11-07T05:31:56Z",
          "UserId": "<string>"
        }
      ],
      "PhysicalAddress": {
        "Street": "<string>",
        "City": "<string>",
        "State": "<string>",
        "ZipCode": "<string>"
      },
      "Fax": "<string>",
      "DateCreated": "2023-11-07T05:31:56Z",
      "ExternalId": "<string>"
    }
  ],
  "Facets": {}
}

{
  "Errors": {},
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

The Locations endpoint provides detailed information about company-related sites such as Terminals, Shippers/Consignees, Cold Warehouses, and Dry Warehouses. The endpoint for searching locations requires specifying the API version in the path and providing filters in the request body. For details on API versioning, see Versioning.

Request Parameters

Path parameters

Parameter	Type	Required	Description
version	String	Yes	The API version to use.

Request body (filters + paging)

Parameter	Type	Required	Description
Page	Integer	No	Page index.
PageSize	Integer	Yes	Page size (must be > 0).
Status	Array of String	No	Filter by one or more location statuses. Supported values: `"Active"`, `"Disabled"`, `"Inactive"`.
LocationIds	Array of String	No	Filter by a set of Location IDs.
CreatedDateRange	Object	No	Filter by creation timestamp range (UTC).
CreatedDateRange.Start	String (DateTime)	No	Start of the date range.
CreatedDateRange.End	String (DateTime)	No	End of the date range.

Example cURL request

curl --location 'https://integrations.alvys.com/api/p/v1/locations/search' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "Page": 0,
  "PageSize": 100,
  "Status": ["Active",  "Disabled", "Inactive"],
  "LocationIds": [],
  "CreatedDateRange": {
    "Start": "2025-01-01T00:00:00Z",
    "End": "2025-09-08T23:59:59Z"
  }
}'

Response Parameters

Parameter	Type	Description
Page	integer	The current page number.
Total	integer	The total number of items matching the criteria.
PageSize	integer	The number of items per page.
Items[].Id	string	Unique identifier of the location.
Items[].Name	string	Location (company site) name.
Items[].CompanyNumber	string	Company number for this location. This is also provided when uploading files for that company.
Items[].Type	string	Location type (e.g., Terminal, Shipper/Consignee, Cold Warehouse, Dry Warehouse).
Items[].Status	string	Location status. Supported values: `"Active"`, `"Disabled"`, `"Inactive"`.
Items[].PhysicalAddress.Street	string	The street line of the location’s physical address.
Items[].PhysicalAddress.City	string	The city of the location.
Items[].PhysicalAddress.State	string	The state or province of the location.
Items[].PhysicalAddress.ZipCode	string	The postal/ZIP code of the location.
Items[].Email[]	array of string	A list of email addresses for the location.
Items[].Phone[]	array of string	A list of phone numbers for the location.
Items[].Fax	string	The fax number for the location.
Items[].DateCreated	string (datetime)	Timestamp when the location was created (UTC).
Items[].ExternalId	string	An external reference identifier, if applicable.
Items[].Notes[]	array of objects	A list of notes attached to the location.
Items[].Notes[].id	string	Unique identifier of the note.
Items[].Notes[].Description	string	The text of the note.
Items[].Notes[].NoteType	string	The type/category of the note.
Items[].Notes[].Time	string (datetime)	The timestamp when the note was created (UTC).
Items[].Notes[].User	string	The user who created the note.

Rate Limit

All endpoints are subject to platform rate limits. See Rate Limits.

Authorizations

Authorization

string

header

required

OAuth 2.0 client-credentials access token. Obtain one from https://auth.alvys.com/oauth/token (grant_type=client_credentials, audience=https://api.alvys.com/public/), then paste it here. The playground sends it as Authorization: Bearer <token>.

Path Parameters

version

string

default:1.0

required

API version (e.g., 1.0)

Example:

"1.0"

Body

Page

integer<int32>

required

PageSize

integer<int32>

required

Status

string[]

required

LocationIds

string[]

required

CreatedDateRange

object | null

Show child attributes

Response

Page

integer<int32>

required

PageSize

integer<int32>

required

Total

integer<int64>

required

Items

object[]

required

Show child attributes

Facets

object | null

Show child attributes

⌘I

Search locations

curl --request POST \
  --url https://integrations.alvys.com/api/p/v{version}/locations/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json-patch+json' \
  --data '
{
  "Page": 123,
  "PageSize": 123,
  "Status": [
    "<string>"
  ],
  "LocationIds": [
    "<string>"
  ],
  "CreatedDateRange": {
    "Start": "2023-11-07T05:31:56Z",
    "End": "2023-11-07T05:31:56Z"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json-patch+json'},
  body: JSON.stringify({
    Page: 123,
    PageSize: 123,
    Status: ['<string>'],
    LocationIds: ['<string>'],
    CreatedDateRange: {Start: '2023-11-07T05:31:56Z', End: '2023-11-07T05:31:56Z'}
  })
};

fetch('https://integrations.alvys.com/api/p/v{version}/locations/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://integrations.alvys.com/api/p/v{version}/locations/search"

payload = {
    "Page": 123,
    "PageSize": 123,
    "Status": ["<string>"],
    "LocationIds": ["<string>"],
    "CreatedDateRange": {
        "Start": "2023-11-07T05:31:56Z",
        "End": "2023-11-07T05:31:56Z"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json-patch+json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://integrations.alvys.com/api/p/v{version}/locations/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'Page' => 123,
    'PageSize' => 123,
    'Status' => [
        '<string>'
    ],
    'LocationIds' => [
        '<string>'
    ],
    'CreatedDateRange' => [
        'Start' => '2023-11-07T05:31:56Z',
        'End' => '2023-11-07T05:31:56Z'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json-patch+json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://integrations.alvys.com/api/p/v{version}/locations/search"

	payload := strings.NewReader("{\n  \"Page\": 123,\n  \"PageSize\": 123,\n  \"Status\": [\n    \"<string>\"\n  ],\n  \"LocationIds\": [\n    \"<string>\"\n  ],\n  \"CreatedDateRange\": {\n    \"Start\": \"2023-11-07T05:31:56Z\",\n    \"End\": \"2023-11-07T05:31:56Z\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json-patch+json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://integrations.alvys.com/api/p/v{version}/locations/search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json-patch+json")
  .body("{\n  \"Page\": 123,\n  \"PageSize\": 123,\n  \"Status\": [\n    \"<string>\"\n  ],\n  \"LocationIds\": [\n    \"<string>\"\n  ],\n  \"CreatedDateRange\": {\n    \"Start\": \"2023-11-07T05:31:56Z\",\n    \"End\": \"2023-11-07T05:31:56Z\"\n  }\n}")
  .asString();

{
  "Page": 123,
  "PageSize": 123,
  "Total": 123,
  "Items": [
    {
      "Id": "<string>",
      "Name": "<string>",
      "CompanyNumber": "<string>",
      "Type": "<string>",
      "Status": "<string>",
      "Email": [
        "<string>"
      ],
      "Phone": [
        "<string>"
      ],
      "Notes": [
        {
          "id": "<string>",
          "Description": "<string>",
          "NoteType": "<string>",
          "User": "<string>",
          "Time": "2023-11-07T05:31:56Z",
          "UserId": "<string>"
        }
      ],
      "PhysicalAddress": {
        "Street": "<string>",
        "City": "<string>",
        "State": "<string>",
        "ZipCode": "<string>"
      },
      "Fax": "<string>",
      "DateCreated": "2023-11-07T05:31:56Z",
      "ExternalId": "<string>"
    }
  ],
  "Facets": {}
}

{
  "Errors": {},
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

{
  "Type": "<string>",
  "Title": "<string>",
  "Status": 123,
  "Detail": "<string>",
  "Instance": "<string>"
}

​Request Parameters

​Example cURL request

​Response Parameters

​Rate Limit

Authorizations

Path Parameters

Body

Response

Request Parameters

Example cURL request

Response Parameters

Rate Limit