---
title: "Get Branches (POST)"
method: POST
path: "/branches/{carrier}/{country_code}"
tags: ["Branches"]
---

# Get Branches (POST)

`POST /branches/{carrier}/{country_code}`

## Request

- Base URL: `https://queries.test.envia.com`
- URL: `https://queries.test.envia.com/branches/{carrier}/{country_code}`
- Auth: HTTP bearer

Same endpoint as **Get Branches**, with a JSON body. Use it to filter by `packages`, or for **live carrier lookup**: send `carrierId` for a carrier that has the `return_branches_by_address` action and Envia asks the carrier for points near the address instead of reading the branch catalog. See the *Live carrier lookup* section of the Get Branches guide.

## Path parameters

- `carrier` string, required
- `country_code` string, required

## Request body

- object
  - `carrierId` integer: Carrier id from `GET /carrier` (`id`). Switches on **live lookup** when that carrier has the `return_branches_by_address` action (check it with `GET /carrier-action/{carrier_id}`). Without it, or on carriers without that action, the catalog search runs.
  - `zipcode` string: Postal code. **Required for live lookup.**
  - `address` string: Street address. **Required for live lookup.**
  - `locality` string: Locality or city. **Required for live lookup.**
  - `serviceName` string: Carrier service name. **Required for live lookup.**
  - `type` 1 | 2 | 3: Capability: 1 origin (admission), 2 destination (delivery), 3 both. **Required for live lookup.** On the catalog search it defaults to `1`.
  - `shipmentType` integer: Shipment type, `0` to `9`. **Required for live lookup.**
  - `packages` object[]: Packages to evaluate. **Required for live lookup** (at least one item).
    - `weight` number, required
    - `length` number, required
    - `height` number, required
    - `width` number, required
    - `amount` number
    - `package_type` number
  - `state` string: State filter. Optional.
  - `latitude` number, float: Latitude. Optional; some carriers require coordinates.
  - `longitude` number, float: Longitude. Optional; some carriers require coordinates.
  - `branchType` string: Catalog search only. Comma-separated branch categories: `1` Post Office, `2` Warehouse, `3` Third Party, `4` Lockers.
  - `limitBranches` number: Maximum number of branches returned (catalog search).
  - `allBranch` boolean: Catalog search only. Ignored by live lookup.

## Response `200`

Successful response. A JSON array of branches (not wrapped in `data`). `[]` when nothing matches.

- object[]
  - `branch_id` string
  - `branch_code` string
  - `branch_type` integer
  - `reference` string
  - `address` object
    - `city` string
    - `state` string
    - `number` string
    - `street` string
    - `country` string
    - `delivery` boolean
    - `latitude` string
    - `locality` string
    - `admission` boolean
    - `longitude` string
    - `postalCode` string
    - `address` string

## Other responses

- `400`: Live lookup: a required field is missing (`This carrier requires: zipcode, address, ...`) or the carrier rejected the request (its message is returned).

---

[API](https://skmtc.dev/envia/apis/envia-queries-api.md) - [All operations](https://skmtc.dev/envia/apis/envia-queries-api/llms.txt) - [OpenAPI document](https://skmtc.dev/envia/apis/envia-queries-api/revisions/56f601a52f3f?raw)