When to use this endpoint

Use GET|POST /branches/{carrier}/{country_code} on the Queries API when you need a carrier’s service points (branches / drop-off and delivery locations) for a given country.

Typical uses:

• Let a shipper pick an origin or destination branch when the selected service requires drop-off or pick-up at a branch.
• Auto-select the nearest branch near an address (postal code, state, locality, and optionally street or coordinates).
• Populate branch pickers filtered by state and locality.

Call this before label creation when the chosen service requires a branch on origin and/or destination (for example when drop_off is 1 = origin, 2 = destination, or 3 = both). A missing branch_code can block label generation.

Base URLs (Queries API)

Authentication

Authorization: Bearer <ENVIA_TOKEN>

Create or copy your token in the matching sandbox or production account. See Authentication.

Path parameters

Important: response shape

HTTP 200 returns a JSON array of branch objects.

This endpoint does not wrap results in { "data": [...] }. Parse the body as an array:

const branches = await response.json(); // array

Do not assume a { success, data, message } envelope for successful lookups on this path.

Using branch_code

Each branch includes a branch_code. That value is the primary identifier to send when creating a label that requires a branch on origin and/or destination.

• Use branch_code from the selected branch (often the nearest: branches[0] when results are distance-sorted).
• On label / shipment payloads, send it on the corresponding address (commonly as branchCode / branch_code, depending on the shipping API field).
• branch_id and reference are useful for catalogs and UI labels; branch_code is what label generation expects.

Example (conceptual):

const nearest = branches[0];
const branchCode = nearest?.branch_code;
// Attach branchCode to the origin or destination address before creating the label

Search behavior

Filters may be sent as a query string (GET) or a JSON body (POST). Field names are the same.

Nearby ranking (50 km)

1. If latitude / longitude are present, or can be resolved from address fields (state, locality, zipcode, address), the API ranks active branches by Haversine distance and keeps those within 50 km, ordered nearest first. A distance field (km) is present on those rows.
2. If that yields no rows, it falls back to the same filters without distance ranking.
3. If still empty and zipcode has more than one character, it retries with a shorter postal prefix.
4. Final fallback: active branches for that carrier and country with location filters removed.

Capability filter (type)

Caching

• GET responses may be HTTP-cached up to 24 hours.
• POST is not cached the same way — prefer POST when filters or package rules must stay fresh.

There is no client-facing page cursor. Use limitBranches when you need to cap the number of rows.

Additional parameters

Common filters (zipcode, state, locality, address, latitude, longitude, type) work on both GET and POST. The following parameters are especially useful for UI pickers and rule-aware search.

packages item shape (POST)

POST vs GET

If packages and/or shipmentType are present, branches may be filtered by branch_rules. Malformed branch_rules JSON on a row is ignored for that branch (the branch is still returned).

Related endpoints

Branch catalog helper

To drive state / locality filter dropdowns:

GET /branches/{carrier}/{country_code}/catalog

Optional query parameters: zipcode, locality, state, type, carrierId.

Example response:

{
  "states": ["State A", "State B"],
  "localities": {
    "State A": ["City 1", "City 2"],
    "State B": ["City 3"]
  }
}

Typical flow:

1. Call the catalog to list states and localities.
2. Call GET|POST /branches/{carrier}/{country_code} with the selected filters (and optional packages).
3. Use the returned branch_code on the label.

Which branch API should I call?

Use this decision tree to pick the right Branches endpoint:

Need branches for label / picker?
│
├─ Carrier is Estafeta OXXO (MX retail network)?
│     └─ POST /branches/estafeta/oxxo
│
├─ Carrier action includes return_branches_by_address?
│     └─ POST {Shipping API}/ship/branchesbyaddress
│           (live carrier response — not the Queries catalog)
│
├─ Need only state / locality lists for dropdowns?
│     └─ GET /branches/{carrier}/{country_code}/catalog
│
├─ Need branches for one known carrier + country?
│     └─ GET|POST /branches/{carrier}/{country_code}   ← this page
│           (optional: packages / shipmentType / branchType / limitBranches)
│
└─ Need multi-carrier branches for a country?
      └─ GET /branches/{country_code}
            (token_user auth; different filter set)

Default for most integrations: GET|POST /branches/{carrier}/{country_code} plus the catalog helper when building filter UIs.

Examples

Replace {carrier} and {country_code} with values from GET /carrier?country_code={country_code} (use the carrier name slug).

GET — nearby branches by postal code

curl --request GET \
  --url "https://queries.test.envia.com/branches/{carrier}/{country_code}?zipcode=00000&state=State%20Name&locality=City%20Name&type=1&limitBranches=10" \
  --header "Authorization: Bearer $ENVIA_TOKEN"

POST — filter with packages and shipment type

curl --request POST \
  --url "https://queries.test.envia.com/branches/{carrier}/{country_code}" \
  --header "Authorization: Bearer $ENVIA_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "type": 1,
    "state": "State Name",
    "locality": "City Name",
    "zipcode": "00000",
    "shipmentType": 1,
    "packages": [
      {
        "weight": 2,
        "length": 30,
        "height": 20,
        "width": 15,
        "amount": 1
      }
    ]
  }'

JavaScript (fetch)

const carrier = "your-carrier-slug"; // from GET /carrier?country_code=XX
const countryCode = "XX";

const response = await fetch(
  `https://queries.test.envia.com/branches/${carrier}/${countryCode}`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.ENVIA_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: 1,
      state: "State Name",
      locality: "City Name",
      zipcode: "00000",
    }),
  }
);

const branches = await response.json(); // raw array — not { data }
const nearest = branches[0];
const branchCode = nearest?.branch_code;

When distance ranking succeeds, take branches[0] as the nearest branch within 50 km and use its branch_code on the label.