> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alvys.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search locations

> Search saved shipper and consignee locations with paginated POST filters — name, city, state, zip, hours of operation, and appointment requirements.

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](/en/api/guides/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. Allowed values (case-sensitive): `"Active"`, `"Inactive"`, `"Disabled"`, `"On Hold"`, `"Do Not Use"`. Filtering by `"Inactive"` also returns locations whose stored status is `"On Hold"` or `"Do Not Use"`. Rows filtered by `"On Hold"` or `"Do Not Use"` still return `"Inactive"` in `Items[].Status`. |
| 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

```bash theme={null}
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", "On Hold", "Do Not Use"],
  "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. |
| Items\[].References\[] | array of objects | An optional list of custom references associated with the location. Only values whose reference definition includes the Public API surface are returned. |

### Rate Limit

All endpoints are subject to platform rate limits. See [Rate Limits](/en/api/guides/rate-limits).


## OpenAPI

````yaml POST /api/p/v{version}/locations/search
openapi: 3.0.1
info:
  title: Alvys
  description: >-
    Alvys provides a robust set of REST APIs to allow you to integrate Alvys
    into virtually any platform. These APIs cover most of Alvys' major product
    areas with additional endpoints being added regularly based on customer
    requests.
  contact:
    name: Alvys Support
    url: https://www.alvys.com/resources/contact/
  version: v1
servers:
  - url: https://integrations.alvys.com
    description: Public API Server
  - url: https://api.alvys.com/
    description: Public API Server
security:
  - Public: []
tags:
  - name: Authentication
    description: Obtain an OAuth 2.0 access token for the Alvys Public API.
  - name: Carrier Settlement Statements
    description: >-
      Search carrier settlement statements and retrieve a single statement by
      number.
  - name: Carriers
    description: Read carrier records, search carriers, and manage carrier documents.
  - name: Customers
    description: Create, read, update, delete, and search customer records.
  - name: Deductions
    description: >-
      Create one-time deductions and search or delete existing deduction
      records.
  - name: DispatchPreferences
    description: Dispatch preferences endpoints for reading dispatch rules and preferences.
  - name: Driver Settlement Statements
    description: >-
      Search driver settlement statements and retrieve a single statement by
      number.
  - name: Drivers
    description: >-
      Read driver records, search drivers and driver events, and manage driver
      documents.
  - name: Fuel
    description: Read and search fuel transactions.
  - name: Invoices
    description: >-
      Read invoices, create carrier invoices, and record carrier and customer
      payments.
  - name: Loads
    description: >-
      Read, update, and search loads; manage load documents, notes, and custom
      references.
  - name: Locations
    description: Read and search company location details.
  - name: Maintenance
    description: Read and search maintenance records.
  - name: References
    description: >-
      List tenant custom reference definitions and create or update values on
      existing loads, stops, and trips.
  - name: Subsidiaries
    description: >-
      List your company's subsidiaries and read a single subsidiary, so an
      integration can resolve a subsidiary id to a recognizable name.
  - name: Tenders
    description: Create, accept, reject, cancel, update, and search inbound EDI tenders.
  - name: Tolls
    description: Read and search toll transactions.
  - name: Tracking
    description: >-
      Record an asset's current location or telemetry from a third-party source,
      such as an external ELD or a self-reporting vehicle.
  - name: Trailers
    description: Read trailers, search trailer events, and manage trailer documents.
  - name: Trips
    description: >-
      Read and search trips; manage trip documents, stop appointments, arrivals,
      departures, and stop and trip custom references.
  - name: Trucks
    description: Read trucks, search truck events, and manage truck documents.
  - name: Users
    description: List and search users.
  - name: Visibility
    description: >-
      Read inbound and outbound visibility history and search outbound
      visibility errors.
  - name: Webhooks
    description: >-
      Create, read, update, delete, enable, disable, verify, test, and rotate
      secrets for webhook subscriptions; read event types, delivery logs, and
      health metrics.
  - name: Accessorials
  - name: Credits
paths:
  /api/p/v{version}/locations/search:
    post:
      tags:
        - Locations
      summary: Search locations
      parameters:
        - name: version
          in: path
          description: API version (e.g., 1.0)
          required: true
          schema:
            type: string
            default: '1.0'
            example: '1.0'
      requestBody:
        content:
          application/json-patch+json:
            schema:
              allOf:
                - $ref: >-
                    #/components/schemas/Alvys.Models.Locations.LocationSearchRequest
          application/json:
            schema:
              allOf:
                - $ref: >-
                    #/components/schemas/Alvys.Models.Locations.LocationSearchRequest
          text/json:
            schema:
              allOf:
                - $ref: >-
                    #/components/schemas/Alvys.Models.Locations.LocationSearchRequest
          application/*+json:
            schema:
              allOf:
                - $ref: >-
                    #/components/schemas/Alvys.Models.Locations.LocationSearchRequest
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Alvys.Helpers.PagedResponse1Alvys.Models.Locations.LocationResponse
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Microsoft.AspNetCore.Mvc.ValidationProblemDetails
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
        '429':
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
      security:
        - Public: []
components:
  schemas:
    Alvys.Models.Locations.LocationSearchRequest:
      required:
        - LocationIds
        - Page
        - PageSize
        - Status
      type: object
      properties:
        Page:
          type: integer
          format: int32
        PageSize:
          type: integer
          format: int32
        Status:
          type: array
          items:
            type: string
        LocationIds:
          type: array
          items:
            type: string
        CreatedDateRange:
          allOf:
            - $ref: '#/components/schemas/Alvys.Models.Period'
          nullable: true
      additionalProperties: false
    Alvys.Helpers.PagedResponse1Alvys.Models.Locations.LocationResponse:
      required:
        - Items
        - Page
        - PageSize
        - Total
      type: object
      properties:
        Page:
          type: integer
          format: int32
        PageSize:
          type: integer
          format: int32
        Facets:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/Alvys.Helpers.ResultSetFacetItem'
          nullable: true
        Total:
          type: integer
          format: int64
        Items:
          type: array
          items:
            $ref: '#/components/schemas/Alvys.Models.Locations.LocationResponse'
      additionalProperties: false
    Microsoft.AspNetCore.Mvc.ValidationProblemDetails:
      required:
        - Errors
      type: object
      properties:
        Errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        Type:
          type: string
          nullable: true
        Title:
          type: string
          nullable: true
        Status:
          type: integer
          format: int32
          nullable: true
        Detail:
          type: string
          nullable: true
        Instance:
          type: string
          nullable: true
      additionalProperties: {}
    Microsoft.AspNetCore.Mvc.ProblemDetails:
      type: object
      properties:
        Type:
          type: string
          nullable: true
        Title:
          type: string
          nullable: true
        Status:
          type: integer
          format: int32
          nullable: true
        Detail:
          type: string
          nullable: true
        Instance:
          type: string
          nullable: true
      additionalProperties: {}
    Alvys.Models.Period:
      required:
        - Start
      type: object
      properties:
        Start:
          type: string
          format: date-time
        End:
          type: string
          format: date-time
          nullable: true
      additionalProperties: false
    Alvys.Helpers.ResultSetFacetItem:
      required:
        - Count
        - Value
      type: object
      properties:
        Value:
          type: string
        Count:
          type: integer
          format: int64
      additionalProperties: false
    Alvys.Models.Locations.LocationResponse:
      required:
        - CompanyNumber
        - Email
        - Id
        - Name
        - Notes
        - Phone
        - Status
        - Type
        - References
      type: object
      properties:
        Id:
          type: string
        Name:
          type: string
        CompanyNumber:
          type: string
        Type:
          type: string
        Status:
          type: string
        PhysicalAddress:
          allOf:
            - $ref: '#/components/schemas/Alvys.Features.Locations.ShortAddress'
          nullable: true
        Email:
          type: array
          items:
            type: string
        Phone:
          type: array
          items:
            type: string
        Fax:
          type: string
          nullable: true
        DateCreated:
          type: string
          format: date-time
          nullable: true
        ExternalId:
          type: string
          nullable: true
        Notes:
          type: array
          items:
            $ref: '#/components/schemas/Alvys.Models.Notes.NoteDto'
        References:
          type: array
          items:
            $ref: '#/components/schemas/Alvys.Models.References.ReferenceResponse'
      additionalProperties: false
    Alvys.Features.Locations.ShortAddress:
      required:
        - City
        - State
        - Street
        - ZipCode
      type: object
      properties:
        Street:
          type: string
        City:
          type: string
        State:
          type: string
        ZipCode:
          type: string
        Country:
          type: string
          description: >-
            ISO 3166-1 alpha-2 country code where the recorded value is a
            recognized spelling of United States, Canada or Mexico; otherwise
            the country exactly as recorded, which for addresses created before
            this field existed may be any string. Omitted when no country is
            recorded; an absent Country must NOT be interpreted as US.
          nullable: true
      additionalProperties: false
    Alvys.Models.Notes.NoteDto:
      required:
        - Description
        - id
        - NoteType
        - User
      type: object
      properties:
        id:
          type: string
        Description:
          type: string
        NoteType:
          type: string
        Time:
          type: string
          format: date-time
          nullable: true
        User:
          type: string
        UserId:
          type: string
          nullable: true
      additionalProperties: false
    Alvys.Models.References.ReferenceResponse:
      required:
        - Name
        - Value
      type: object
      properties:
        Id:
          type: string
          nullable: true
        ReferenceId:
          type: string
          nullable: true
        Name:
          type: string
        Value:
          type: string
        Type:
          type: string
          nullable: true
        Access:
          type: string
          nullable: true
        Origin:
          type: string
          nullable: true
      additionalProperties: false
  securitySchemes:
    Public:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        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>`.

````