NAV
php javascript bash

Info

Welcome to the V3 Collivery.net API reference.

Please refer to the documentation of our older api Learn more

Headers

{
  "X-App-Name": "My Custom App", // Application Name
  "X-App-Version": "0.2.1", // Application Version
  "X-App-Host": ".NET Framework 4.8", // Framework/CMS name and version
  "X-App-Lang": "C#", // Language your implementation is written in
}

The following headers are required with each request, they help us to track the requests from each app in order to offer you help when you get stuck.

As a reminder you will see this tag with each example to indicate that you must include these in production. Requires headers

Please make these values your own, they will be rejected if they are all the default values suggested here. You can, however, use the default headers if you are logging in as api@collivery.co.za or demo@collivery.co.za.


Customise this page's example headers

1. Authentication

Please note:

Log in with your credentials and receive back your api token (to be used in further calls)

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->post("https://api.collivery.co.za/v3/login", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
        "Content-Type" => "application/json",
    ],
    'json' => [
        "email" => "demo@collivery.co.za",
        "password" => "demo",
     ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/login");

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Content-Type": "application/json",
    "Accept": "application/json",
}

let body = {"email":"demo@collivery.co.za","password":"demo"}
fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(body)
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X POST "https://api.collivery.co.za/v3/login" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#" \
    -H "Content-Type: application/json" \
    -d '{"email":"demo@collivery.co.za","password":"demo"}'

Example response (200):

{
    "data": {
        "id": 87,
        "email_address": "demo@collivery.co.za",
        "api_token": "OpSjx5TlXGCGkzGAvUOm",
        "full_name": "Collivery Demo"
    }
}

HTTP Request

POST v3/login

Body Parameters

Parameter Type Status Description
email string required Your email address.
password string required Your login password.

Register

Requires headers

Create a new client account

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->post("https://api.collivery.co.za/v3/register", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
        "Content-Type" => "application/json",
    ],
    'json' => [
        "name" => "John Doe",
        "terms" => "1",
        "email_address" => "foobar@example.com",
        "cellphone" => 123456789,
        "town_id" => "147",
        "suburb_id" => "1936",
        "street_name" => "Webber Street",
        "street_number" => "58c",
        "building" => "MDS House",
     ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/register");

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Content-Type": "application/json",
    "Accept": "application/json",
}

let body = {"name":"John Doe","terms":"1","email_address":"foobar@example.com","cellphone":123456789,"town_id":"147","suburb_id":"1936","street_name":"Webber Street","street_number":"58c","building":"MDS House"}
fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(body)
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X POST "https://api.collivery.co.za/v3/register" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#" \
    -H "Content-Type: application/json" \
    -d '{"name":"John Doe","terms":"1","email_address":"foobar@example.com","cellphone":123456789,"town_id":"147","suburb_id":"1936","street_name":"Webber Street","street_number":"58c","building":"MDS House"}'

Example response (200):

{
    "data": {
        "id": 54596,
        "full_name": "John Doe",
        "email_address": "foobar@example.com",
        "landline_number": "123456789",
        "mobile_number": "123456789",
        "api_token": "q4HuuQP67J6NabYoqov4",
        "client": {
            "id": 40203,
            "name": "John Doe",
            "landline_number": "123456789",
            "mobile_number": "123456789",
            "account_code": null,
            "account_type": "pre-paid",
            "primary_address": {
                "id": 2433244,
                "custom_id": null,
                "town": "Johannesburg",
                "town_id": 147,
                "suburb": "Selby",
                "suburb_id": 1936,
                "text": "John Doe, MDS House, 58c Webber Street, Selby, Johannesburg",
                "short_text": "John Doe, Selby, Johannesburg"
            }
        }
    }
}

Example response (412):

{
    "error": [
        [
            "That email address is already registered. Please rather login through http:\/\/api.collivery.local\/v3\/login"
        ]
    ]
}

Example response (422):

{
    "error": [
        [
            "That email address is already registered. Please rather login through https:\/\/api.collivery.co.za\/v3\/login"
        ]
    ]
}

HTTP Request

POST v3/register

Body Parameters

Parameter Type Status Description
name required optional string Your full name. Minimum 5 characters. Maximum 50 characters.
terms required optional boolean Whether you accept all terms an conditions. Should be fetched from our /terms endpoint.
email_address required optional string A valid email address that is not yet registered.
telephone number optional Your personal or business land-line number. One of telephone or cellphone must be provided.
cellphone number optional Your personal or business mobile number. One of telephone or cellphone must be provided.
town_id required optional number A valid town id, can be fetched from out /towns endpoint.
suburb_id required optional number A valid id of a suburb in the town provided, can be fetched from out /suburbs endpoint.
street_name required optional string The name of the street your primary address is on. Minimum 5 characters, maximum 50 characters.
street_number string optional The street number of your primary address. Maximum 5 characters.
building string optional The building name of your primary address. Maximum 50 characters.
company_name string optional The name of your business. Indicates that this is a business registration. Minimum 5 characters. Maximum 70 characters.
id_number number optional ID number of the person responsible for the payment of the account. Required if company_name is filled. Maximum 20 characters. If you are registering as a business and this is an invalid RSA id number your account will automatically be placed on hold, and we will contact you to get the correct details.
vat_number string optional Your company VAT number. Required if company_name is filled. Maximum 20 characters.
registration string optional Your company registration number. Required if company_name is filled. Maximum 20 characters.

2. Addresses

Manage Addresses

Index


Requires authenticationRequires headers

List your addresses

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get("https://api.collivery.co.za/v3/address", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
    ],
    'query' => [
        "per_page" => "3",
        "search" => "Johannes",
    ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/address");

let params = {
    "per_page": "3",
    "search": "Johannes",
};
Object.keys(params).forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Accept": "application/json",
    "Content-Type": "application/json",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET -G "https://api.collivery.co.za/v3/address?per_page=3&search=Johannes" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#"

Example response (200):

{
    "data": [
        {
            "id": 952,
            "custom_id": null,
            "town_id": 147,
            "suburb_id": 1936,
            "text": "MDS JHB, 58C Webber St, Selby, Johannesburg",
            "short_text": "MDS JHB, Selby, Johannesburg"
        },
        {
            "id": 2226089,
            "custom_id": "JAN0001",
            "town_id": 147,
            "suburb_id": 1936,
            "text": "Feyen, MDS House, 58c Webber St, Selby, Johannesburg",
            "short_text": "Feyen, Selby, Johannesburg"
        },
        {
            "id": 2226090,
            "custom_id": "JAN0001",
            "town_id": 147,
            "suburb_id": 1936,
            "text": "Feyen, MDS House, 58c Webber St, Selby, Johannesburg",
            "short_text": "Feyen, Selby, Johannesburg"
        }
    ],
    "links": {
        "first": "https:\/\/api.collivery.co.za\/v3\/address?page=1",
        "last": "https:\/\/api.collivery.co.za\/v3\/address?page=12",
        "prev": null,
        "next": "https:\/\/api.collivery.co.za\/v3\/address?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 12,
        "path": "https:\/\/api.collivery.co.za\/v3\/address",
        "per_page": "3",
        "to": 3,
        "total": 35
    }
}

HTTP Request

GET v3/address

Query Parameters

Parameter Status Description
per_page optional The limit per page. If this option is provided, 'links' and meta will exist in the; response with further information about the full list of addresses. 0 is the same as not limiting.
include optional A comma separated list of relationships to return. Available entries: contacts, suburb, town, active_waybills.
custom_id optional Search by this custom address id only.
search optional Search in street, building, company_name, suburb or town for a match.
town_id optional Limit to results with this town id.
suburb_id optional Limit to results with this suburb id.

Save


Requires authenticationRequires headers

Store a new Address.

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->post("https://api.collivery.co.za/v3/address", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
        "Content-Type" => "application/json",
    ],
    'json' => [
        "town_id" => 147,
        "town_name" => "Johannesburg",
        "suburb_id" => 1936,
        "suburb_name" => "Selby",
        "company_name" => "MDS Collivery",
        "building" => "MDS House",
        "street_number" => "58c",
        "street" => "Webber Street",
        "location_type" => 1,
        "location_type_name" => "Business Premises",
        "contact" => {"full_name":"John Doe","cellphone":"0723456789","email_address":"demo@collivery.co.za"},
     ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/address");

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Content-Type": "application/json",
    "Accept": "application/json",
}

let body = {"town_id":147,"town_name":"Johannesburg","suburb_id":1936,"suburb_name":"Selby","company_name":"MDS Collivery","building":"MDS House","street_number":"58c","street":"Webber Street","location_type":1,"location_type_name":"Business Premises","contact":{"full_name":"John Doe","cellphone":"0723456789","email_address":"demo@collivery.co.za"}}
fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(body)
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X POST "https://api.collivery.co.za/v3/address" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#" \
    -H "Content-Type: application/json" \
    -d '{"town_id":147,"town_name":"Johannesburg","suburb_id":1936,"suburb_name":"Selby","company_name":"MDS Collivery","building":"MDS House","street_number":"58c","street":"Webber Street","location_type":1,"location_type_name":"Business Premises","contact":{"full_name":"John Doe","cellphone":"0723456789","email_address":"demo@collivery.co.za"}}'

Example response (201):

{
    "data": {
        "id": 2693787,
        "custom_id": null,
        "town_id": 147,
        "suburb_id": 1936,
        "text": "MDS Collivery, MDS House, 58c Webber Street, Selby, Johannesburg",
        "short_text": "MDS Collivery, Selby, Johannesburg",
        "contacts": [
            {
                "id": 2816424,
                "full_name": "John Doe ",
                "cell_no": "0723456789",
                "work_no": "",
                "email": "demo@collivery.co.za"
            }
        ]
    }
}

HTTP Request

POST v3/address

Body Parameters

Parameter Type Status Description
custom_id string optional The custom id you would like to assign to this address. Must be unique. Max 20 characters.
town_id integer optional Required without town_name. Can be obtained from /towns/ endpoint.
town_name string optional Required without town_id. Can be obtained from /towns/ endpoint.
suburb_id integer optional Required without suburb_name. Can be obtained from /suburbs/ endpoint.
suburb_name string optional Required without suburb_id. Can be obtained from /suburbs/ endpoint.
company_name string optional The name of the company of the address. Max 50 characters.
building string optional The building of the address. Max 50 characters.
street_number string optional The number on the street of the address. Max 5 characters.
street string required The name of the street that the address is on. Max 50 characters.
location_type integer optional Required without location_type_name. The id of the location type for the address. Can be obtained from /location_types/ endpoint.
location_type_name string optional Required without location_type. The name of the location type for the address. Can be obtained from /location_types/ endpoint.
contact.full_name string optional optional If you are creating a contact with the address, their full name. Required if any of cellphone, work_phone or email_address is present in the contact object. Min 2 characters, max 50 characters.
contact.cellphone string optional optional If you are creating a contact with the address, their cellphone. Required if any of full_name or email_address is present in the contact object - and work_phone is not provided. Min 10 characters, max 20 characters.
contact.work_phone string optional optional If you are creating a contact with the address, their cellphone. Required if any of full_name or email_address is present in the contact object - and cellphone is not provided. Min 10 characters, max 20 characters.
contact.email_address string optional optional If you are creating a contact with the address, their full name. Useful for tracking updates to be sent to. Max 50 characters.
contact.id integer optional optional Only required for update requests. The id of the contact that you wish to update.

Show


Requires authenticationRequires headers

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get("https://api.collivery.co.za/v3/address/1363971", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
    ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/address/1363971");

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Accept": "application/json",
    "Content-Type": "application/json",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET -G "https://api.collivery.co.za/v3/address/1363971" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#"

Example response (200):

{
    "data": {
        "id": 1363971,
        "custom_id": null,
        "town_id": 419,
        "suburb_id": 4095,
        "text": "MDS Collivery, 123 Main Street, CBD, Louis Trichardt",
        "short_text": "MDS Collivery, CBD, Louis Trichardt",
        "contacts": [
            {
                "id": 592,
                "full_name": "Collivery Demo ",
                "cell_no": "011 241 4911",
                "work_no": "",
                "email": "demo@collivery.co.za"
            },
            {
                "id": 1413835,
                "full_name": "Some Person ",
                "cell_no": "0831245679",
                "work_no": "0123456789",
                "email": ""
            },
            {
                "id": 2650431,
                "full_name": "John Doe ",
                "cell_no": "0721828159",
                "work_no": null,
                "email": "foo@example.com"
            }
        ]
    }
}

HTTP Request

GET v3/address/{address}

Update


Requires authenticationRequires headers

Modify the details of a pre-existing address.

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->put("https://api.collivery.co.za/v3/address/1363971", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
        "Content-Type" => "application/json",
    ],
    'json' => [
        "town_id" => 147,
        "town_name" => "Johannesburg",
        "suburb_id" => 1936,
        "suburb_name" => "Selby",
        "company_name" => "MDS Collivery",
        "building" => "MDS House",
        "street_number" => "58c",
        "street" => "Webber Street",
        "location_type" => 1,
        "location_type_name" => "Business Premises",
        "contact" => {"full_name":"John Doe","cellphone":"0723456789","email_address":"demo@collivery.co.za"},
     ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/address/1363971");

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Content-Type": "application/json",
    "Accept": "application/json",
}

let body = {"town_id":147,"town_name":"Johannesburg","suburb_id":1936,"suburb_name":"Selby","company_name":"MDS Collivery","building":"MDS House","street_number":"58c","street":"Webber Street","location_type":1,"location_type_name":"Business Premises","contact":{"full_name":"John Doe","cellphone":"0723456789","email_address":"demo@collivery.co.za"}}
fetch(url, {
    method: "PUT",
    headers: headers,
    body: JSON.stringify(body)
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X PUT "https://api.collivery.co.za/v3/address/1363971" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#" \
    -H "Content-Type: application/json" \
    -d '{"town_id":147,"town_name":"Johannesburg","suburb_id":1936,"suburb_name":"Selby","company_name":"MDS Collivery","building":"MDS House","street_number":"58c","street":"Webber Street","location_type":1,"location_type_name":"Business Premises","contact":{"full_name":"John Doe","cellphone":"0723456789","email_address":"demo@collivery.co.za"}}'

Example response (200):

{
    "data": {
        "id": 2415979,
        "custom_id": "",
        "town": "Johannesburg",
        "town_id": 147,
        "suburb": "Selby",
        "suburb_id": 1936,
        "text": "MDS Collivery, MDS House, 58c Webber Street, Selby, Johannesburg",
        "short_text": "MDS Collivery, Selby, Johannesburg"
    }
}

Example response (400):

{
    "error": {
        "http_code_text": "Bad Request",
        "http_code": 400,
        "message": "There are waybills linked to that address, rather create a new one."
    }
}

HTTP Request

PUT v3/address/{address}

PATCH v3/address/{address}

Body Parameters

Parameter Type Status Description
custom_id string optional The custom id you would like to assign to this address. Must be unique. Max 20 characters.
town_id integer optional Required without town_name. Can be obtained from /towns/ endpoint.
town_name string optional Required without town_id. Can be obtained from /towns/ endpoint.
suburb_id integer optional Required without suburb_name. Can be obtained from /suburbs/ endpoint.
suburb_name string optional Required without suburb_id. Can be obtained from /suburbs/ endpoint.
company_name string optional The name of the company of the address. Max 50 characters.
building string optional The building of the address. Max 50 characters.
street_number string optional The number on the street of the address. Max 5 characters.
street string required The name of the street that the address is on. Max 50 characters.
location_type integer optional Required without location_type_name. The id of the location type for the address. Can be obtained from /location_types/ endpoint.
location_type_name string optional Required without location_type. The name of the location type for the address. Can be obtained from /location_types/ endpoint.
contact.full_name string optional optional If you are creating a contact with the address, their full name. Required if any of cellphone, work_phone or email_address is present in the contact object. Min 2 characters, max 50 characters.
contact.cellphone string optional optional If you are creating a contact with the address, their cellphone. Required if any of full_name or email_address is present in the contact object - and work_phone is not provided. Min 10 characters, max 20 characters.
contact.work_phone string optional optional If you are creating a contact with the address, their cellphone. Required if any of full_name or email_address is present in the contact object - and cellphone is not provided. Min 10 characters, max 20 characters.
contact.email_address string optional optional If you are creating a contact with the address, their full name. Useful for tracking updates to be sent to. Max 50 characters.
contact.id integer optional optional Only required for update requests. The id of the contact that you wish to update.

Delete


Requires authenticationRequires headers

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->delete("https://api.collivery.co.za/v3/address/1363971", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
    ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/address/1363971");

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Accept": "application/json",
    "Content-Type": "application/json",
}

fetch(url, {
    method: "DELETE",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X DELETE "https://api.collivery.co.za/v3/address/1363971" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#"

Example response (200):

{
    "success": {
        "http_code_text": 200,
        "http_code": 200,
        "message": {
            "message": "Address # 1363971 has been deleted"
        }
    }
}

Example response (400):

{
    "error": {
        "http_code_text": "Bad Request",
        "http_code": 400,
        "message": "Address # 1363971 is already used for waybills, you cannot delete it."
    }
}

HTTP Request

DELETE v3/address/{address}

Show


Requires authenticationRequires headers

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get("https://api.collivery.co.za/v3/default_address", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
    ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/default_address");

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Accept": "application/json",
    "Content-Type": "application/json",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET -G "https://api.collivery.co.za/v3/default_address" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#"

Example response (200):

{
    "data": {
        "id": 1363971,
        "custom_id": null,
        "town_id": 419,
        "suburb_id": 4095,
        "text": "MDS Collivery, 123 Main Street, CBD, Louis Trichardt",
        "short_text": "MDS Collivery, CBD, Louis Trichardt"
    }
}

HTTP Request

GET v3/default_address

3. Contacts

Manage Address Contacts

Index


Requires authenticationRequires headers

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get("https://api.collivery.co.za/v3/contacts", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
    ],
    'query' => [
        "per_page" => "3",
        "search" => "Collivery",
    ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/contacts");

let params = {
    "per_page": "3",
    "search": "Collivery",
};
Object.keys(params).forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Accept": "application/json",
    "Content-Type": "application/json",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET -G "https://api.collivery.co.za/v3/contacts?per_page=3&search=Collivery" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#"

Example response (200):

{
    "data": [
        {
            "id": 592,
            "full_name": "Collivery Demo ",
            "cell_no": "011 241 4911",
            "work_no": "",
            "email": "demo@collivery.co.za"
        },
        {
            "id": 596,
            "full_name": "DBN Collivery ",
            "cell_no": "079-891-3211",
            "work_no": "031-534-6500",
            "email": "dbn@collivery.co.za"
        }
    ],
    "links": {
        "first": "https:\/\/api.collivery.co.za\/v3\/contacts?page=1",
        "last": "https:\/\/api.collivery.co.za\/v3\/contacts?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https:\/\/api.collivery.co.za\/v3\/contacts",
        "per_page": "3",
        "to": 2,
        "total": 2
    }
}

HTTP Request

GET v3/contacts

Query Parameters

Parameter Status Description
per_page optional The limit per page. If this option is provided, links and meta will exist in the response with further information about the full list of addresses. 0 is the same as not limiting.
address_id optional Limit to contacts for this specific address.
search optional Search in name for a match.

Save


Requires authenticationRequires headers

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->post("https://api.collivery.co.za/v3/contacts", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
        "Content-Type" => "application/json",
    ],
    'json' => [
        "address_id" => 1363971,
        "email" => "foo@example.com",
        "full_name" => "John Doe",
        "cell_no" => "0721828159",
     ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/contacts");

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Content-Type": "application/json",
    "Accept": "application/json",
}

let body = {"address_id":1363971,"email":"foo@example.com","full_name":"John Doe","cell_no":"0721828159"}
fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(body)
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X POST "https://api.collivery.co.za/v3/contacts" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#" \
    -H "Content-Type: application/json" \
    -d '{"address_id":1363971,"email":"foo@example.com","full_name":"John Doe","cell_no":"0721828159"}'

Example response (201):

{
    "data": {
        "id": 2816425,
        "full_name": "John Doe ",
        "cell_no": "0721828159",
        "work_no": null,
        "email": "foo@example.com"
    }
}

HTTP Request

POST v3/contacts

Body Parameters

Parameter Type Status Description
address_id integer required The id of the address you wish to add this contact to. Can be fetched through the /addresses endpoint.
email string required Valid email address. Minimum 5 characters.
full_name string optional required. The contact's full name. Minimum 3 characters.
cell_no string optional Required without work_no. Minimum 10 characters.
work_no string optional Required without cell_no. Minimum 10 characters.

Show


Requires authenticationRequires headers

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get("https://api.collivery.co.za/v3/contacts/592", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
    ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/contacts/592");

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Accept": "application/json",
    "Content-Type": "application/json",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET -G "https://api.collivery.co.za/v3/contacts/592" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#"

Example response (200):

{
    "data": {
        "id": 592,
        "full_name": "Collivery Demo ",
        "cell_no": "011 241 4911",
        "work_no": "",
        "email": "demo@collivery.co.za"
    }
}

HTTP Request

GET v3/contacts/{contact}

Update


Requires authenticationRequires headers

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->put("https://api.collivery.co.za/v3/contacts/592", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
        "Content-Type" => "application/json",
    ],
    'json' => [
        "address_id" => 1363971,
        "email" => "foo@example.com",
        "full_name" => "John Doe",
        "cell_no" => "0721828159",
     ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/contacts/592");

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Content-Type": "application/json",
    "Accept": "application/json",
}

let body = {"address_id":1363971,"email":"foo@example.com","full_name":"John Doe","cell_no":"0721828159"}
fetch(url, {
    method: "PUT",
    headers: headers,
    body: JSON.stringify(body)
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X PUT "https://api.collivery.co.za/v3/contacts/592" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#" \
    -H "Content-Type: application/json" \
    -d '{"address_id":1363971,"email":"foo@example.com","full_name":"John Doe","cell_no":"0721828159"}'

Example response (200):

{
    "data": {
        "id": 592,
        "full_name": "John Doe ",
        "cell_no": "0721828159",
        "work_no": null,
        "email": "foo@example.com"
    }
}

HTTP Request

PUT v3/contacts/{contact}

PATCH v3/contacts/{contact}

Body Parameters

Parameter Type Status Description
address_id integer required The id of the address you wish to add this contact to. Can be fetched through the /addresses endpoint.
email string required Valid email address. Minimum 5 characters.
full_name string optional required. The contact's full name. Minimum 3 characters.
cell_no string optional Required without work_no. Minimum 10 characters.
work_no string optional Required without cell_no. Minimum 10 characters.

Delete


Requires authenticationRequires headers

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->delete("https://api.collivery.co.za/v3/contacts/592", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
    ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/contacts/592");

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Accept": "application/json",
    "Content-Type": "application/json",
}

fetch(url, {
    method: "DELETE",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X DELETE "https://api.collivery.co.za/v3/contacts/592" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#"

Example response (200):

{
    "success": {
        "http_code_text": 200,
        "http_code": 200,
        "message": {
            "message": "Contact # 592 has been deleted."
        }
    }
}

Example response (400):

{
    "error": {
        "http_code_text": "Bad Request",
        "http_code": 400,
        "message": "Contact # 592 is already used for waybills, you cannot delete it."
    }
}

HTTP Request

DELETE v3/contacts/{contact}

4. Get Quote

Request a quote


Requires authenticationRequires headers

Get a waybill quote based on the parameters provided.

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->post("https://api.collivery.co.za/v3/quote", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
        "Content-Type" => "application/json",
    ],
    'json' => [
        "services" => [1],
        "parcels" => [{"length":21.5,"width":10,"height":5.5,"weight":5.2,"quantity":2}],
        "collection_town" => 147,
        "delivery_town" => 200,
        "collection_location_type" => 1,
        "delivery_location_type" => 5,
        "collection_time" => "2025-01-24 12:00",
        "delivery_time" => "2025-01-25 16:00:00",
        "exclude_weekend" => true,
        "risk_cover" => true,
        "rica" => true,
        "consignee" => true,
        "sms_tracking" => true,
     ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/quote");

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Content-Type": "application/json",
    "Accept": "application/json",
}

let body = {"services":[1],"parcels":[{"length":21.5,"width":10,"height":5.5,"weight":5.2,"quantity":2}],"collection_town":147,"delivery_town":200,"collection_location_type":1,"delivery_location_type":5,"collection_time":"2025-01-24 12:00","delivery_time":"2025-01-25 16:00:00","exclude_weekend":true,"risk_cover":true,"rica":true,"consignee":true,"sms_tracking":true}
fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(body)
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X POST "https://api.collivery.co.za/v3/quote" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#" \
    -H "Content-Type: application/json" \
    -d '{"services":[1],"parcels":[{"length":21.5,"width":10,"height":5.5,"weight":5.2,"quantity":2}],"collection_town":147,"delivery_town":200,"collection_location_type":1,"delivery_location_type":5,"collection_time":"2025-01-24 12:00","delivery_time":"2025-01-25 16:00:00","exclude_weekend":true,"risk_cover":true,"rica":true,"consignee":true,"sms_tracking":true}'

Example response (200):

{
    "data": [
        {
            "service_type": 1,
            "total": 1999.8
        }
    ]
}

HTTP Request

POST v3/quote

Body Parameters

Parameter Type Status Description
services.* number optional A list of the services you would like a quote on. Any or none of 1,2,3,5. Defaults to all services.
parcels.* object optional Very important for determining accurate an quote. Will default to an "average" parcel if not supplied. Dimensions are limited to 1000, weight is limited to 400
parcels.*.length float optional The length of the parcel. Values in centimetres. Can be supplied as floats or integers.
parcels.*.width float optional The width of the parcel. Values in centimetres. Can be supplied as floats or integers.
parcels.*.height float optional The height of the parcel. Values in centimetres. Can be supplied as floats or integers.
parcels.*.weight float optional The weight of the parcel. Values in kilograms. Can be supplied as floats or integers.
parcels.*.quantity number optional The amount of parcels of this type.
collection_address number optional optional Required if collection_town is not supplied.
delivery_address number optional optional Required if delivery_town is not supplied.
collection_town number optional optional Required if collection_address is not supplied.
delivery_town number optional optional Required if delivery_address is not supplied.
collection_location_type number optional optional Must be a valid location type. Values can be gotten from our /location_type endpoint.
delivery_location_type number optional optional Must be a valid location type. Values can be gotten from our /location_type endpoint.
collection_time string required Any non-relative time representation that can be parsed by PHP strtotime(). Interpreted as GMT+2. If left empty no time surcharges will be encountered. Must be after current time.
delivery_time string optional Any non-relative time representation that can be parsed by PHP strtotime(). Interpreted as GMT+2. If left empty no time surcharges will be encountered. Must be after collection_time.
exclude_weekend boolean optional optional Whether to allow for weekend collection or delivery. Surcharges will be applied. Defaults to true.
risk_cover boolean optional optional Whether to enable risk cover over and above the default cover. See terms and conditions. Surcharges will be applied. Defaults to false.
rica boolean optional optional Whether this delivery requires RICA information and documentation to be supplied. Surcharges will be applied. Defaults to false. Example:
consignee boolean optional optional Whether this delivery can only be received by the person it is addressed to, with identity document required. Surcharges will be applied. Defaults to false. Example:
sms_tracking boolean optional optional Whether to send SMS updates to you, the collection and delivery contacts. Surcharges will be applied. Defaults to false. Example:

5. Waybills

Store


Requires authenticationRequires headers

Create a new waybill

Any time errors are returned in a "meta" array

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->post("https://api.collivery.co.za/v3/waybill", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
        "Content-Type" => "application/json",
    ],
    'json' => [
        "service" => 3,
        "parcels" => [{"length":21.5,"width":10,"height":5.5,"weight":5.2,"quantity":2}],
        "collection_address" => 952,
        "collection_contact" => 593,
        "delivery_address" => 955,
        "delivery_contact" => 596,
        "collection_time" => "2025-01-24",
        "delivery_time" => "2025-01-25",
        "exclude_weekend" => true,
        "risk_cover" => true,
        "battery_type" => "pi_965",
     ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/waybill");

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Content-Type": "application/json",
    "Accept": "application/json",
}

let body = {"service":3,"parcels":[{"length":21.5,"width":10,"height":5.5,"weight":5.2,"quantity":2}],"collection_address":952,"collection_contact":593,"delivery_address":955,"delivery_contact":596,"collection_time":"2025-01-24","delivery_time":"2025-01-25","exclude_weekend":true,"risk_cover":true,"battery_type":"pi_965"}
fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(body)
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X POST "https://api.collivery.co.za/v3/waybill" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#" \
    -H "Content-Type: application/json" \
    -d '{"service":3,"parcels":[{"length":21.5,"width":10,"height":5.5,"weight":5.2,"quantity":2}],"collection_address":952,"collection_contact":593,"delivery_address":955,"delivery_contact":596,"collection_time":"2025-01-24","delivery_time":"2025-01-25","exclude_weekend":true,"risk_cover":true,"battery_type":"pi_965"}'

Example response (201):

{
    "data": {
        "id": 4489466,
        "custom_id": "",
        "service_type_id": 3,
        "collection_time": 1737669600,
        "customer_reference": "",
        "delivery_time": 1738159200,
        "parcel_count": 2,
        "special_instructions": "pi_965 ",
        "collection_address_id": 952,
        "collection_contact_id": 593,
        "delivery_address_id": 955,
        "delivery_contact_id": 596,
        "status_id": 1,
        "parcel_description": "pi_965 ",
        "weight": 10.4,
        "volumetric_weight": 0.6,
        "total_price": 251
    },
    "meta": {
        "delivery_hours": [
            "Minimum hours from Johannesburg to Durban on the Road Freight service is 72, you requested the waybill be delivered within 24 hours. Weekends included. Deliver before time has adjusted."
        ],
        "lock-down": [
            "Due to limited flights and delays on road services between major centres there may be an additional delay in delivering your collivery."
        ],
        "delivery_time": [
            "Road Freight and Road Freight express only deliver at 16:00. Deliver before time has adjusted."
        ],
        "service_type": [
            "Road Freight service needs at least 3 working days between collection and delivery. Moving delivery date forward."
        ]
    }
}

HTTP Request

POST v3/waybill

Body Parameters

Parameter Type Status Description
service integer optional A service you would like to deliver the waybill on. Defaults to 2 (Overnight Express).
parcels.* object optional Very important for determining accurate an quote. Will default to an "average" parcel if not supplied. Dimensions are limited to 1000, weight is limited to 400
parcels.*.length float optional The length of the parcel. Values in centimetres. Can be supplied as floats or integers.
parcels.*.width float optional The width of the parcel. Values in centimetres. Can be supplied as floats or integers.
parcels.*.height float optional The height of the parcel. Values in centimetres. Can be supplied as floats or integers.
parcels.*.weight float optional The weight of the parcel. Values in kilograms. Can be supplied as floats or integers.
parcels.*.quantity number optional The amount of parcels of this type.
delivery_method integer optional The vehicle that we should collect it with. Defaults to 1 (Motorbike).
collection_address number required The id of the Collection Address.
collection_contact number required The id of the Collection Contact.
delivery_address number required The id of the Delivery Address.
delivery_contact number required The id of the Delivery Contact.
collection_time string required Any non-relative time representation that can be parsed by PHP strtotime(). Interpreted as GMT+2. If left empty no time surcharges will be encountered. Must be after current time.
delivery_time string optional Any non-relative time representation that can be parsed by PHP strtotime(). Interpreted as GMT+2. If left empty no time surcharges will be encountered. Must be after collection_time. Example:
exclude_weekend boolean optional optional Whether to allow for weekend collection or delivery. Surcharges will be applied. Defaults to true.
custom_id string optional A custom id for you to track the waybill by. Max 25 characters.
reference string optional Customer reference number. Max 100 characters.
description string optional A description of the package. Max 100 characters.
special_instructions string optional Any instructions on the handling, collection or delivery of your waybill. Max 2048 characters.
risk_cover boolean optional optional Whether to enable risk cover over and above the default cover. See terms and conditions. Surcharges will be applied. Defaults to false.
rica boolean optional optional Whether this delivery requires RICA information and documentation to be supplied. Surcharges will be applied. Defaults to false.
consignee boolean optional optional Whether this delivery can only be received by the person it is addressed to, with identity document required. Surcharges will be applied. Defaults to false.
sms_tracking boolean optional optional Whether to send SMS updates to you, the collection and delivery contacts. Surcharges will be applied. Defaults to false.
battery_type string optional optional Does the parcel contain any lithium ion batteries. The values for this can be gotten from our /battery_types endpoint. Defaults to false.

Show


Requires authenticationRequires headers

This will return a waybill's information, optionally along with addresses, contacts and documents as needed

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get("https://api.collivery.co.za/v3/waybill/4001907", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
    ],
    'query' => [
        "include" => "client,collection_address",
    ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/waybill/4001907");

let params = {
    "include": "client,collection_address",
};
Object.keys(params).forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Accept": "application/json",
    "Content-Type": "application/json",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET -G "https://api.collivery.co.za/v3/waybill/4001907?include=client,collection_address" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#"

Example response (200):

{
    "data": {
        "id": 4001907,
        "custom_id": "",
        "service_type_id": 2,
        "collection_time": 1559127600,
        "customer_reference": "",
        "delivery_time": 1559224800,
        "parcel_count": 1,
        "special_instructions": "",
        "collection_address_id": 647187,
        "collection_contact_id": 671846,
        "delivery_address_id": 660058,
        "delivery_contact_id": 684889,
        "status_id": 5,
        "parcel_description": "",
        "weight": 0.4,
        "volumetric_weight": 0.6,
        "total_price": 100,
        "client": {
            "id": 116,
            "name": "Test Collivery (Pty) Ltd",
            "landline_number": "011 241 4911",
            "mobile_number": null,
            "account_code": null,
            "account_type": "account"
        },
        "collection_address": {
            "id": 647187,
            "custom_id": null,
            "town_id": 147,
            "suburb_id": 1936,
            "text": "MDS Collivery, MDS House, 58c Webber St, Selby, Johannesburg",
            "short_text": "MDS Collivery, Selby, Johannesburg"
        }
    }
}

Example response (403):

{
    "error": {
        "http_code_text": "Forbidden",
        "http_code": 403,
        "message": "That waybill is not linked to your account."
    }
}

HTTP Request

GET v3/waybill/{waybill}

Query Parameters

Parameter Status Description
include optional A comma separated list of relationships to return. Available entries: client, collection_address, delivery_address, collection_contact, delivery_contact, documents.

6. Status Tracking

Fetch and query status updates for your waybills

Index


Requires authenticationRequires headers

Show a list of status tracking records

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get("https://api.collivery.co.za/v3/status_tracking", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
    ],
    'query' => [
        "statuses" => "1,3",
        "per_page" => "3",
    ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/status_tracking");

let params = {
    "statuses": "1,3",
    "per_page": "3",
};
Object.keys(params).forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Accept": "application/json",
    "Content-Type": "application/json",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET -G "https://api.collivery.co.za/v3/status_tracking?statuses=1,3&per_page=3" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#"

Example response (200):

{
    "data": [],
    "links": {
        "first": "https:\/\/api.collivery.co.za\/v3\/status_tracking?page=1",
        "last": "https:\/\/api.collivery.co.za\/v3\/status_tracking?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": null,
        "last_page": 1,
        "path": "https:\/\/api.collivery.co.za\/v3\/status_tracking",
        "per_page": "3",
        "to": null,
        "total": 0
    }
}

HTTP Request

GET v3/status_tracking

Query Parameters

Parameter Status Description
statuses optional optional A comma-separated list of statuses to limit the results to. Defaults to all statuses.
per_page optional optional The limit per page. If this option is provided, links and meta will exist in the response with further information about the full list of addresses.
start_date optional optional Any valid time representation that can be parsed by PHP strtotime(). Defaults to a week ago.
end_date optional optional.

Show


Requires authenticationRequires headers

Display all status tracking for a specific waybill

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get("https://api.collivery.co.za/v3/status_tracking/4001907", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
    ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/status_tracking/4001907");

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Accept": "application/json",
    "Content-Type": "application/json",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET -G "https://api.collivery.co.za/v3/status_tracking/4001907" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#"

Example response (200):

{
    "data": [
        {
            "status_id": 1,
            "status_name": "Waiting Client Acceptance",
            "waybill_id": 4001907,
            "created_at": "2019-05-29 12:13"
        },
        {
            "status_id": 3,
            "status_name": "Quote Accepted",
            "waybill_id": 4001907,
            "created_at": "2019-05-29 12:13"
        },
        {
            "status_id": 10,
            "status_name": "Collection Driver Dispatched",
            "waybill_id": 4001907,
            "created_at": "2019-05-29 12:14"
        },
        {
            "status_id": 5,
            "status_name": "Collivery Cancelled",
            "waybill_id": 4001907,
            "created_at": "2019-05-29 20:41"
        }
    ]
}

HTTP Request

GET v3/status_tracking/{waybill}

Update


Requires authenticationRequires headers

Accept or Cancel a waybill

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->put("https://api.collivery.co.za/v3/status_tracking/4001907", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
        "Content-Type" => "application/json",
    ],
    'json' => [
        "status_id" => 3,
     ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/status_tracking/4001907");

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Content-Type": "application/json",
    "Accept": "application/json",
}

let body = {"status_id":3}
fetch(url, {
    method: "PUT",
    headers: headers,
    body: JSON.stringify(body)
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X PUT "https://api.collivery.co.za/v3/status_tracking/4001907" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#" \
    -H "Content-Type: application/json" \
    -d '{"status_id":3}'

Example response (200):

{
    "data": {
        "message": "Waybill 4001907 has been accepted, Price remained at R100.00"
    }
}

Example response (400):

{
    "error": {
        "http_code_text": "Bad Request",
        "http_code": 400,
        "message": "Waybill # 4001907 has already started collection\/delivery process, cannot cancel."
    }
}

HTTP Request

PUT v3/status_tracking/{waybill}

PATCH v3/status_tracking/{waybill}

Body Parameters

Parameter Type Status Description
status_id number required The id of the status you want to update to. Must be 3 (Quote Accepted) or 5 (Cancelled).

7. Waybill Documents

Index


Requires authenticationRequires headers

List your waybill documents

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get("https://api.collivery.co.za/v3/waybill_documents", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
    ],
    'query' => [
        "per_page" => "3",
    ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/waybill_documents");

let params = {
    "per_page": "3",
};
Object.keys(params).forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Accept": "application/json",
    "Content-Type": "application/json",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET -G "https://api.collivery.co.za/v3/waybill_documents?per_page=3" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#"

Example response (200):

{
    "data": [
        {
            "id": 170452,
            "type": "POD",
            "file_name": "342118.pdf",
            "pages": 1,
            "mime": "application\/pdf",
            "size": 48971,
            "created_at": "2010-09-27 11:15:03",
            "image_url": "https:\/\/api.collivery.co.za\/v3\/waybill_documents\/170452"
        },
        {
            "id": 182535,
            "type": "POD",
            "file_name": "356551.pdf",
            "pages": 1,
            "mime": "application\/pdf",
            "size": 112152,
            "created_at": "2010-10-20 14:16:18",
            "image_url": "https:\/\/api.collivery.co.za\/v3\/waybill_documents\/182535"
        },
        {
            "id": 1836445,
            "type": "Master",
            "file_name": "MDS359074.pdf",
            "pages": 1,
            "mime": "application\/pdf",
            "size": 32381,
            "created_at": "2016-04-12 10:50:30",
            "image_url": "https:\/\/api.collivery.co.za\/v3\/waybill_documents\/1836445"
        }
    ],
    "links": {
        "first": "https:\/\/api.collivery.co.za\/v3\/waybill_documents?page=1",
        "last": "https:\/\/api.collivery.co.za\/v3\/waybill_documents?page=6",
        "prev": null,
        "next": "https:\/\/api.collivery.co.za\/v3\/waybill_documents?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 6,
        "path": "https:\/\/api.collivery.co.za\/v3\/waybill_documents",
        "per_page": "3",
        "to": 3,
        "total": 18
    }
}

HTTP Request

GET v3/waybill_documents

Query Parameters

Parameter Status Description
per_page optional The limit per page. If this option is provided, links and meta will exist in the response with further information about the full list of addresses. Defaults to 100.
waybill_id optional Limit to results with this waybill.

Show


Requires authenticationRequires headers

Get the details and base64 encoded image of the waybill document

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get("https://api.collivery.co.za/v3/waybill_documents/4001907", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
    ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/waybill_documents/4001907");

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Accept": "application/json",
    "Content-Type": "application/json",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET -G "https://api.collivery.co.za/v3/waybill_documents/4001907" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#"

Example response (200):

{
    "data": {
        "id": 4001907,
        "type": "",
        "file_name": "4001907.pdf",
        "pages": 1,
        "mime": "application\/pdf",
        "size": 2605,
        "created_at": "2019-05-29 18:41:11",
        "image_url": "https:\/\/api.collivery.co.za\/v3\/waybill_documents\/4001907",
        "image": "JVBERi0xLjMgCjEgMCBvYmoKPDwKL1BhZ2VzIDIgMCBSCi9UeXBlIC9DYXRhbG9nCj4+CmVuZG9iagoyIDAgb2JqCjw8Ci9UeXBlIC9QYWdlcwovS2lkcyBbIDMgMCBSIF0KL0NvdW50IDEKPj4KZW5kb2JqCjMgMCBvYmoKPDwKL1R5cGUgL1BhZ2UKL1BhcmVudCAyIDAgUgovUmVzb3VyY2VzIDw8Ci9YT2JqZWN0IDw8IC9JbTAgOCAwIFIgPj4KL1Byb2NTZXQgNiAwIFIgPj4KL01lZGlhQm94IFswIDAgMSAxXQovQ3JvcEJveCBbMCAwIDEgMV0KL0NvbnRlbnRzIDQgMCBSCi9UaHVtYiAxMSAwIFIKPj4KZW5kb2JqCjQgMCBvYmoKPDwKL0xlbmd0aCA1IDAgUgo+PgpzdHJlYW0KcQoxIDAgMCAxIDAgMCBjbQovSW0wIERvClEKCmVuZHN0cmVhbQplbmRvYmoKNSAwIG9iagoyNwplbmRvYmoKNiAwIG9iagpbIC9QREYgL1RleHQgL0ltYWdlQyBdCmVuZG9iago3IDAgb2JqCjw8Cj4+CmVuZG9iago4IDAgb2JqCjw8Ci9UeXBlIC9YT2JqZWN0Ci9TdWJ0eXBlIC9JbWFnZQovTmFtZSAvSW0wCi9GaWx0ZXIgWyAvRENURGVjb2RlIF0KL1dpZHRoIDEKL0hlaWdodCAxCi9Db2xvclNwYWNlIDEwIDAgUgovQml0c1BlckNvbXBvbmVudCA4Ci9MZW5ndGggOSAwIFIKPj4Kc3RyZWFtCv\/Y\/+AAEEpGSUYAAQEAAAEAAQAA\/9sAQwAMCAkKCQcMCgoKDQ0MDhIeExIQEBIkGhsVHismLSwqJikpLzVEOi8yQDMpKTtRPEBGSUxNTC45VFpTSllES0xJ\/8AACwgAAQABAQERAP\/EABQAAQAAAAAAAAAAAAAAAAAAAAf\/xAAUEAEAAAAAAAAAAAAAAAAAAAAA\/9oACAEBAAA\/AFV\/\/9kKZW5kc3RyZWFtCmVuZG9iago5IDAgb2JqCjE2MAplbmRvYmoKMTAgMCBvYmoKL0RldmljZUdyYXkKZW5kb2JqCjExIDAgb2JqCjw8Ci9GaWx0ZXIgWyAvRENURGVjb2RlIF0KL1dpZHRoIDEKL0hlaWdodCAxCi9Db2xvclNwYWNlIDEwIDAgUgovQml0c1BlckNvbXBvbmVudCA4Ci9MZW5ndGggMTIgMCBSCj4+CnN0cmVhbQr\/2P\/gABBKRklGAAEBAAABAAEAAP\/bAEMADAgJCgkHDAoKCg0NDA4SHhMSEBASJBobFR4rJi0sKiYpKS81RDovMkAzKSk7UTxARklMTUwuOVRaU0pZREtMSf\/AAAsIAAEAAQEBEQD\/xAAUAAEAAAAAAAAAAAAAAAAAAAAH\/8QAFBABAAAAAAAAAAAAAAAAAAAAAP\/aAAgBAQAAPwBVf\/\/ZCmVuZHN0cmVhbQplbmRvYmoKMTIgMCBvYmoKMTYwCmVuZG9iagoxMyAwIG9iago8PAo+PgplbmRvYmoKMTQgMCBvYmoKMTYwCmVuZG9iagoxNSAwIG9iago8PAo+PgplbmRvYmoKMTYgMCBvYmoKMTYwCmVuZG9iagoxNyAwIG9iago8PAovVGl0bGUgPEZFRkYwMDYxMDAwMD4KL0NyZWF0aW9uRGF0ZSAoRDoyMDE5MDkxMTA2MjMxMykKL01vZERhdGUgKEQ6MjAxOTA5MTEwNjIzMTMpCi9Qcm9kdWNlciAoaHR0cHM6Ly9pbWFnZW1hZ2ljay5vcmcpCj4+CmVuZG9iagp4cmVmCjAgMTgKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDEwIDAwMDAwIG4gCjAwMDAwMDAwNTkgMDAwMDAgbiAKMDAwMDAwMDExOCAwMDAwMCBuIAowMDAwMDAwMjkyIDAwMDAwIG4gCjAwMDAwMDAzNzIgMDAwMDAgbiAKMDAwMDAwMDM5MCAwMDAwMCBuIAowMDAwMDAwNDI4IDAwMDAwIG4gCjAwMDAwMDA0NDkgMDAwMDAgbiAKMDAwMDAwMDc4NSAwMDAwMCBuIAowMDAwMDAwODA0IDAwMDAwIG4gCjAwMDAwMDA4MzIgMDAwMDAgbiAKMDAwMDAwMTEyOCAwMDAwMCBuIAowMDAwMDAxMTQ4IDAwMDAwIG4gCjAwMDAwMDExNzAgMDAwMDAgbiAKMDAwMDAwMTE5MCAwMDAwMCBuIAowMDAwMDAxMjEyIDAwMDAwIG4gCjAwMDAwMDEyMzIgMDAwMDAgbiAKdHJhaWxlcgo8PAovU2l6ZSAxOAovSW5mbyAxNyAwIFIKL1Jvb3QgMSAwIFIKL0lEIFs8ZTAwZTVlYjk0NDQxODJmMzUyMzIzMzc0ZWY0ZTA4ZWJjYjc4NDcyNWZkZDRmZDYxMmQ3NzMwNTQwYjNlMGM4Yz4gPGUwMGU1ZWI5NDQ0MTgyZjM1MjMyMzM3NGVmNGUwOGViY2I3ODQ3MjVmZGQ0ZmQ2MTJkNzczMDU0MGIzZTBjOGM+XQo+PgpzdGFydHhyZWYKMTM3MwolJUVPRgo"
    }
}

Example response (404):

{
    "message": "Waybill Document for id 4001907 not found"
}

HTTP Request

GET v3/waybill_documents/{waybill_document}

8. Parcel Images

Index


Requires authenticationRequires headers

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get("https://api.collivery.co.za/v3/parcel_images", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
    ],
    'query' => [
        "per_page" => "3",
    ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/parcel_images");

let params = {
    "per_page": "3",
};
Object.keys(params).forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Accept": "application/json",
    "Content-Type": "application/json",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET -G "https://api.collivery.co.za/v3/parcel_images?per_page=3" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#"

Example response (200):

{
    "data": [],
    "links": {
        "first": "https:\/\/api.collivery.co.za\/v3\/parcel_images?page=1",
        "last": "https:\/\/api.collivery.co.za\/v3\/parcel_images?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": null,
        "last_page": 1,
        "path": "https:\/\/api.collivery.co.za\/v3\/parcel_images",
        "per_page": "3",
        "to": null,
        "total": 0
    }
}

HTTP Request

GET v3/parcel_images

Query Parameters

Parameter Status Description
per_page optional The limit per page. If this option is provided, links and meta will exist in the response with further information about the full list of addresses.
waybill_id optional A waybill id that you would like to limit the parcel images to.

Show


Requires authenticationRequires headers

Get the base64 encoded image

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get("https://api.collivery.co.za/v3/parcel_images/3041631", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
    ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/parcel_images/3041631");

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Accept": "application/json",
    "Content-Type": "application/json",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET -G "https://api.collivery.co.za/v3/parcel_images/3041631" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#"

Example response (200):

{
    "data": {
        "file_name": "3041631-1.jpeg",
        "mime_type": "image\/jpeg",
        "image": "\/9j\/4AAQSkZJRgABAQAAAQABAAD\/2wCEAAUFBQUFBQUGBgUICAcICAsKCQkKCxEMDQwNDBEaEBMQEBMQGhcbFhUWGxcpIBwcICkvJyUnLzkzMzlHREddXX0BBQUFBQUFBQYGBQgIBwgICwoJCQoLEQwNDA0MERoQExAQExAaFxsWFRYbFykgHBwgKS8nJScvOTMzOUdER11dff\/CABEIAAEAAQMBIgACEQEDEQH\/xAAUAAEAAAAAAAAAAAAAAAAAAAAI\/9oACAEBAAAAAGX\/AP\/EABQBAQAAAAAAAAAAAAAAAAAAAAD\/2gAIAQIQAAAAf\/\/EABQBAQAAAAAAAAAAAAAAAAAAAAD\/2gAIAQMQAAAAf\/\/EABQQAQAAAAAAAAAAAAAAAAAAAAD\/2gAIAQEAAT8Af\/\/EABQRAQAAAAAAAAAAAAAAAAAAAAD\/2gAIAQIBAT8Af\/\/EABQRAQAAAAAAAAAAAAAAAAAAAAD\/2gAIAQMBAT8Af\/\/Z"
    }
}

Example response (403):

{
    "error": {
        "http_code_text": "Forbidden",
        "http_code": 403,
        "message": "You are not allowed to access that parcel image."
    }
}

HTTP Request

GET v3/parcel_images/{parcel_image}

9. Towns

Show and search for Towns

Index


Requires authenticationRequires headers

Show all towns for a country or search towns.

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get("https://api.collivery.co.za/v3/towns", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
    ],
    'query' => [
        "per_page" => "3",
        "search" => "Joh",
        "country" => "ZAF",
    ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/towns");

let params = {
    "per_page": "3",
    "search": "Joh",
    "country": "ZAF",
};
Object.keys(params).forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Accept": "application/json",
    "Content-Type": "application/json",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET -G "https://api.collivery.co.za/v3/towns?per_page=3&search=Joh&country=ZAF" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#"

Example response (200):

{
    "data": [
        {
            "id": 147,
            "name": "Johannesburg",
            "latitude": "-26.204103",
            "longitude": "28.047305"
        },
        {
            "id": 777,
            "name": "Port St Johns",
            "latitude": "-31.628751",
            "longitude": "29.536871"
        }
    ],
    "links": {
        "first": "https:\/\/api.collivery.co.za\/v3\/towns?page=1",
        "last": "https:\/\/api.collivery.co.za\/v3\/towns?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https:\/\/api.collivery.co.za\/v3\/towns",
        "per_page": "3",
        "to": 2,
        "total": 2
    }
}

HTTP Request

GET v3/towns

Query Parameters

Parameter Status Description
per_page optional The limit per page. If this option is provided, links and meta will exist in the response with further information about the full list of addresses. 0 is the same as not limiting.
search optional Search by town name.
country optional The three letter abbreviation (ISO 3166) for the country. Defaults to ZAF.

10. Suburbs

Show and filter suburbs

Index


Requires authenticationRequires headers

Show all suburbs for a town or country or search suburbs.

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get("https://api.collivery.co.za/v3/suburbs", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
    ],
    'query' => [
        "per_page" => "3",
        "latitude" => "-26.212500",
        "longitude" => "28.037500",
        "town_id" => "147",
        "country" => "ZAF",
    ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/suburbs");

let params = {
    "per_page": "3",
    "latitude": "-26.212500",
    "longitude": "28.037500",
    "town_id": "147",
    "country": "ZAF",
};
Object.keys(params).forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Accept": "application/json",
    "Content-Type": "application/json",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET -G "https://api.collivery.co.za/v3/suburbs?per_page=3&latitude=-26.212500&longitude=28.037500&town_id=147&country=ZAF" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#"

Example response (200):

{
    "data": [
        {
            "id": 1936,
            "name": "Selby",
            "latitude": -26.2125,
            "longitude": 28.0375,
            "town": {
                "id": 147,
                "name": "Johannesburg",
                "latitude": "-26.204103",
                "longitude": "28.047305"
            }
        },
        {
            "id": 1458,
            "name": "New Centre",
            "latitude": -26.2125,
            "longitude": 28.045799,
            "town": {
                "id": 147,
                "name": "Johannesburg",
                "latitude": "-26.204103",
                "longitude": "28.047305"
            }
        },
        {
            "id": 339,
            "name": "City West",
            "latitude": -26.2125,
            "longitude": 28.0292,
            "town": {
                "id": 147,
                "name": "Johannesburg",
                "latitude": "-26.204103",
                "longitude": "28.047305"
            }
        }
    ],
    "links": {
        "first": "https:\/\/api.collivery.co.za\/v3\/suburbs?page=1",
        "last": null,
        "prev": null,
        "next": "https:\/\/api.collivery.co.za\/v3\/suburbs?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "path": "https:\/\/api.collivery.co.za\/v3\/suburbs",
        "per_page": "3",
        "to": 3
    }
}

HTTP Request

GET v3/suburbs

Query Parameters

Parameter Status Description
per_page optional The limit per page. If this option is provided, links and meta will exist in the response with further information about the full list of addresses. Defaults to 2000.
search optional Search by suburb name.
latitude optional A latitude to match a closest suburb against. Required if longitude is provided.
longitude optional A longitude to match a closest suburb against. Required if latitude is provided.
town_id optional Required without country. Can be obtained from /towns/ endpoint.
country optional Required without town_id. The three letter abbreviation (ISO 3166) for the country. Defaults to ZAF.

Show


Requires authenticationRequires headers

Show details of one particular suburb. Loaded with Town details included

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get("https://api.collivery.co.za/v3/suburbs/1936", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
    ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/suburbs/1936");

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Accept": "application/json",
    "Content-Type": "application/json",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET -G "https://api.collivery.co.za/v3/suburbs/1936" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#"

Example response (200):

{
    "data": {
        "id": 1936,
        "name": "Selby",
        "latitude": -26.2125,
        "longitude": 28.0375,
        "town": {
            "id": 147,
            "name": "Johannesburg",
            "latitude": "-26.204103",
            "longitude": "28.047305"
        }
    }
}

HTTP Request

GET v3/suburbs/{suburb}

11. Service Types

Show all service types or searched

Index

Requires headers

Get available service types with delivery days

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get("https://api.collivery.co.za/v3/service_types", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
    ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/service_types");

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Accept": "application/json",
    "Content-Type": "application/json",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET -G "https://api.collivery.co.za/v3/service_types" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#"

Example response (200):

{
    "data": [
        {
            "id": 1,
            "code": "SDX",
            "text": "Same Day",
            "description": "Will be delivered same day at times specified",
            "delivery_days": 0
        },
        {
            "id": 2,
            "code": "ONX",
            "text": "Next Day",
            "description": "Will be delivered next day at times specified",
            "delivery_days": 1
        },
        {
            "id": 5,
            "code": "ECO",
            "text": "Road Freight Express",
            "description": "Will be delivered within 2 working days",
            "delivery_days": 2
        },
        {
            "id": 3,
            "code": "FRT",
            "text": "Road Freight",
            "description": "For heavy cargo. Delivery within 3 working days",
            "delivery_days": 3
        }
    ]
}

HTTP Request

GET v3/service_types

Show


Requires authenticationRequires headers

Get specific service type by id

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get("https://api.collivery.co.za/v3/service_type/1", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
    ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/service_type/1");

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Accept": "application/json",
    "Content-Type": "application/json",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET -G "https://api.collivery.co.za/v3/service_type/1" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#"

Example response (200):

{
    "data": {
        "id": 1,
        "code": "SDX",
        "text": "Same Day",
        "description": "Will be delivered same day at times specified",
        "delivery_days": 0
    }
}

HTTP Request

GET v3/service_type/{id}

12. Location Types

Index


Requires authenticationRequires headers

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get("https://api.collivery.co.za/v3/location_types", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
    ],
    'query' => [
        "search" => "business",
    ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/location_types");

let params = {
    "search": "business",
};
Object.keys(params).forEach(key => url.searchParams.append(key, params[key]));

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Accept": "application/json",
    "Content-Type": "application/json",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET -G "https://api.collivery.co.za/v3/location_types?search=business" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#"

Example response (200):

{
    "data": [
        {
            "id": 1,
            "name": "Business Premises",
            "surcharge": false
        }
    ]
}

HTTP Request

GET v3/location_types

Query Parameters

Parameter Status Description
search optional An optional search string matched against the location types names.
surcharge_only optional {include, exclude} include will return only surchargeable location types, exclude will return only non-surchargeable location types.

13. Terms and Conditions

Index


Requires authenticationRequires headers

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get("https://api.collivery.co.za/v3/terms_and_conditions", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
    ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/terms_and_conditions");

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Accept": "application/json",
    "Content-Type": "application/json",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET -G "https://api.collivery.co.za/v3/terms_and_conditions" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#"

Example response (200):

{
    "data": {
        "Definitions": [
            {
                "key": 1,
                "value": "“MDS” shall mean MDS Collivery (Pty) Ltd, its staff, agents or sub-contractors."
            },
            {
                "key": 2,
                "value": "“Goods” shall mean any documents, parcels or freight accepted for carriage by MDS."
            },
            {
                "key": 3,
                "value": "“Carriage” shall mean the transport of goods from one point to another by MDS (the “Carrier”) using means it deems suitable."
            },
            {
                "key": 4,
                "value": "“Client” shall mean the party responsible for the payment for the carriage of the goods."
            },
            {
                "key": 5,
                "value": "“Owner” shall mean the party who has a financial interest in the goods."
            },
            {
                "key": 6,
                "value": "“Parties” shall mean the Client, the Owner, the sender, the receiver or the Carrier, as the context may require."
            },
            {
                "key": 7,
                "value": "“Waybill” is the accompanying document which identifies the Client, the number and weight of packages involved and instructions regarding the time and place of both the collection and delivery, copies of which are signed by the parties and serve as proof of handover of the goods from one party to the other."
            }
        ],
        "Terms and Conditions": [
            {
                "key": 1,
                "value": "MDS is not a public\/common carrier and may refuse to accept any goods for carriage without providing reason for such refusal."
            },
            {
                "key": 2,
                "value": "By using our collection and delivery service you agree to be bound by our terms and conditions, as set out in this document, and you acknowledge that our terms and conditions will constitute a valid, binding and enforceable agreement."
            },
            {
                "key": 3,
                "value": "These terms & conditions shall apply to all transactions concluded by or on the Client's behalf on our website. (www.collivery.co.za or collivery.net)."
            },
            {
                "key": 4,
                "value": "A certificate issued by an administrator of our website shall constitute prima facie proof of any fact related to our website, including (but not limited to) which version of the terms and conditions that govern a particular dispute and the content that was published or functionality was available on our website at a specific point in time."
            },
            {
                "key": 5,
                "value": "For purposes of Section 22(2) of the Electronic Communications and Transactions Act, 25 of 2002 you accept that the agreement will be regarded as concluded at Randburg, Gauteng Province."
            },
            {
                "key": 6,
                "value": "All matters arising from this agreement, its validity, existence or termination shall be determined in accordance with the laws of the time of the Republic of South Africa, and you hereby submit to the jurisdiction of the Magistrates' Court of Johannesburg\/Randburg."
            },
            {
                "key": 7,
                "value": "MDS' prices are set out in its price list or are as negotiated or quoted to the Client and are subject to review from time to time."
            },
            {
                "key": 8,
                "value": "Prices quoted are based on the information provided by the Client. Should this information be found to be incorrect, MDS has the right to adjust the prices based on the correct information while continuing with the carriage."
            },
            {
                "key": 9,
                "value": "Any credit limit, invoice frequency, or payment terms set by MDS shall be at its sole and absolute discretion and may be changed by MDS depending on circumstances that MDS believes justifies such changes."
            }
        ],
        "Liability": [
            {
                "key": "MDS' liability to the Client in respect of goods in its care:",
                "value": [
                    {
                        "key": 1,
                        "value": "Will terminate once proof of delivery has been obtained from the receiving party at the address stated on the waybill."
                    },
                    {
                        "key": 2,
                        "value": "Shall be limited to an amount of R1 000.00 (One Thousand Rand)."
                    },
                    {
                        "key": 3,
                        "value": "Shall exclude indirect and consequential damages."
                    },
                    {
                        "key": 4,
                        "value": "Where MDS has agreed to accept the additional risk of carriage, such risk shall not exceed an amount of R10 000.00 (Ten thousand Rand) relating to any one waybill. This risk relates to the loss of goods, and does not cover damage resulting from inadequate packaging of the items by you or your agents. This acceptance of risk relates exclusively to the direct cost of replacement of goods, and shall in no way cover any indirect or consequential losses."
                    }
                ]
            },
            {
                "key": 2,
                "value": "Any claim for loss must be lodged within 7 (seven) days of such loss by sending an email to claims@collivery.co.za. Any Claim lodged after such period will not be considered."
            },
            {
                "key": 3,
                "value": "Failure to supply necessary documents requested to support the claim will result in the claim not being considered."
            },
            {
                "key": 4,
                "value": "MDS shall not be liable for failure to fulfil its obligations if such failure is due to war, civil disobedience, industrial dispute, acts of God, or any event beyond MDS' reasonable control."
            },
            {
                "key": 5,
                "value": "If MDS is unable for any reason to effect delivery of the goods, all reasonable steps will be taken to return the goods to the Client. The Client will, however, be responsible for the costs of carriage, attempted delivery and return of the goods. Any failure to deliver or any late deliveries may not be used as motivation for non-payment for that delivery."
            },
            {
                "key": 6,
                "value": "MDS will not be responsible for any fulfilment of Customs formalities or payments. However, MDS will assist the Client as far as possible, on condition that such assistance will be rendered at the sole risk and responsibility of the Client and the Client undertakes to indemnify MDS against any claims in this respect."
            },
            {
                "key": "The Client warrants that:",
                "value": [
                    {
                        "key": 1,
                        "value": "The goods are accurately described on the waybill."
                    },
                    {
                        "key": 2,
                        "value": "The waybill is printed and affixed to the parcel."
                    },
                    {
                        "key": 3,
                        "value": "The goods are adequately packed and accurately addressed on the system generated waybill to enable delivery to take place with ordinary care and handling."
                    },
                    {
                        "key": 4,
                        "value": "The Client has to the best of its knowledge and belief, complied with all laws, rules and regulations regarding, the carriage and that the goods are not prohibited by Government regulation."
                    }
                ]
            },
            {
                "key": 8,
                "value": "The Client agrees to MDS' terms of payment and agrees that MDS shall be entitled to suspend, delay and\/or cancel collection and\/or delivery of any consignment(s) in the event of non payment, or to hold the consignments until such time as the account has been settled in full or to MDS' satisfaction."
            },
            {
                "key": 9,
                "value": "Failure to pay your account within 30 (thirty) days from the date of delivery of a tax invoice will attract interest in terms of the National Credit Act."
            },
            {
                "key": 10,
                "value": "You will be liable for all legal costs incurred by MDS on a scale as between attorney and Client, (including, but not limited to Sheriffs fees, collection commission and tracing agent's fees) in the event of MDS having to institute legal action in order to secure payment of any outstanding account."
            }
        ],
        "Risk Cover Exclusions": [
            {
                "key": "MDS will not be liable for any claims made by Client in any of the following circumstances:",
                "value": [
                    {
                        "key": 1,
                        "value": "Where the Client fails to submit the Claim to MDS within the relevant time limits."
                    },
                    {
                        "key": 2,
                        "value": "Where MDS is in possession of an unendorsed proof of delivery form for the consignment."
                    },
                    {
                        "key": 3,
                        "value": "Where the Goods consigned are Excluded Goods, where “Excluded Goods” means each of the following items:- \n            Money, bullion, credit cards, pre-paid cards, jewelry, watches, precious stones, furs, treasury notes, securities; stamps, patterns or manuscripts, plans, designs, explosives and all livestock or plants, guns, ammunition, hazardous goods and dangerous goods \/ materials, negotiable instruments, gemstones, works of art, securities, drugs, all framed pictures; artwork, solar panels or parts, mirrors and negotiable instruments, including collectible coins, cellphones, furniture and antiques, including fossils or fossil pieces, are carried entirely at your risk. Second - hand goods that have not been declared as such to MDS, who reserves the right to inspect second hand goods before acceptance and to delay the transit time by one day to effect such inspection."
                    },
                    {
                        "key": 4,
                        "value": "Where MDS in its reasonable opinion considers the Packaging of the Goods to be inadequate for rail, air or road transportation. In the event of a claim for damage, the receiver must retain all inner and outer packaging materials as well as the damaged goods. Failure by the receiver to retain the original goods and packaging at the original delivery location or the failure to make the delivered goods available for inspection will invalidate the claim."
                    },
                    {
                        "key": 5,
                        "value": "Where the Goods are determined by MDS to have been defective prior to the Carriage."
                    },
                    {
                        "key": 6,
                        "value": "Where damage, mechanical failure or other operational defect in the Goods could not, in the reasonable opinion of MDS, have been caused by the Carriage."
                    },
                    {
                        "key": 7,
                        "value": "Where MDS fails, delays or is unable to carry out its obligations under this contract due to strikes and \/ or lockouts (whether of MDS' own employees or those of others and whether or not MDS could have avoided the same by acceding to the demands of the employees responsible for such action), acts of God, war, terrorism, fire, flood, embargo, litigation, acts of government or any agency instrumentality or any political subdivision thereof or any other cause beyond the control MDS."
                    },
                    {
                        "key": 8,
                        "value": "Where the goods have been lost or damaged as a result of derailments, collisions, overturning or any similar incident."
                    },
                    {
                        "key": 9,
                        "value": "Where the Goods have not been packed in the original manufacturer's packaging or the equivalent."
                    },
                    {
                        "key": 10,
                        "value": "Where the Delivery Address is a post office box, a roadside drop or postal mail box."
                    }
                ]
            }
        ],
        "Amendments to Terms and Conditions of Contract ": [
            {
                "key": 1,
                "value": "MDS reserves the right to amend these terms and conditions of contract from time to time, without prior notice to the Customer."
            }
        ]
    },
    "last_updated": 1544079600
}

HTTP Request

GET v3/terms_and_conditions

14. Battery Types

Index


Requires authenticationRequires headers

Get all battery types, to be used when booking a waybill. Should be aggressively cached, or even statically defined.

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get("https://api.collivery.co.za/v3/battery_types", [
    'headers' => [
        "X-App-Name" => "My Custom App",
        "X-App-Version" => "0.2.1",
        "X-App-Host" => ".NET Framework 4.8",
        "X-App-Lang" => "C#",
    ],
]);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL("https://api.collivery.co.za/v3/battery_types");

let headers = {
    "X-App-Name": "My Custom App",
    "X-App-Version": "0.2.1",
    "X-App-Host": ".NET Framework 4.8",
    "X-App-Lang": "C#",
    "Accept": "application/json",
    "Content-Type": "application/json",
}

fetch(url, {
    method: "GET",
    headers: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET -G "https://api.collivery.co.za/v3/battery_types" \
    -H "X-App-Name: My Custom App" \
    -H "X-App-Version: 0.2.1" \
    -H "X-App-Host: .NET Framework 4.8" \
    -H "X-App-Lang: C#"

Example response (200):

{
    "data": [
        {
            "id": "pi_965",
            "name": "PI 965",
            "description": "Lithium Ion batteries packaged \/ sent on their own."
        },
        {
            "id": "pi_966",
            "name": "PI 966",
            "description": "Lithium Ion batteries WITH equipment. (Same box, but NOT inside the item)"
        },
        {
            "id": "pi_967",
            "name": "PI 967",
            "description": "Lithium Ion batteries contained IN equipment. (Not removed from the item)"
        }
    ]
}

HTTP Request

GET v3/battery_types

15. Errors

The API uses the following error codes:

Error Code Meaning
400 Bad Request -- There is something wrong with the data you provided
401 Unauthorized -- Your API key is wrong.
404 Not Found -- The url does not exist or the specified resource could not be found
405 Method Not Allowed -- You tried to access an endpoint with an invalid method
412 Precondition Failed -- The data you provided fails validation. Please see error messages
429 Too Many Requests -- You're requesting too many times within a minute
500 Internal Server Error -- We had a problem with our server. Try again later.