Introduction

Base URL: https://api.citycourier.org

This documentation aims to provide all the information you need to work with our API.

<aside>As you scroll, you'll see code examples for working with the API in different programming languages in the dark area to the right (or as part of the content on mobile).
You can switch the language used with the tabs at the top right (or from the nav menu at the top left on mobile).</aside>

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {YOUR_AUTH_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

You can retrieve your token by visiting your dashboard and clicking Generate API token.

Authentication

APIs for managing user authentication

Authenticate a user and return an access token.

Example request:

curl --request POST \
    "https://api.citycourier.org/api/v1/login" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"loginID\": \"user123\",
    \"email\": \"user@example.com\",
    \"password\": \"password123\"
}"

const url = new URL(
    "https://api.citycourier.org/api/v1/login"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "loginID": "user123",
    "email": "user@example.com",
    "password": "password123"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": {
        "user": {
            "id": 1,
            "loginID": "user123",
            "email": "user@example.com",
            "profile": {
                "name": "John Doe",
                "phone": "+1234567890"
            }
        },
        "token": "1|abcdefghijklmnopqrstuvwxyz"
    },
    "message": "Login successful"
}

Example response (422):


{
    "success": false,
    "message": "The provided credentials are incorrect."
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

POST api/v1/login

Headers

Content-Type

Example: application/json

Accept

Example: application/json

Body Parameters

loginID string

The user's login ID. Example: user123

email string optional

required_if:loginID,null The user's email address. Example: user@example.com

password string

The user's password. Example: password123

Get Authenticated User

requires authentication

Get the details of the currently authenticated user.

Example request:

curl --request GET \
    --get "https://api.citycourier.org/api/v1/me" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://api.citycourier.org/api/v1/me"
);

const headers = {
    "Authorization": "Bearer {YOUR_AUTH_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": {
        "user": {
            "id": 1,
            "loginID": "user123",
            "email": "user@example.com",
            "profile": {
                "name": "John Doe",
                "phone": "+1234567890"
            }
        }
    },
    "message": "User details retrieved successfully"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Cities and Branches

APIs for managing cities and their branches

Get all cities

Retrieve a list of all cities with their basic information.

Example request:

curl --request GET \
    --get "https://api.citycourier.org/api/v1/cities" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://api.citycourier.org/api/v1/cities"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "New York",
            "code": "NYC",
            "zone": "East"
        },
        {
            "id": 2,
            "name": "Los Angeles",
            "code": "LAX",
            "zone": "West"
        }
    ],
    "message": "Cities retrieved successfully"
}

Example response (500):


{
    "success": false,
    "message": "Internal server error"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Get branches by city

Retrieve all branches for a specific city with their details.

Example request:

curl --request GET \
    --get "https://api.citycourier.org/api/v1/cities/1/branches" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://api.citycourier.org/api/v1/cities/1/branches"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "Main Branch",
            "code": "NYC-MAIN",
            "type": "Main",
            "city_id": 1,
            "city": {
                "id": 1,
                "name": "New York",
                "code": "NYC",
                "zone": "East"
            }
        },
        {
            "id": 2,
            "name": "Downtown Branch",
            "code": "NYC-DOWN",
            "type": "Sub",
            "city_id": 1,
            "city": {
                "id": 1,
                "name": "New York",
                "code": "NYC",
                "zone": "East"
            }
        }
    ],
    "message": "Branches retrieved successfully"
}

Example response (404):


{
    "success": false,
    "message": "City not found"
}

Example response (500):


{
    "success": false,
    "message": "Internal server error"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Consignment Management

APIs for managing consignments

List all consignments

requires authentication

Example request:

curl --request GET \
    --get "https://api.citycourier.org/api/v1/consignments?from_date=2024-03-01&to_date=2024-03-20&status=booked" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://api.citycourier.org/api/v1/consignments"
);

const params = {
    "from_date": "2024-03-01",
    "to_date": "2024-03-20",
    "status": "booked",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer {token}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": [
        {
            "id": 1,
            "consignment_no": "NYC-LAX-123456",
            "status": {
                "id": 1,
                "name": "Booked"
            },
            "consigner": {
                "name": "John Doe",
                "phone": "+1234567890",
                "address": "123 Main St"
            },
            "consignee": {
                "name": "Jane Smith",
                "phone": "+1987654321",
                "address": "456 Oak St"
            },
            "branch": {
                "id": 1,
                "name": "Main Branch"
            },
            "created_at": "2024-03-20T10:00:00.000000Z"
        }
    ]
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

GET api/v1/consignments

Headers

Authorization

Example: Bearer {token}

Content-Type

Example: application/json

Accept

Example: application/json

Query Parameters

from_date string optional

Filter consignments created after this date. Example: 2024-03-01

to_date string optional

Filter consignments created before this date. Example: 2024-03-20

status string optional

Filter by consignment status (case-insensitive). Example: booked

Get consignment details

requires authentication

Example request:

curl --request GET \
    --get "https://api.citycourier.org/api/v1/consignments/NYC-LAX-123456" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://api.citycourier.org/api/v1/consignments/NYC-LAX-123456"
);

const headers = {
    "Authorization": "Bearer {token}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": {
        "id": 1,
        "consignment_no": "NYC-LAX-123456",
        "status": {
            "id": 1,
            "name": "Booked"
        },
        "consigner": {
            "name": "John Doe",
            "phone": "+1234567890",
            "address": "123 Main St",
            "cnic": "12345-6789012-3"
        },
        "consignee": {
            "name": "Jane Smith",
            "phone": "+1987654321",
            "address": "456 Oak St"
        },
        "branch": {
            "id": 1,
            "name": "Main Branch"
        },
        "trackings": [
            {
                "id": 1,
                "status": "Booked",
                "created_at": "2024-03-20T10:00:00.000000Z"
            }
        ],
        "originCity": {
            "id": 1,
            "name": "New York"
        },
        "destinationCity": {
            "id": 2,
            "name": "Los Angeles"
        }
    },
    "message": "Consignment retrieved successfully"
}

Example response (404):


{
    "success": false,
    "message": "Consignment not found"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

GET api/v1/consignments/{id}

Headers

Authorization

Example: Bearer {token}

Content-Type

Example: application/json

Accept

Example: application/json

URL Parameters

id string

The ID or consignment number of the consignment. Example: NYC-LAX-123456

Create new consignment

requires authentication

Example request:

curl --request POST \
    "https://api.citycourier.org/api/v1/consignments" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"origin\": 1,
    \"destination\": 2,
    \"service_type\": \"Express\",
    \"pieces\": \"2\",
    \"height\": \"10.5\",
    \"width\": \"15.2\",
    \"length\": \"20.0\",
    \"weight\": \"5.5\",
    \"consignerName\": \"John Doe\",
    \"consignerPhone\": \"+1234567890\",
    \"consignerAddress\": \"123 Main St\",
    \"consigneeName\": \"Jane Smith\",
    \"consigneePhone\": \"+1987654321\",
    \"consigneeAddress\": \"456 Oak St\\n\\nFor CLIENT users, additional fields:\",
    \"consignerPhone2\": \"+1234567891\",
    \"consignerCnic\": \"12345-6789012-3\",
    \"consigneePhone2\": \"+1987654322\",
    \"cod_type\": \"Prepaid\",
    \"orderId\": \"ORD123\",
    \"cod_amount\": \"1000\",
    \"declared_value\": \"5000\",
    \"special_instructions\": \"Handle with care\\n\\nFor non-CLIENT users, additional fields:\",
    \"goods_description\": \"Electronics\",
    \"price\": \"1000\",
    \"discount\": \"100\",
    \"total_price\": \"900\"
}"

const url = new URL(
    "https://api.citycourier.org/api/v1/consignments"
);

const headers = {
    "Authorization": "Bearer {token}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "origin": 1,
    "destination": 2,
    "service_type": "Express",
    "pieces": "2",
    "height": "10.5",
    "width": "15.2",
    "length": "20.0",
    "weight": "5.5",
    "consignerName": "John Doe",
    "consignerPhone": "+1234567890",
    "consignerAddress": "123 Main St",
    "consigneeName": "Jane Smith",
    "consigneePhone": "+1987654321",
    "consigneeAddress": "456 Oak St\n\nFor CLIENT users, additional fields:",
    "consignerPhone2": "+1234567891",
    "consignerCnic": "12345-6789012-3",
    "consigneePhone2": "+1987654322",
    "cod_type": "Prepaid",
    "orderId": "ORD123",
    "cod_amount": "1000",
    "declared_value": "5000",
    "special_instructions": "Handle with care\n\nFor non-CLIENT users, additional fields:",
    "goods_description": "Electronics",
    "price": "1000",
    "discount": "100",
    "total_price": "900"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (201):


{
    "success": true,
    "data": {
        "id": 1,
        "consignment_no": "NYC-LAX-123456",
        "status_id": 1,
        "volumetric_weight": 8.4,
        "chargeable_weight": 10.5
    },
    "message": "Consignment created successfully"
}

Example response (422):


{
    "success": false,
    "message": "Validation failed",
    "errors": {
        "origin": [
            "The origin field is required."
        ]
    }
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

POST api/v1/consignments

Headers

Authorization

Example: Bearer {token}

Content-Type

Example: application/json

Accept

Example: application/json

Body Parameters

origin integer

The ID of the origin city. Example: 1

destination integer

The ID of the destination city. Example: 2

service_type string

The type of service (Overnight/Express). Example: Express

pieces string

Number of pieces. Example: 2

height string

Height of the package. Example: 10.5

width string

Width of the package. Example: 15.2

length string

Length of the package. Example: 20.0

weight string

Weight of the package. Example: 5.5

consignerName string

Name of the consigner. Example: John Doe

consignerPhone string

Phone number of the consigner. Example: +1234567890

consignerAddress string

Address of the consigner. Example: 123 Main St

consigneeName string

Name of the consignee. Example: Jane Smith

consigneePhone string

Phone number of the consignee. Example: +1987654321

consigneeAddress string

Address of the consignee. Example: `456 Oak St

For CLIENT users, additional fields:`

consignerPhone2 string optional

optional Secondary phone number of the consigner. Example: +1234567891

consignerCnic string optional

required_if:user_type,not_client CNIC of the consigner. Example: 12345-6789012-3

consigneePhone2 string optional

optional Secondary phone number of the consignee. Example: +1987654322

cod_type string

Type of payment (Prepaid/COD). Example: Prepaid

orderId string

Order ID. Example: ORD123

cod_amount string optional

required_if:cod_type,COD COD amount. Example: 1000

declared_value string

Declared value of the package. Example: 5000

special_instructions string

Special instructions. Example: `Handle with care

For non-CLIENT users, additional fields:`

goods_description string

Description of goods. Example: Electronics

price string

Price of the consignment. Example: 1000

discount string

Discount amount. Example: 100

total_price string

Total price after discount. Example: 900

Update consignment

requires authentication

Example request:

curl --request PUT \
    "https://api.citycourier.org/api/v1/consignments/0" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"service_type\": \"Express\",
    \"origin\": 1,
    \"destination\": 2,
    \"pieces\": \"2\",
    \"height\": \"10.5\",
    \"width\": \"15.2\",
    \"length\": \"20.0\",
    \"weight\": \"5.5\",
    \"consignerName\": \"John Doe\",
    \"consignerPhone\": \"+1234567890\",
    \"consignerPhone2\": \"+1234567891\",
    \"consignerAddress\": \"123 Main St\",
    \"consignerCnic\": \"12345-6789012-3\",
    \"consigneeName\": \"Jane Smith\",
    \"consigneePhone\": \"+1987654321\",
    \"consigneePhone2\": \"+1987654322\",
    \"consigneeAddress\": \"456 Oak St\\n\\nFor CLIENT users, additional fields:\",
    \"cod_type\": \"Prepaid\",
    \"orderId\": \"ORD123\",
    \"cod_amount\": \"1000\",
    \"declared_value\": \"5000\",
    \"special_instructions\": \"Handle with care\\n\\nFor non-CLIENT users, additional fields:\",
    \"goods_description\": \"Electronics\",
    \"price\": \"1000\",
    \"discount\": \"100\",
    \"total_price\": \"900\"
}"

const url = new URL(
    "https://api.citycourier.org/api/v1/consignments/0"
);

const headers = {
    "Authorization": "Bearer {token}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "service_type": "Express",
    "origin": 1,
    "destination": 2,
    "pieces": "2",
    "height": "10.5",
    "width": "15.2",
    "length": "20.0",
    "weight": "5.5",
    "consignerName": "John Doe",
    "consignerPhone": "+1234567890",
    "consignerPhone2": "+1234567891",
    "consignerAddress": "123 Main St",
    "consignerCnic": "12345-6789012-3",
    "consigneeName": "Jane Smith",
    "consigneePhone": "+1987654321",
    "consigneePhone2": "+1987654322",
    "consigneeAddress": "456 Oak St\n\nFor CLIENT users, additional fields:",
    "cod_type": "Prepaid",
    "orderId": "ORD123",
    "cod_amount": "1000",
    "declared_value": "5000",
    "special_instructions": "Handle with care\n\nFor non-CLIENT users, additional fields:",
    "goods_description": "Electronics",
    "price": "1000",
    "discount": "100",
    "total_price": "900"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": {
        "id": 1,
        "consignment_no": "NYC-LAX-123456",
        "status_id": 1
    },
    "message": "Consignment updated successfully"
}

Example response (400):


{
    "success": false,
    "message": "Only consignments with Booked status can be updated"
}

Example response (404):


{
    "success": false,
    "message": "Consignment not found"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

PUT api/v1/consignments/{id}

Headers

Authorization

Example: Bearer {token}

Content-Type

Example: application/json

Accept

Example: application/json

URL Parameters

id integer

The ID or consignment number of the consignment to update. Example: 0

Body Parameters

service_type string

The type of service. Example: Express

origin integer

The ID of the origin city. Example: 1

destination integer

The ID of the destination city. Example: 2

pieces string

Number of pieces. Example: 2

height string

Height of the package. Example: 10.5

width string

Width of the package. Example: 15.2

length string

Length of the package. Example: 20.0

weight string

Weight of the package. Example: 5.5

consignerName string

Name of the consigner. Example: John Doe

consignerPhone string

Phone number of the consigner. Example: +1234567890

consignerPhone2 string optional

optional Secondary phone number of the consigner. Example: +1234567891

consignerAddress string

Address of the consigner. Example: 123 Main St

consignerCnic string optional

required_if:user_type,not_client CNIC of the consigner. Example: 12345-6789012-3

consigneeName string

Name of the consignee. Example: Jane Smith

consigneePhone string

Phone number of the consignee. Example: +1987654321

consigneePhone2 string optional

optional Secondary phone number of the consignee. Example: +1987654322

consigneeAddress string

Address of the consignee. Example: `456 Oak St

For CLIENT users, additional fields:`

cod_type string

Type of payment (Prepaid/COD). Example: Prepaid

orderId string

Order ID. Example: ORD123

cod_amount string optional

required_if:cod_type,COD COD amount. Example: 1000

declared_value string

Declared value of the package. Example: 5000

special_instructions string

Special instructions. Example: `Handle with care

For non-CLIENT users, additional fields:`

goods_description string

Description of goods. Example: Electronics

price string

Price of the consignment. Example: 1000

discount string

Discount amount. Example: 100

total_price string

Total price after discount. Example: 900

Delete consignment

requires authentication

Example request:

curl --request DELETE \
    "https://api.citycourier.org/api/v1/consignments/0" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://api.citycourier.org/api/v1/consignments/0"
);

const headers = {
    "Authorization": "Bearer {token}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "message": "Consignment deleted successfully"
}

Example response (400):


{
    "success": false,
    "message": "Only consignments with Booked status can be deleted"
}

Example response (404):


{
    "success": false,
    "message": "Consignment not found"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

DELETE api/v1/consignments/{id}

Headers

Authorization

Example: Bearer {token}

Content-Type

Example: application/json

Accept

Example: application/json

URL Parameters

id integer

The ID or consignment number of the consignment to delete. Example: 0

Get consignment tracking

requires authentication

Example request:

curl --request GET \
    --get "https://api.citycourier.org/api/v1/consignments/NYC-LAX-123456/tracking" \
    --header "Authorization: Bearer {token}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "https://api.citycourier.org/api/v1/consignments/NYC-LAX-123456/tracking"
);

const headers = {
    "Authorization": "Bearer {token}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "data": [
        {
            "id": 1,
            "consignment_id": 1,
            "status": "Booked",
            "created_at": "2024-03-20T10:00:00.000000Z",
            "updated_at": "2024-03-20T10:00:00.000000Z"
        }
    ],
    "message": "Consignment tracking retrieved successfully"
}

Example response (404):


{
    "success": false,
    "message": "Consignment not found"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

GET api/v1/consignments/{id}/tracking

Headers

Authorization

Example: Bearer {token}

Content-Type

Example: application/json

Accept

Example: application/json

URL Parameters

id string

The ID or consignment number of the consignment. Example: NYC-LAX-123456

Introduction

Authenticating requests

Authentication

User Login

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Body Parameters

Get Authenticated User

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Cities and Branches

Get all cities

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Get branches by city

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

URL Parameters

Consignment Management

List all consignments

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Query Parameters

Get consignment details

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

URL Parameters

Create new consignment

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Body Parameters

Update consignment

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

URL Parameters

Body Parameters

Delete consignment

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

URL Parameters

Get consignment tracking

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

URL Parameters

Request

Request

Request

Request

Request

Request

Request

Request

Request

Request