# Branches

# Introduction

In branch management, you can create, edit, fetch, or delete branches.

# Create Branch

To create a branch, you will need to make an HTTP POST request to the following endpoint:

POST
https://api.armadadelivery.com/v1/branches

Required Permission: branch:write

The body of the request should be in JSON format and include the following parameters:

name: Branch name, Between 2 and 75 characters String - Required
phone: Branch phone number String - Required
latitude: Latitude coordinate Number - Required
longitude: Longitude coordinate Number - Required

Armada will automatically generate a human-readable address from the provided geo-location coordinates.

# Request Example

Remember to include your Armada-Access-Token in the request headers. If you don't have one, please refer to the Authentication page to learn how to obtain it.

curl --location --request POST 'https://api.armadadelivery.com/v1/branches' \
--header 'Armada-Access-Token: [YOUR ACCESS TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "Fostoq",
  "phone": "+96533301234",
  "latitude": 29.3759,
  "longitude": 47.9774
}'

# Response Schema

{
  "id": "String", // Unique branch identifier
  "name": "String", // Branch name
  "phone": "String", // Branch phone number
  "latitude": Number, // Latitude coordinate
  "longitude": Number, // Longitude coordinate
  "address": "String", // Human-readable address generated by Armada from geo coordinates
  "created_at": "ISO Date" // Branch creation timestamp
}

# Response Example

{
  "id": "695c59ec793232655992c089",
  "name": "Fostoq",
  "phone": "+96533301234",
  "latitude": 29.3759,
  "longitude": 47.9774,
  "address": "Qibla, 8, Mubarak Al-Kabeer St",
  "created_at": "2026-01-06T00:40:12.531Z"
}

# Get Branch

To get one branch, you will need to make an HTTP GET request to the following endpoint:

GET
https://api.armadadelivery.com/v1/branches/:id

Required Permission: branch:read

id: The branch ID String - Required

# Request Example

(e.g id = 695c59ec793232655992c089)

Remember to include your Armada-Access-Token in the request headers. If you don't have one, please refer to the Authentication page to learn how to obtain it.

curl --location --request GET 'https://api.armadadelivery.com/v1/branches/695c59ec793232655992c089' \
--header 'Armada-Access-Token: [YOUR ACCESS TOKEN]'

# Response Example

{
  "id": "695c59ec793232655992c089",
  "name": "Fostoq",
  "phone": "+96533301234",
  "latitude": 29.3759,
  "longitude": 47.9774,
  "address": "Qibla, 8, Mubarak Al-Kabeer St",
  "created_at": "2026-01-06T00:40:12.531Z"
}

# Get All Branches

To get all branches with pagination support 🎉, you will need to make an HTTP GET request to the following endpoint:

GET
https://api.armadadelivery.com/v1/branches

Required Permission: branch:read

# Query Parameters

All parameters are optional with default values:

page: Page number Number - Optional - Default: 1
limit: Number of branches per page Number - Optional - Default: 30
sort_by: Field to sort by String - Optional - Options: created_at, name - Default: created_at
sort_order: Sort order String - Optional - Options: asc, desc - Default: desc

# Request Examples

Remember to include your Armada-Access-Token in the request headers. If you don't have one, please refer to the Authentication page to learn how to obtain it.

curl --location --request GET 'https://api.armadadelivery.com/v1/branches' \
--header 'Armada-Access-Token: [YOUR ACCESS TOKEN]'

curl --location --request GET 'https://api.armadadelivery.com/v1/branches?page=1&limit=30&sort_by=created_at&sort_order=desc' \
--header 'Armada-Access-Token: [YOUR ACCESS TOKEN]'

# Response Schema

{
  "branches": Array, // Array of branch objects
  "page": Number, // Current page number
  "limit": Number, // Number of items per page
  "sort_by": String, // Field used for sorting
  "sort_order": String, // Sort order (asc/desc)
  "total_pages": Number, // Total number of pages available
  "total_count": Number // Total number of branches
}

# Response Example

{
  "branches": [
    {
      "id": "695c59ec793232655992c089",
      "name": "Fostoqa",
      "phone": "+77533301234",
      "latitude": 29.3759,
      "longitude": 47.9774,
      "address": "Qibla, 8, Mubarak Al-Kabeer St",
      "created_at": "2026-01-06T00:40:12.531Z"
    },
    {
      "id": "695c54f746775a4c4a354ea8",
      "name": "SPUOA",
      "phone": "+96522001234",
      "latitude": 29.3759,
      "longitude": 47.9774,
      "address": "Kibla, 8, Mubarak Al-Kabeer St",
      "created_at": "2026-01-06T00:19:03.691Z"
    },
    {
      "id": "695c547e46775a4c4a354e97",
      "name": "Kuwait Hub Center",
      "phone": "+96522001234",
      "latitude": 29.3759,
      "longitude": 47.9774,
      "address": "Qibla, 8, Mubarak Al-Kabeer St",
      "created_at": "2026-01-06T00:17:02.631Z"
    }
  ],
  "page": 1,
  "limit": 30,
  "sort_by": "created_at",
  "sort_order": "desc",
  "total_pages": 1,
  "total_count": 3
}

# Update Branch

To update a branch, you will need to make an HTTP PUT request to the following endpoint:

PUT
https://api.armadadelivery.com/v1/branches/:id

Required Permission: branch:update

id: The branch ID String - Required

The body of the request should be in JSON format and include one or more of the following parameters:

name: Branch name, Between 2 and 75 characters String - Optional
phone: Branch phone number String - Optional
latitude: Latitude coordinate Number - Optional
longitude: Longitude coordinate Number - Optional

When updating coordinates, Armada will automatically regenerate the human-readable address.

# Request Example

(e.g id = 695c59ec793232655992c089)

Remember to include your Armada-Access-Token in the request headers. If you don't have one, please refer to the Authentication page to learn how to obtain it.

curl --location --request PUT 'https://api.armadadelivery.com/v1/branches/695c59ec793232655992c089' \
--header 'Armada-Access-Token: [YOUR ACCESS TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "Fostoqa Updated"
}'

# Response Example

{
  "id": "695c59ec793232655992c089",
  "name": "Fostoqa Updated",
  "phone": "+96533301234",
  "latitude": 29.3759,
  "longitude": 47.9774,
  "address": "Qibla, 8, Mubarak Al-Kabeer St",
  "created_at": "2026-01-06T00:40:12.531Z"
}

# Delete Branch

To delete a branch, you will need to make an HTTP DELETE request to the following endpoint:

DELETE
https://api.armadadelivery.com/v1/branches/:id

Required Permission: branch:delete

id: The branch ID String - Required

# Request Example

(e.g id = 695c59ec793232655992c089)

Remember to include your Armada-Access-Token in the request headers. If you don't have one, please refer to the Authentication page to learn how to obtain it.

curl --location --request DELETE 'https://api.armadadelivery.com/v1/branches/695c59ec793232655992c089' \
--header 'Armada-Access-Token: [YOUR ACCESS TOKEN]'

# Response

If successful, you will receive a 200 status code with no response body.