> ## 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](/docs/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 ```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"], "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](/docs/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, search loads, and manage load documents and notes. - name: Locations description: Read and search company location details. - name: Maintenance description: Read and search maintenance records. - name: Tenders description: Create, accept, reject, cancel, update, and search inbound EDI tenders. - name: Tolls description: Read and search toll transactions. - name: Trailers description: Read trailers, search trailer events, and manage trailer documents. - name: Trips description: >- Read, search trips, manage trip documents, and record stop appointments, arrivals, and departures. - 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. 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' '404': description: Not Found content: application/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 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' 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 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 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 `. ````