MENU navbar-image

Introduction

Welcome to the V3 Collivery.net API reference. Please refer to the documentation of our older api Learn more

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

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
  "X-App-Url": "https://example.com", // URL your site is hosted on. *Optional
}

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.

Base URL

https://api.collivery.co.za

Authenticating requests

Authenticate requests to this API's endpoints by sending a query parameter api_token in the request.

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

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

1. Authentication

Please note:

Log in

requires headers

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' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        '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"
);

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

let body = {
    "email": "demo@collivery.co.za",
    "password": "demo"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X POST \
"https://api.collivery.co.za/v3/login" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"email":"demo@collivery.co.za","password":"demo"}'

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 10
x-ratelimit-remaining: 9
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "data": {
        "id": 87,
        "full_name": "Collivery Demo",
        "email_address": "demo@collivery.co.za",
        "landline_number": "011 241 4911",
        "mobile_number": "",
        "api_token": "OpSjx5TlXGCGkzGAvUOm",
        "client": {
            "id": 116,
            "name": "Demo Collivery (PTY) Ltd.",
            "landline_number": "011 241 4911",
            "mobile_number": null,
            "account_code": "TESTCOLLIVER",
            "account_type": "account",
            "primary_address": {
                "id": 952,
                "address_id": 952,
                "custom_id": "",
                "town_id": 147,
                "town_name": "Johannesburg",
                "town_other_name": "",
                "suburb_id": 1936,
                "suburb_name": "Selby",
                "company_name": "MDS JHB",
                "building_complex_name": "",
                "street_number": "58C",
                "street_name": "Webber St",
                "postal_code": "",
                "country_name": "South Africa",
                "text": "MDS JHB, 58C Webber St, Selby, Johannesburg",
                "short_text": "MDS JHB, Selby, Johannesburg",
                "location_type": {
                    "id": 1,
                    "name": "Business Premises",
                    "surcharge": false,
                    "surcharge_amount": 0
                },
                "town": {
                    "id": 147,
                    "name": "Johannesburg",
                    "other_name": "",
                    "province": "GP",
                    "latitude": -26.204103,
                    "longitude": 28.047305,
                    "category": "Major",
                    "town_surcharge": 0
                },
                "geocode_data": {
                    "accuracy": 8,
                    "accuracy_type": "Address",
                    "last_geocoded_at": "2010-06-09",
                    "latitude": -26.214703,
                    "longitude": 28.040485
                }
            }
        }
    }
}

Request   

POST v3/login

Body Parameters

email  string  

Your email address.

password  string  

Your login password.

Register

requires authentication requires headers

Create a new client account. You will need to be provided with access to this endpoint. Please contact us to enable it.

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

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

let body = {
    "name": "John Doe",
    "terms": true,
    "email_address": "foobar@example.com",
    "cellphone": 123456789,
    "suburb_id": 1936,
    "street_name": "Webber Street",
    "street_number": "58c",
    "building": "MDS House",
    "is_vat_registered": "no",
    "town_id": 147
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X POST \
"https://api.collivery.co.za/v3/register?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"name":"John Doe","terms":true,"email_address":"foobar@example.com","cellphone":123456789,"suburb_id":1936,"street_name":"Webber Street","street_number":"58c","building":"MDS House","is_vat_registered":"no","town_id":147}'

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.co.za/v3/login"
        ]
    ]
}

Request   

POST v3/register

Query Parameters

api_token  string  

Authentication key.

Body Parameters

name  string  

Your full name. Minimum 5 characters. Maximum 50 characters.

terms  boolean  

Whether you accept all terms an conditions. Should be fetched from our /terms endpoint.

email_address  string  

A valid email address that is not yet registered.

telephone  integer optional  

Your personal or business land-line number. One of telephone or cellphone must be provided.

cellphone  integer optional  

Your personal or business mobile number. One of telephone or cellphone must be provided.

suburb_id  integer  

A valid id of a suburb in the town provided, can be fetched from out /suburbs endpoint.

street_name  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  integer 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.

is_vat_registered  string optional  

Must be one of yes or no.

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.

other_input  string optional  

This field is required when find_how is 10.

town_id  integer  

A valid town id, can be fetched from out /towns endpoint.

2. Addresses

Manage Addresses

Index

requires authentication requires headers

List your addresses

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

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

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

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/address?api_token=OpSjx5TlXGCGkzGAvUOm&search=Johannes&page=1&per_page=3" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 54
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "data": [
        {
            "id": 952,
            "address_id": 952,
            "custom_id": "",
            "town_id": 147,
            "town_name": "Johannesburg",
            "town_other_name": "",
            "suburb_id": 1936,
            "suburb_name": "Selby",
            "company_name": "MDS JHB",
            "building_complex_name": "",
            "street_number": "58C",
            "street_name": "Webber St",
            "postal_code": "",
            "country_name": "South Africa",
            "text": "MDS JHB, 58C Webber St, Selby, Johannesburg",
            "short_text": "MDS JHB, Selby, Johannesburg",
            "location_type": {
                "id": 1,
                "name": "Business Premises",
                "surcharge": false,
                "surcharge_amount": 0
            },
            "town": {
                "id": 147,
                "name": "Johannesburg",
                "other_name": "",
                "province": "GP",
                "latitude": -26.204103,
                "longitude": 28.047305,
                "category": "Major",
                "town_surcharge": 0
            },
            "geocode_data": {
                "accuracy": 8,
                "accuracy_type": "Address",
                "last_geocoded_at": "2010-06-09",
                "latitude": -26.214703,
                "longitude": 28.040485
            }
        }
    ],
    "links": {
        "first": "https://api.collivery.co.za/v3/address?page=1",
        "last": "https://api.collivery.co.za/v3/address?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "active": false
            },
            {
                "url": "https://api.collivery.co.za/v3/address?page=1",
                "label": "1",
                "active": true
            },
            {
                "url": null,
                "label": "Next »",
                "active": false
            }
        ],
        "path": "https://api.collivery.co.za/v3/address",
        "per_page": 3,
        "to": 1,
        "total": 1
    }
}

Request   

GET v3/address

Query Parameters

api_token  string  

Authentication key.

include  string optional  

A comma separated list of relationships to return. Available entries: contacts, suburb, town, active_waybills.

custom_id  string optional  

Search by this custom address id only.

search  string optional  

Search in street, building, company_name, suburb or town for a match.

town_id  string optional  

Limit to results with this town id.

suburb_id  string optional  

Limit to results with this suburb id.

page  string optional  

Page number to return.

per_page  string 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.0 is the same as not limiting. Default is 100 Example: 3.

Store

requires authentication requires headers

Save a new Address.

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://api.collivery.co.za/v3/address',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
        'json' => [
            'town_id' => 147,
            'town_name' => 'Johannesburg',
            'province' => 'Gauteng',
            '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' => [
                'id' => 2519728,
                'full_name' => 'John Doe',
                'cellphone' => '0723456789',
                'email_address' => 'demo@collivery.co.za',
            ],
            'country' => 'ZAF',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/address"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

let body = {
    "town_id": 147,
    "town_name": "Johannesburg",
    "province": "Gauteng",
    "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": {
        "id": 2519728,
        "full_name": "John Doe",
        "cellphone": "0723456789",
        "email_address": "demo@collivery.co.za"
    },
    "country": "ZAF"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X POST \
"https://api.collivery.co.za/v3/address?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"town_id":147,"town_name":"Johannesburg","province":"Gauteng","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":{"id":2519728,"full_name":"John Doe","cellphone":"0723456789","email_address":"demo@collivery.co.za"},"country":"ZAF"}'

Example response (201):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 53
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "data": {
        "id": 4649651,
        "address_id": 4649651,
        "custom_id": "",
        "town_id": 147,
        "town_name": "Johannesburg",
        "town_other_name": "",
        "suburb_id": 1936,
        "suburb_name": "Selby",
        "company_name": "MDS Collivery",
        "building_complex_name": "MDS House",
        "street_number": "58c",
        "street_name": "Webber Street",
        "postal_code": null,
        "country_name": null,
        "text": "MDS Collivery, MDS House, 58c Webber Street, Selby, Johannesburg",
        "short_text": "MDS Collivery, Selby, Johannesburg",
        "location_type": {
            "id": 1,
            "name": "Business Premises",
            "surcharge": false,
            "surcharge_amount": 0
        },
        "contacts": [
            {
                "id": 4901835,
                "full_name": "John Doe ",
                "cell_no": "0723456789",
                "cellphone": "0723456789",
                "work_no": "",
                "work_phone": "",
                "email": "demo@collivery.co.za"
            }
        ],
        "town": {
            "id": 147,
            "name": "Johannesburg",
            "other_name": "",
            "province": "GP",
            "latitude": -26.204103,
            "longitude": 28.047305,
            "category": "Major",
            "town_surcharge": 0
        },
        "geocode_data": {
            "accuracy": 5,
            "accuracy_type": "Suburb",
            "last_geocoded_at": "1900-01-01",
            "latitude": -26.2125,
            "longitude": 28.0375
        }
    }
}

Request   

POST v3/address

Query Parameters

api_token  string  

Authentication key.

Body Parameters

custom_id  string optional  

The custom id you would like to assign to this address. Must be unique. Max 30 characters.

town_id  integer  

without town_name and suburb_id. Required with 'country' only if 'country' is sent or not ZAF . Can be obtained from /towns/ endpoint.

town_name  string  

without town_id and suburb_id. Can be obtained from /towns/ endpoint.

province  string. optional  

The name of the province, useful when providing town_name to filter the towns.

suburb_id  integer  

without suburb_name. Can be obtained from /suburbs/ endpoint. Ignored when country sent is not ZAF.

suburb_name  string optional  

Required when country is not ZAF or without suburb_id. South African suburbs 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  

The name of the street that the address is on. Max 50 characters.

location_type  integer  

without location_type_name. The id of the location type for the address. Can be obtained from /location_types/ endpoint.

location_type_name  string  

without location_type. The name of the location type for the address. Can be obtained from /location_types/ endpoint.

contact  object optional  

optional If you are creating/updating a contact with the address, please ensure that it is a valid JSON object.

contact.id  integer optional  

optional Only required for update requests. The id of the contact that you wish to update.

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.

country  string. optional  

The three letter abbreviation (ISO 3166) for the country. Defaults to ZAF. Can be obtained from /country/ endpoint.

Show

requires authentication requires headers

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/address/-1',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/address/-1"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/address/{id}?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 52
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "data": {
        "id": 952,
        "address_id": 952,
        "custom_id": "",
        "town_id": 147,
        "town_name": "Johannesburg",
        "town_other_name": "",
        "suburb_id": 1936,
        "suburb_name": "Selby",
        "company_name": "MDS JHB",
        "building_complex_name": "",
        "street_number": "58C",
        "street_name": "Webber St",
        "postal_code": "",
        "country_name": "South Africa",
        "text": "MDS JHB, 58C Webber St, Selby, Johannesburg",
        "short_text": "MDS JHB, Selby, Johannesburg",
        "location_type": {
            "id": 1,
            "name": "Business Premises",
            "surcharge": false,
            "surcharge_amount": 0
        },
        "contacts": [
            {
                "id": 593,
                "full_name": "Billy banks ",
                "cell_no": "0721234567",
                "cellphone": "0721234567",
                "work_no": "0214242000",
                "work_phone": "0214242000",
                "email": "world@example.com"
            },
            {
                "id": 3804171,
                "full_name": "John Doe ",
                "cell_no": "0721234567",
                "cellphone": "0721234567",
                "work_no": null,
                "work_phone": null,
                "email": "foo@example.com"
            },
            {
                "id": 3910017,
                "full_name": "Tyron Blakes ",
                "cell_no": "0831234569",
                "cellphone": "0831234569",
                "work_no": "0314555555",
                "work_phone": "0314555555",
                "email": "tyron@hotmail.com"
            },
            {
                "id": 3910018,
                "full_name": "Vaugan Blakes ",
                "cell_no": "0831234530",
                "cellphone": "0831234530",
                "work_no": "0314555590",
                "work_phone": "0314555590",
                "email": "vaugan@hotmail.com"
            },
            {
                "id": 4123858,
                "full_name": "John Doe ",
                "cell_no": "0721234567",
                "cellphone": "0721234567",
                "work_no": "0721234567",
                "work_phone": "0721234567",
                "email": "foo@example.com"
            },
            {
                "id": 4478364,
                "full_name": "Marius Claassen ",
                "cell_no": "086 143 3548",
                "cellphone": "086 143 3548",
                "work_no": "086 143 354",
                "work_phone": "086 143 354",
                "email": "info@ideliver.co.za"
            }
        ],
        "town": {
            "id": 147,
            "name": "Johannesburg",
            "other_name": "",
            "province": "GP",
            "latitude": -26.204103,
            "longitude": 28.047305,
            "category": "Major",
            "town_surcharge": 0
        },
        "geocode_data": {
            "accuracy": 8,
            "accuracy_type": "Address",
            "last_geocoded_at": "2010-06-09",
            "latitude": -26.214703,
            "longitude": 28.040485
        }
    }
}

Request   

GET v3/address/{id}

URL Parameters

id  integer  

The ID of the address.

address  number  

The address id.

Query Parameters

api_token  string  

Authentication key.

Update

requires authentication requires 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/-1',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
        'json' => [
            'town_id' => 147,
            'town_name' => 'Johannesburg',
            'province' => 'Gauteng',
            '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' => [
                'id' => 2519728,
                'full_name' => 'John Doe',
                'cellphone' => '0723456789',
                'email_address' => 'demo@collivery.co.za',
            ],
            'country' => 'ZAF',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/address/-1"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

let body = {
    "town_id": 147,
    "town_name": "Johannesburg",
    "province": "Gauteng",
    "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": {
        "id": 2519728,
        "full_name": "John Doe",
        "cellphone": "0723456789",
        "email_address": "demo@collivery.co.za"
    },
    "country": "ZAF"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X PUT \
"https://api.collivery.co.za/v3/address/{id}?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"town_id":147,"town_name":"Johannesburg","province":"Gauteng","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":{"id":2519728,"full_name":"John Doe","cellphone":"0723456789","email_address":"demo@collivery.co.za"},"country":"ZAF"}'

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",
        "geocode_data": {
            "accuracy": 5,
            "accuracy_type": "Suburb",
            "last_geocoded_at": "1900-01-01",
            "latitude": 0,
            "longitude": 0
        }
    }
}

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."
    }
}

Request   

PUT v3/address/{id}

PATCH v3/address/{id}

URL Parameters

id  integer  

The ID of the address.

address  number  

The address id.

Query Parameters

api_token  string  

Authentication key.

Body Parameters

custom_id  string optional  

The custom id you would like to assign to this address. Must be unique. Max 30 characters.

town_id  integer  

without town_name and suburb_id. Required with 'country' only if 'country' is sent or not ZAF . Can be obtained from /towns/ endpoint.

town_name  string  

without town_id and suburb_id. Can be obtained from /towns/ endpoint.

province  string. optional  

The name of the province, useful when providing town_name to filter the towns.

suburb_id  integer  

without suburb_name. Can be obtained from /suburbs/ endpoint. Ignored when country sent is not ZAF.

suburb_name  string optional  

Required when country is not ZAF or without suburb_id. South African suburbs 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  

The name of the street that the address is on. Max 50 characters.

location_type  integer  

without location_type_name. The id of the location type for the address. Can be obtained from /location_types/ endpoint.

location_type_name  string  

without location_type. The name of the location type for the address. Can be obtained from /location_types/ endpoint.

contact  object optional  

optional If you are creating/updating a contact with the address, please ensure that it is a valid JSON object.

contact.id  integer optional  

optional Only required for update requests. The id of the contact that you wish to update.

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.

country  string. optional  

The three letter abbreviation (ISO 3166) for the country. Defaults to ZAF. Can be obtained from /country/ endpoint.

Delete

requires authentication requires headers

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->delete(
    'https://api.collivery.co.za/v3/address/952',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/address/952"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());
curl -X DELETE \
"https://api.collivery.co.za/v3/address/{id}?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

Example response (200):


{
    "data": {
        "message": "Address # 952 has been deleted"
    }
}

Example response (400):


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

Request   

DELETE v3/address/{id}

URL Parameters

id  integer optional  

required.

Query Parameters

api_token  string  

Authentication key.

Show Default Address

requires authentication requires headers

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

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/default_address?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

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": "Default address not found."
    }
}

Request   

GET v3/default_address

Query Parameters

api_token  string  

Authentication key.

3. Contacts

Manage Address Contacts

Index

requires authentication requires headers

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

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

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

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/contacts?api_token=OpSjx5TlXGCGkzGAvUOm&search=Collivery&page=1&per_page=3" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

Example response (200):


{
    "data": [
        {
            "id": 729097,
            "email": "support@collivery.co.za",
            "full_name": "Collivery Support",
            "cell_no": null,
            "cellphone": null,
            "work_no": "0123456789",
            "work_phone": "0123456789"
        },
        {
            "id": 729098,
            "email": "integration@collivery.co.za",
            "full_name": "Collivery Integration",
            "cell_no": null,
            "cellphone": null,
            "work_no": "0123456789",
            "work_phone": "0123456789"
        },
        {
            "id": 729099,
            "email": "api@collivery.co.za",
            "full_name": "Collivery Api",
            "cell_no": null,
            "cellphone": null,
            "work_no": "0123456789",
            "work_phone": "0123456789"
        }
    ],
    "links": {
        "first": "https://api.collivery.co.za/v3/contacts?page=1",
        "last": "https://api.collivery.co.za/v3/contacts?page=1532",
        "next": "https://api.collivery.co.za/v3/contacts?page=1501",
        "prev": "https://api.collivery.co.za/v3/contacts?page=1499"
    },
    "meta": {
        "current_page": 1500,
        "from": 4498,
        "last_page": 1532,
        "path": "https://api.collivery.co.za/v3/contacts",
        "per_page": "3",
        "to": 4500,
        "total": 4596
    }
}

Request   

GET v3/contacts

Query Parameters

api_token  string  

Authentication key.

address_id  string optional  

Limit to contacts for this specific address.

search  string optional  

Search in name for a match.

page  string optional  

Page number to return.

per_page  string 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.0 is the same as not limiting. Default is 100.

Store

requires authentication requires headers

Save a new Contact.

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

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

let body = {
    "address_id": 952,
    "email": "foo@example.com",
    "full_name": "John Doe",
    "cell_no": "0721234567",
    "cellphone": "0721234567",
    "work_no": null,
    "work_phone": null
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X POST \
"https://api.collivery.co.za/v3/contacts?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"address_id":952,"email":"foo@example.com","full_name":"John Doe","cell_no":"0721234567","cellphone":"0721234567","work_no":null,"work_phone":null}'

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 50
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "data": {
        "id": 3804171,
        "full_name": "John Doe ",
        "cell_no": "0721234567",
        "cellphone": "0721234567",
        "work_no": null,
        "work_phone": null,
        "email": "foo@example.com"
    }
}

Request   

POST v3/contacts

Query Parameters

api_token  string  

Authentication key.

Body Parameters

address_id  integer  

The id of the address you wish to add this contact to. Can be fetched through the /addresses endpoint.

email  string optional  

optional Valid email address. Minimum 5 characters.

full_name  string optional  

required. The contact's full name. Minimum 3 characters.

cell_no  string  

without work_phone. Minimum 10 characters. For legacy reasons, cell_no is also supported.

cellphone  string  

without work_phone. Minimum 10 characters. For legacy reasons, cell_no is also supported.

work_no  string  

without cellphone. Minimum 10 characters. For legacy reasons, work_no is also supported.

work_phone  string  

without cellphone. Minimum 10 characters. For legacy reasons, work_no is also supported.

Show

requires authentication requires headers

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/contacts/593',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/contacts/593"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/contacts/{id}?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

Example response (404):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 49
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "message": "Address Contact for id 1 not found"
}

Request   

GET v3/contacts/{id}

URL Parameters

id  integer optional  

required.

Query Parameters

api_token  string  

Authentication key.

Update

requires authentication requires headers

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->put(
    'https://api.collivery.co.za/v3/contacts/593',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
        'json' => [
            'address_id' => 952,
            'email' => 'foo@example.com',
            'full_name' => 'John Doe',
            'cell_no' => '0721234567',
            'cellphone' => '0721234567',
            'work_no' => null,
            'work_phone' => null,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/contacts/593"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

let body = {
    "address_id": 952,
    "email": "foo@example.com",
    "full_name": "John Doe",
    "cell_no": "0721234567",
    "cellphone": "0721234567",
    "work_no": null,
    "work_phone": null
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X PUT \
"https://api.collivery.co.za/v3/contacts/{id}?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"address_id":952,"email":"foo@example.com","full_name":"John Doe","cell_no":"0721234567","cellphone":"0721234567","work_no":null,"work_phone":null}'

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 48
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "data": {
        "id": 593,
        "full_name": "John Doe ",
        "cell_no": "0721234567",
        "cellphone": "0721234567",
        "work_no": null,
        "work_phone": null,
        "email": "foo@example.com"
    }
}

Request   

PUT v3/contacts/{id}

PATCH v3/contacts/{id}

URL Parameters

id  string  

The id

contact  number optional  

id required The id

Query Parameters

api_token  string  

Authentication key.

Body Parameters

address_id  integer  

The id of the address you wish to add this contact to. Can be fetched through the /addresses endpoint.

email  string optional  

optional Valid email address. Minimum 5 characters.

full_name  string optional  

required. The contact's full name. Minimum 3 characters.

cell_no  string  

without work_phone. Minimum 10 characters. For legacy reasons, cell_no is also supported.

cellphone  string  

without work_phone. Minimum 10 characters. For legacy reasons, cell_no is also supported.

work_no  string  

without cellphone. Minimum 10 characters. For legacy reasons, work_no is also supported.

work_phone  string  

without cellphone. Minimum 10 characters. For legacy reasons, work_no is also supported.

Delete

requires authentication requires headers

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->delete(
    'https://api.collivery.co.za/v3/contacts/ex',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/contacts/ex"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());
curl -X DELETE \
"https://api.collivery.co.za/v3/contacts/{id}?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

Example response (200):


{
    "data": {
        "message": "Contact # 593 has been deleted."
    }
}

Example response (400):


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

Request   

DELETE v3/contacts/{id}

URL Parameters

id  string  

The ID of the contact.

contact  string optional  

Query Parameters

api_token  string  

Authentication key.

4. Get Quote

Request a quote

requires authentication requires 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' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
        'json' => [
            'services' => [
                2,
            ],
            'parcels' => [
                [
                    'length' => 21.5,
                    'width' => 10.0,
                    'height' => 5.5,
                    'weight' => 5.2,
                    'quantity' => 2,
                    'product_id' => 2542,
                ],
            ],
            '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',
            'strict_delivery_time' => false,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/quote"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

let body = {
    "services": [
        2
    ],
    "parcels": [
        {
            "length": 21.5,
            "width": 10,
            "height": 5.5,
            "weight": 5.2,
            "quantity": 2,
            "product_id": 2542
        }
    ],
    "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",
    "strict_delivery_time": false
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X POST \
"https://api.collivery.co.za/v3/quote?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"services":[2],"parcels":[{"length":21.5,"width":10,"height":5.5,"weight":5.2,"quantity":2,"product_id":2542}],"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","strict_delivery_time":false}'

Example response (422):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 44
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "error": [
        [
            "The delivery time must be a date before 2024-11-21 07:50:02."
        ]
    ]
}

Request   

POST v3/quote

Query Parameters

api_token  string  

Authentication key.

Body Parameters

services  object[] optional  

number 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 quote. Will default to an "average" parcel if not supplied. Dimensions are limited to 1000, weight is limited to 400

parcels[].length  number optional  

The length of the parcel. Values in centimetres. Can be supplied as floats or integers.

parcels[].width  number optional  

The width of the parcel. Values in centimetres. Can be supplied as floats or integers.

parcels[].height  number optional  

The height of the parcel. Values in centimetres. Can be supplied as floats or integers.

parcels[].weight  number optional  

The weight of the parcel. Values in kilograms. Can be supplied as floats or integers.

parcels[].quantity  integer optional  

The amount of parcels of this type.

parcels[].product_id  integer optional  

The id of the predefined parcel. Length, width, height and weight will be ignored if value is set. Can be obtained from /predefined_parcels/ endpoint.

collection_address  integer/object optional  

optional Required if collection_town is not supplied. Can be the id of the address or a json object if the address is not yet stored. See below for object structure

collection_address.custom_id  string optional  

The custom id you would like to assign to this address. Must be unique. Max 20 characters.

collection_address.country  string. optional  

The three letter abbreviation (ISO 3166) for the country. Only ZAF supported currently. Can be obtained from /country/ endpoint.

collection_address.town_id  integer optional  

Required without town_name and suburb_id. Can be obtained from /towns/ endpoint.

collection_address.town_name  string optional  

Required without town_id and suburb_id. Can be obtained from /towns/ endpoint.

collection_address.suburb_id  integer optional  

Required without suburb_name. Can be obtained from /suburbs/ endpoint.

collection_address.suburb_name  string optional  

Required when country is not ZAF or without suburb_id. South African suburbs can be obtained from /suburbs/ endpoint. No-Example

collection_address.company_name  string optional  

The name of the company of the address. Max 50 characters.

collection_address.building  string optional  

The building of the address. Max 50 characters.

collection_address.street_number  string optional  

The number on the street of the address. Max 5 characters.

collection_address.street  string optional  

optional Required if the collection_address is filled. The name of the street that the address is on. Max 50 characters.

collection_address.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.

collection_address.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.

delivery_address  integer/object optional  

optional Required if delivery_town is not supplied. Can be the id of the address or a json object if the address is not yet stored. See below for object structure

delivery_address.custom_id  string optional  

The custom id you would like to assign to this address. Must be unique. Max 20 characters.

delivery_address.country  string. optional  

The three letter abbreviation (ISO 3166) for the country. Defaults to ZAF. Can be obtained from /country/ endpoint.

delivery_address.town_id  integer optional  

Required without town_nameand suburb_id. Can be obtained from /towns/ endpoint.

delivery_address.town_name  string optional  

Required without town_idand suburb_id. Can be obtained from /towns/ endpoint.

delivery_address.suburb_id  integer optional  

Required without suburb_name. Can be obtained from /suburbs/ endpoint. Ignored when country sent is not ZAF.

delivery_address.suburb_name  string optional  

Required when country is not ZAF or without suburb_id. South African suburbs can be obtained from /suburbs/ endpoint. No-Example

delivery_address.company_name  string optional  

The name of the company of the address. Max 50 characters.

delivery_address.building  string optional  

The building of the address. Max 50 characters.

delivery_address.street_number  string optional  

The number on the street of the address. Max 5 characters.

delivery_address.street  string optional  

optional Required if the delivery_address is filled. The name of the street that the address is on. Max 50 characters.

delivery_address.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.

delivery_address.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.

collection_town  integer optional  

optional Required if collection_address is not supplied.

delivery_town  integer optional  

optional Required if delivery_address is not supplied.

collection_location_type  integer optional  

optional Must be a valid location type. Values can be gotten from our /location_type endpoint.

delivery_location_type  integer optional  

optional Must be a valid location type. Values can be gotten from our /location_type endpoint.

collection_time  string optional  

optional Any future date/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 future date/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.

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.

hide_collection_address  boolean optional  

optional Whether to reprint the waybill when received in order to hide collection details from delivery recipient. Surcharges will be applied. Defaults to false.

delivery_pin  boolean optional  

optional Whether to enable delivery pin. Pin is emailed/SMS'd to the delivery contact and is verified upon delivery. Surcharges will be applied. Defaults to false.

strict_delivery_time  boolean optional  

document_express  boolean optional  

optional Whether to set the waybill to use Document Express. This is an over-night service for documents only. Service sent will be ignored and parcels if exist must validate to be below 2Kg. Defaults to false.

5. Waybills

Index

requires authentication requires headers

List your waybills

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/waybill',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
        'json' => [
            'custom_id' => 'CustomID_786',
            'per_page' => '15',
            'statuses' => '3',
            'show' => 'active',
            'include' => 'client,collection_address',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/waybill"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

let body = {
    "custom_id": "CustomID_786",
    "per_page": "15",
    "statuses": "3",
    "show": "active",
    "include": "client,collection_address"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/waybill?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"custom_id":"CustomID_786","per_page":"15","statuses":"3","show":"active","include":"client,collection_address"}'

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 42
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "data": [],
    "links": {
        "first": "https://api.collivery.co.za/v3/waybill?page=1",
        "last": "https://api.collivery.co.za/v3/waybill?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": null,
        "last_page": 1,
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "active": false
            },
            {
                "url": "https://api.collivery.co.za/v3/waybill?page=1",
                "label": "1",
                "active": true
            },
            {
                "url": null,
                "label": "Next »",
                "active": false
            }
        ],
        "path": "https://api.collivery.co.za/v3/waybill",
        "per_page": 15,
        "to": null,
        "total": 0
    }
}

Request   

GET v3/waybill

Query Parameters

api_token  string  

Authentication key.

Body Parameters

custom_id  string optional  

Custom Waybill ID.

per_page  The optional  

limit per page. Max is 10000. If this option is provided, 'links' and meta will exist in the response with further information about the full list of waybills. 0 is the same as not limiting. Default is 100.

statuses  optional optional  

A comma-separated list of statuses to limit the results to. Defaults to all active statuses.

show  optional optional  

The value represent group of statuses. Acceptable values include: 'active', 'in-active', 'cancelled', 'all', 'pre-collected', 'pre-delivered', 'pre-received', or 'failed'. If no value is provided, only items with 'active' status will be returned by default.

start_date  optional optional  

Any valid time representation that can be parsed by PHP strtotime(). Refers to the date the waybill was created. Defaults to 1 week ago.

end_date  Any optional  

valid time representation that can be parsed by PHP strtotime(). Refers to the date the waybill was created. Defaults to now.

include  A optional  

comma separated list of relationships to return. Available entries: client, collection_address, delivery_address, collection_contact, delivery_contact, proofs_of_delivery.

Store

requires authentication requires headers

Create a new waybill

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://api.collivery.co.za/v3/waybill',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
        'json' => [
            'service' => 3,
            'parcels' => [
                [
                    'length' => 21.5,
                    'width' => 10.0,
                    'height' => 5.5,
                    'weight' => 5.2,
                    'quantity' => 2,
                    'product_id' => 2542,
                    'ref' => 'ypcemwoqy',
                ],
            ],
            'collection_address' => '952',
            'collection_contact' => 593,
            'delivery_address' => '955',
            'delivery_contact' => 596,
            'exclude_weekend' => true,
            'risk_cover' => true,
            'consolidate' => true,
            'battery_type' => 'pi_965',
            'parcel_type' => 2,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/waybill"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

let body = {
    "service": 3,
    "parcels": [
        {
            "length": 21.5,
            "width": 10,
            "height": 5.5,
            "weight": 5.2,
            "quantity": 2,
            "product_id": 2542,
            "ref": "ypcemwoqy"
        }
    ],
    "collection_address": "952",
    "collection_contact": 593,
    "delivery_address": "955",
    "delivery_contact": 596,
    "exclude_weekend": true,
    "risk_cover": true,
    "consolidate": true,
    "battery_type": "pi_965",
    "parcel_type": 2
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X POST \
"https://api.collivery.co.za/v3/waybill?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"service":3,"parcels":[{"length":21.5,"width":10,"height":5.5,"weight":5.2,"quantity":2,"product_id":2542,"ref":"ypcemwoqy"}],"collection_address":"952","collection_contact":593,"delivery_address":"955","delivery_contact":596,"exclude_weekend":true,"risk_cover":true,"consolidate":true,"battery_type":"pi_965","parcel_type":2}'

Example response (404):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 41
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "message": "Address for id 955 not found"
}

Request   

POST v3/waybill

Query Parameters

api_token  string  

Authentication key.

Body Parameters

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 a quote. Will default to an "average" parcel if not supplied. Dimensions are limited to 1000, weight is limited to 400

parcels[].length  number optional  

The length of the parcel. Values in centimetres. Can be supplied as floats or integers.

parcels[].width  number optional  

The width of the parcel. Values in centimetres. Can be supplied as floats or integers.

parcels[].height  number optional  

The height of the parcel. Values in centimetres. Can be supplied as floats or integers.

parcels[].weight  number optional  

The weight of the parcel. Values in kilograms. Can be supplied as floats or integers.

parcels[].quantity  integer optional  

The amount of parcels of this type.

parcels[].product_id  integer optional  

The id of the predefined parcel. Length, width, height and weight will be ignored if value is set. Can be obtained from /predefined_parcels/ endpoint.

parcels[].ref  string optional  

Must not be greater than 25 characters.

parcels[].reference  string optional  

Parcel reference. Max 25 characters.

delivery_method  integer optional  

The vehicle that we should collect it with. Defaults to 1 (Motorbike).

collection_address  integer/object optional  

optional Required if collection_town is not supplied. Can be the id of the address or a json object if the address is not yet stored. See below for object structure.

collection_address.custom_id  string optional  

The custom id you would like to assign to this address. Must be unique. Max 30 characters.

collection_address.country  string. optional  

The three letter abbreviation (ISO 3166) for the country. Only ZAF supported currently. Can be obtained from /country/ endpoint.

collection_address.town_id  integer  

without town_name and suburb_id. Required with 'country' only if 'country' is sent or not ZAF . Can be obtained from /towns/ endpoint.

collection_address.town_name  string optional  

Required without town_id and suburb_id. Can be obtained from /towns/ endpoint.

collection_address.suburb_id  integer optional  

Required without suburb_name. Can be obtained from /suburbs/ endpoint. Ignored when country sent is not ZAF.

collection_address.suburb_name  string optional  

Required when country is not ZAF or without suburb_id. South African suburbs can be obtained from /suburbs/ endpoint.

collection_address.company_name  string optional  

The name of the company of the address. Max 50 characters.

collection_address.building  string optional  

The building of the address. Max 50 characters.

collection_address.street_number  string optional  

The number on the street of the address. Max 5 characters.

collection_address.street  string optional  

optional Required if the collection_address is filled. The name of the street that the address is on. Max 50 characters.

collection_address.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.

collection_address.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.

collection_address.contact  object optional  

optional If you are creating a contact with the address, please ensure that it is a valid JSON object.

collection_address.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.

collection_address.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.

collection_address.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.

collection_address.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.

collection_contact  integer optional  

optional The id of the Collection Contact. Required only if you are not providing the contact object in collection_address.

delivery_address  integer/object optional  

optional Required if delivery_town is not supplied. Can be the id of the address or a json object if the address is not yet stored. See below for object structure.

delivery_address.custom_id  string optional  

The custom id you would like to assign to this address. Must be unique. Max 20 characters.

delivery_address.country  string. optional  

The three letter abbreviation (ISO 3166) for the country. Defaults to ZAF. Can be obtained from /country/ endpoint.

delivery_address.town_id  integer  

without town_name and suburb_id. Required with 'country' only if 'country' is sent or not ZAF . Can be obtained from /towns/ endpoint.

delivery_address.town_name  string optional  

Required without town_id and suburb_id. Can be obtained from /towns/ endpoint.

delivery_address.suburb_id  integer optional  

Required without suburb_name. Can be obtained from /suburbs/ endpoint. Ignored when country sent is not ZAF.

delivery_address.suburb_name  string optional  

Required when country is not ZAF or without suburb_id. South African suburbs can be obtained from /suburbs/ endpoint.

delivery_address.company_name  string optional  

The name of the company of the address. Max 50 characters.

delivery_address.building  string optional  

The building of the address. Max 50 characters.

delivery_address.street_number  string optional  

The number on the street of the address. Max 5 characters.

delivery_address.street  string optional  

optional Required if the delivery_address is filled. The name of the street that the address is on. Max 50 characters.

delivery_address.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.

delivery_address.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.

delivery_address.contact  object optional  

optional If you are creating a contact with the address, please ensure that it is a valid JSON object.

delivery_address.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.

delivery_address.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.

delivery_address.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.

delivery_address.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.

delivery_contact  integer optional  

optional The id of the Delivery Contact. Required only if you are not providing the contact object in delivery_address.

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. Required for international waybills. Max 100 characters.

special_instructions  string optional  

Any instructions on the handling, collection or delivery of your waybill. Max 2048 characters.

collection_time  string optional  

optional Any future date/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 future date/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.

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.

hide_collection_address  boolean optional  

optional Whether to reprint the waybill when received in order to hide collection details from delivery recipient. Surcharges will be applied. Defaults to false.

delivery_pin  boolean optional  

optional Whether to enable delivery pin. Pin is emailed/SMS'd to the delivery contact and is verified upon delivery. Surcharges will be applied. Defaults to false.

strict_delivery_time  boolean optional  

Waybill should not be delivered before delivery_time. Delivery time may change if it cannot be reached, this setting does not stop that.

consolidate  boolean optional  

optional Whether to allow for waybill to be consolidated with existing pre-collected waybill that has matching addresses, service and dates. NB: Consolidation also need to be activated on your account so please contact support@colllivery.co.za if you wish to do so. Defaults to false.

auto_accept  boolean optional  

optional Whether waybill added should immediately be accepted. 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. Required for international waybills.

document_express  boolean optional  

optional Whether to set the waybill to use Document Express. This is an over-night service for documents only. Service sent will be ignored and parcels if exist must validate to be below 2Kg. Defaults to false.

parcel_type  integer optional  

Required if waybill is international export, or if Can be obtained from /parcel_types/ endpoint .

Show

requires authentication requires headers

This will return a waybill's information, optionally along with addresses, contacts, proofs of delivery as needed

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/waybill/2904397',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
            'include'=> 'client,collection_address',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/waybill/2904397"
);

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

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

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/waybill/{collivery_id}?api_token=OpSjx5TlXGCGkzGAvUOm&include=client,collection_address" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

Example response (200):


{
    "data": {
        "id": 2904397,
        "custom_id": "",
        "service_type_id": 2,
        "service_type_name": "Next Day",
        "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": 6,
        "status_name": "Invoiced",
        "parcel_description": "",
        "weight": 0.4,
        "volumetric_weight": 0.6,
        "total_price": 100,
        "risk_cover": false,
        "parcels": [
            {
                "add_method": "client",
                "created_at": "2020-09-18 14:33:41",
                "custom_id": "",
                "height": "6.0",
                "id": 7699472,
                "waybill_id": 4001907,
                "length": "22.0",
                "parcel_number": 1,
                "quantity": 1,
                "volumetric_weight": "0.3",
                "weight": "5.2",
                "width": "10.0"
            }
        ],
        "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."
    }
}

Request   

GET v3/waybill/{collivery_id}

URL Parameters

collivery_id  string  

The waybill's ID.

Query Parameters

api_token  string  

Authentication key.

include  string optional  

A comma separated list of relationships to return. Available entries: client, collection_address, delivery_address, collection_contact, delivery_contact, proofs_of_delivery.

Update

requires authentication requires headers

Allows you to update the waybill's service type.

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->put(
    'https://api.collivery.co.za/v3/waybill/325',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
            'include'=> 'client,collection_address',
        ],
        'json' => [
            'service' => 3,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/waybill/325"
);

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

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

let body = {
    "service": 3
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X PUT \
"https://api.collivery.co.za/v3/waybill/{collivery_id}?api_token=OpSjx5TlXGCGkzGAvUOm&include=client,collection_address" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"service":3}'

Example response (200):


{
    "data": {
        "id": 4001907,
        "custom_id": "",
        "service_type_id": 3,
        "service_type_name": "Road Freight",
        "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": 6,
        "status_name": "Invoiced",
        "parcel_description": "",
        "weight": 0.4,
        "volumetric_weight": 0.6,
        "total_price": 100,
        "risk_cover": false,
        "parcels": [
            {
                "add_method": "client",
                "created_at": "2020-09-18 14:33:41",
                "custom_id": "",
                "height": "6.0",
                "id": 7699472,
                "waybill_id": 4001907,
                "length": "22.0",
                "parcel_number": 1,
                "quantity": 1,
                "volumetric_weight": "0.3",
                "weight": "5.2",
                "width": "10.0"
            }
        ],
        "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 (401):


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

Request   

PUT v3/waybill/{collivery_id}

PATCH v3/waybill/{collivery_id}

URL Parameters

collivery_id  integer  

The ID of the collivery.

waybill  string  

The waybill id.

Query Parameters

api_token  string  

Authentication key.

include  string optional  

A comma separated list of relationships to return. Available entries: client, collection_address, delivery_address, collection_contact, delivery_contact, proofs_of_delivery.

Body Parameters

service  integer optional  

The new service you would like to deliver the waybill on.

PrintLabel

requires authentication requires headers

Print waybill labels (only for customers who have a WebPrinter installed)

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/waybill/325/print_label/6',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/waybill/325/print_label/6"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/waybill/{waybill_collivery_id}/print_label/{printer?}?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

Example response (403):


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

Example response (400):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 40
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "error": {
        "http_code_text": "Bad Request",
        "http_code": 400,
        "message": "Invalid device, WebPrinter with id 6 does not belong to Demo Collivery (PTY) Ltd."
    }
}

Request   

GET v3/waybill/{waybill_collivery_id}/print_label/{printer?}

URL Parameters

waybill_collivery_id  integer  

The ID of the waybill collivery.

printer  string optional  

optional The printer id you want to print to. Can be obtained from /web_printer/ endpoint.

waybill  string  

The waybill id.

Query Parameters

api_token  string  

Authentication key.

6. Status Tracking

Fetch and query status updates for your waybills

Index

requires authentication requires 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' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
        'json' => [
            'statuses' => '1,3',
            'per_page' => 100,
            'start_date' => '2023-10-10',
            'end_date' => '2023-11-10',
            'page' => 1,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/status_tracking"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

let body = {
    "statuses": "1,3",
    "per_page": 100,
    "start_date": "2023-10-10",
    "end_date": "2023-11-10",
    "page": 1
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/status_tracking?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"statuses":"1,3","per_page":100,"start_date":"2023-10-10","end_date":"2023-11-10","page":1}'

Example response (200):


{
    "data": [
        {
            "status_id": 1,
            "status_name": "Waiting Client Acceptance",
            "waybill_id": 4105972,
            "created_at": "2019-08-12 06:02"
        },
        {
            "status_id": 3,
            "status_name": "Quote Accepted",
            "waybill_id": 4105972,
            "created_at": "2019-08-12 06:02"
        },
        {
            "status_id": 1,
            "status_name": "Waiting Client Acceptance",
            "waybill_id": 4105999,
            "created_at": "2019-08-12 06:03"
        }
    ],
    "links": {
        "first": "http://api.collivery.co.za/v3/status_tracking?page=1",
        "last": "http://api.collivery.co.za/v3/status_tracking?page=33",
        "prev": null,
        "next": "http://api.collivery.co.za/v3/status_tracking?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 33,
        "path": "http://api.collivery.co.za/v3/status_tracking",
        "per_page": "3",
        "to": 3,
        "total": 98
    }
}

Request   

GET v3/status_tracking

Query Parameters

api_token  string  

Authentication key.

Body Parameters

statuses  optional optional  

A comma-separated list of statuses to limit the results to. Defaults to all statuses.

per_page  integer  

The limit per page. Max is 50. If this option is provided, links and meta will exist in the response with further information about the full list.0 is the same as not limiting. Default is 100.

start_date  optional optional  

Any valid time representation that can be parsed by PHP strtotime(). Defaults to a week ago.

end_date  optional. optional  

page  integer  

page number to return. .

Show

requires authentication requires 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/325',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/status_tracking/325"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/status_tracking/{waybill_collivery_id}?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 43
access-control-allow-origin: *
x-robots-tag: noindex
 

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

Request   

GET v3/status_tracking/{waybill_collivery_id}

URL Parameters

waybill_collivery_id  integer  

The ID of the waybill collivery.

waybill  number  

The waybill id.

Query Parameters

api_token  string  

Authentication key.

Update

requires authentication requires headers

Accept or Cancel a waybill

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->put(
    'https://api.collivery.co.za/v3/status_tracking/325',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
        'json' => [
            'status_id' => 3.0,
            'cheapest' => true,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/status_tracking/325"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

let body = {
    "status_id": 3,
    "cheapest": true
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X PUT \
"https://api.collivery.co.za/v3/status_tracking/{waybill_collivery_id}?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"status_id":3,"cheapest":true}'

Example response (200):


{
    "data": {
        "message": "Waybill 4001907 updated to Quote Accepted"
    }
}

Example response (400):


{
 "error": {
   "http_code_text": "Bad Request",
   "http_code": 400,
   "message": "You have a prepaid account, you need to pay before accepting waybill # 4001907."
 }
 "meta": {
   "payment_needed": "https:\/\/collivery.net\/payment_requests\/store?waybills%5B0%5D=4001907"
 }
}

Example response (400):


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

Request   

PUT v3/status_tracking/{waybill_collivery_id}

PATCH v3/status_tracking/{waybill_collivery_id}

URL Parameters

waybill_collivery_id  integer  

The ID of the waybill collivery.

waybill  number  

The waybill id.

Query Parameters

api_token  string  

Authentication key.

Body Parameters

status_id  number  

The id of the status you want to update to. Must be 3 (Quote Accepted) or 5 (Cancelled).

cheapest  boolean optional  

Whether you would like the waybill to be accepted at the cheapest rate

7. Waybill Documents

Get your Quote or Waybill documents

Index

requires authentication requires headers

List your waybill documents

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

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/waybill_documents/{waybill}?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 38
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "data": [
        {
            "type": "waybill",
            "file_name": "4001907-waybill.pdf",
            "pages": 1,
            "mime": "application/pdf",
            "size": 27461,
            "created_at": "2024-10-23 07:50:03",
            "image_url": "https://api.collivery.co.za/v3/waybill_documents/4001907/waybill"
        },
        {
            "type": "quote",
            "file_name": "4001907-quote.pdf",
            "pages": 1,
            "mime": "application/pdf",
            "size": 23806,
            "created_at": "2024-10-23 07:50:03",
            "image_url": "https://api.collivery.co.za/v3/waybill_documents/4001907/quote"
        }
    ]
}

Request   

GET v3/waybill_documents/{waybill}

URL Parameters

waybill  number  

The waybill id you are requesting documents for.

Query Parameters

api_token  string  

Authentication key.

Show

requires authentication requires 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/waybill',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/waybill_documents/4001907/waybill"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/waybill_documents/{waybill}/{type}?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

Example response (200):


{
    "data": {
        "id": 4001907,
        "type": "waybill",
        "file_name": "4001907.pdf",
        "pages": 1,
        "mime": "application/pdf",
        "size": 2605,
        "created_at": "2019-05-29 18:41:11",
        "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"
    }
}

Request   

GET v3/waybill_documents/{waybill}/{type}

URL Parameters

waybill  number  

The waybill id you are requesting documents for.

type  string  

The type of document, 'waybill' or 'quote' or 'label'.

Query Parameters

api_token  string  

Authentication key.

8. Proofs of Delivery

Index

requires authentication requires headers

List your waybill proofs of delivery

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/proofs_of_delivery',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
            'page'=> '1',
            'per_page'=> '3',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/proofs_of_delivery"
);

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

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

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/proofs_of_delivery?api_token=OpSjx5TlXGCGkzGAvUOm&page=1&per_page=3" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 39
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "data": [
        {
            "id": 170452,
            "waybill_id": 342118,
            "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/proofs_of_delivery/170452"
        },
        {
            "id": 182535,
            "waybill_id": 356551,
            "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/proofs_of_delivery/182535"
        },
        {
            "id": 211515,
            "waybill_id": 390109,
            "type": "POD",
            "file_name": "390109.pdf",
            "pages": 1,
            "mime": "application/pdf",
            "size": 57001,
            "created_at": "2010-12-08 10:23:25",
            "image_url": "https://api.collivery.co.za/v3/proofs_of_delivery/211515"
        }
    ],
    "links": {
        "first": "https://api.collivery.co.za/v3/proofs_of_delivery?page=1",
        "last": "https://api.collivery.co.za/v3/proofs_of_delivery?page=194",
        "prev": null,
        "next": "https://api.collivery.co.za/v3/proofs_of_delivery?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 194,
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "active": false
            },
            {
                "url": "https://api.collivery.co.za/v3/proofs_of_delivery?page=1",
                "label": "1",
                "active": true
            },
            {
                "url": "https://api.collivery.co.za/v3/proofs_of_delivery?page=2",
                "label": "2",
                "active": false
            },
            {
                "url": "https://api.collivery.co.za/v3/proofs_of_delivery?page=3",
                "label": "3",
                "active": false
            },
            {
                "url": "https://api.collivery.co.za/v3/proofs_of_delivery?page=4",
                "label": "4",
                "active": false
            },
            {
                "url": "https://api.collivery.co.za/v3/proofs_of_delivery?page=5",
                "label": "5",
                "active": false
            },
            {
                "url": "https://api.collivery.co.za/v3/proofs_of_delivery?page=6",
                "label": "6",
                "active": false
            },
            {
                "url": "https://api.collivery.co.za/v3/proofs_of_delivery?page=7",
                "label": "7",
                "active": false
            },
            {
                "url": "https://api.collivery.co.za/v3/proofs_of_delivery?page=8",
                "label": "8",
                "active": false
            },
            {
                "url": "https://api.collivery.co.za/v3/proofs_of_delivery?page=9",
                "label": "9",
                "active": false
            },
            {
                "url": "https://api.collivery.co.za/v3/proofs_of_delivery?page=10",
                "label": "10",
                "active": false
            },
            {
                "url": null,
                "label": "...",
                "active": false
            },
            {
                "url": "https://api.collivery.co.za/v3/proofs_of_delivery?page=193",
                "label": "193",
                "active": false
            },
            {
                "url": "https://api.collivery.co.za/v3/proofs_of_delivery?page=194",
                "label": "194",
                "active": false
            },
            {
                "url": "https://api.collivery.co.za/v3/proofs_of_delivery?page=2",
                "label": "Next »",
                "active": false
            }
        ],
        "path": "https://api.collivery.co.za/v3/proofs_of_delivery",
        "per_page": 3,
        "to": 3,
        "total": 580
    }
}

Request   

GET v3/proofs_of_delivery

Query Parameters

api_token  string  

Authentication key.

waybill_id  string optional  

Limit to results with this waybill.

page  string optional  

Page number to return.

per_page  string 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.0 is the same as not limiting. Default is 100.

Show

requires authentication requires headers

Get the details and base64 encoded image of the waybill proof of delivery

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/proofs_of_delivery/211515',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/proofs_of_delivery/211515"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/proofs_of_delivery/{id}?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

Example response (200):


{
    "data": {
        "id": 211515,
        "type": "",
        "file_name": "4001907_POD.pdf",
        "pages": 1,
        "mime": "application/pdf",
        "size": 2605,
        "created_at": "2019-05-29 18:41:11",
        "image_url": "https://api.collivery.co.za/v3/proofs_of_delivery/211515",
        "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"
    }
}

Request   

GET v3/proofs_of_delivery/{id}

URL Parameters

id  number  

The proof of delivery id.

Query Parameters

api_token  string  

Authentication key.

9. Parcel Images

Index

requires authentication requires headers

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/parcel_images',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
            'page'=> '1',
            'per_page'=> '3',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/parcel_images"
);

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

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

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/parcel_images?api_token=OpSjx5TlXGCGkzGAvUOm&page=1&per_page=3" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

Example response (200):


{
    "data": [
        {
            "id": 2681479,
            "waybill_id": 3012330,
            "parcel_number": 1,
            "file_name": "3012330-1.jpeg",
            "mime_type": "image/jpeg",
            "size": 26287,
            "created_at": "2017-07-17 13:06:57",
            "image_url": "https://api.collivery.co.za/v3/parcel_images/2681479"
        },
        {
            "id": 2694043,
            "waybill_id": 3041631,
            "parcel_number": 1,
            "file_name": "3041631-1.jpeg",
            "mime_type": "image/jpeg",
            "size": 32399,
            "created_at": "2017-07-25 14:37:50",
            "image_url": "https://api.collivery.co.za/v3/parcel_images/2694043"
        },
        {
            "id": 2694087,
            "waybill_id": 3041631,
            "parcel_number": 2,
            "file_name": "3041631-2.jpeg",
            "mime_type": "image/jpeg",
            "size": 34726,
            "created_at": "2017-07-25 14:52:37",
            "image_url": "https://api.collivery.co.za/v3/parcel_images/2694087"
        }
    ],
    "links": {
        "first": "https://api.collivery.co.za/v3/parcel_images?page=1",
        "last": "https://api.collivery.co.za/v3/parcel_images?page=2",
        "next": "https://api.collivery.co.za/v3/parcel_images?page=2",
        "prev": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 2,
        "path": "https://api.collivery.co.za/v3/parcel_images",
        "per_page": "3",
        "to": 3,
        "total": 6
    }
}

Request   

GET v3/parcel_images

Query Parameters

api_token  string  

Authentication key.

waybill_id  string optional  

A waybill id that you would like to limit the parcel images to.

page  string optional  

Page number to return.

per_page  string 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.0 is the same as not limiting. Default is 100.

Show

requires authentication requires headers

Get the base64 encoded image

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/parcel_images/1',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/parcel_images/1"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/parcel_images/{id}?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

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"
    }
}

Request   

GET v3/parcel_images/{id}

URL Parameters

id  integer  

The ID of the parcel image.

parcel_image  number  

The parcel image id.

Query Parameters

api_token  string  

Authentication key.

10. Country

Show and search for countries

Index

requires authentication requires headers

Show all countries

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/country',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
            'page'=> '1',
            'per_page'=> '3',
        ],
        'json' => [
            'search' => 'south',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/country"
);

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

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

let body = {
    "search": "south"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/country?api_token=OpSjx5TlXGCGkzGAvUOm&page=1&per_page=3" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"search":"south"}'

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 33
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "data": [
        {
            "id": 195,
            "name": "South Africa",
            "country_code": "ZAF"
        },
        {
            "id": 243,
            "name": "South Sudan",
            "country_code": "SSD"
        }
    ],
    "links": {
        "first": "https://api.collivery.co.za/v3/country?page=1",
        "last": "https://api.collivery.co.za/v3/country?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "active": false
            },
            {
                "url": "https://api.collivery.co.za/v3/country?page=1",
                "label": "1",
                "active": true
            },
            {
                "url": null,
                "label": "Next »",
                "active": false
            }
        ],
        "path": "https://api.collivery.co.za/v3/country",
        "per_page": 3,
        "to": 2,
        "total": 2
    }
}

Request   

GET v3/country

Query Parameters

api_token  string  

Authentication key.

page  string optional  

Page number to return.

per_page  string 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.0 is the same as not limiting. Default is 300.

Body Parameters

search  required optional  

Must be at least 3 characters.

11. Towns

Show and search for Towns

Index

requires authentication requires 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' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
            'page'=> '1',
            'per_page'=> '3',
        ],
        'json' => [
            'country' => 'ZAF',
            'province' => 'Gauteng',
            'search' => 'Joh',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/towns"
);

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

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

let body = {
    "country": "ZAF",
    "province": "Gauteng",
    "search": "Joh"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/towns?api_token=OpSjx5TlXGCGkzGAvUOm&page=1&per_page=3" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"country":"ZAF","province":"Gauteng","search":"Joh"}'

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 58
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "data": [
        {
            "id": 147,
            "name": "Johannesburg",
            "other_name": "",
            "province": "GP",
            "latitude": -26.204103,
            "longitude": 28.047305,
            "category": "Major",
            "town_surcharge": 0
        },
        {
            "id": 13523,
            "name": "Johannesburg South",
            "other_name": "",
            "province": "GP",
            "latitude": -26.273866,
            "longitude": 27.995186,
            "category": "Major",
            "town_surcharge": 0
        },
        {
            "id": 14142,
            "name": "Whiteridge, Johannesburg",
            "other_name": "",
            "province": "GP",
            "latitude": -26.162219,
            "longitude": 27.950016,
            "category": "Major",
            "town_surcharge": 0
        }
    ],
    "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,
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "active": false
            },
            {
                "url": "https://api.collivery.co.za/v3/towns?page=1",
                "label": "1",
                "active": true
            },
            {
                "url": null,
                "label": "Next »",
                "active": false
            }
        ],
        "path": "https://api.collivery.co.za/v3/towns",
        "per_page": 3,
        "to": 3,
        "total": 3
    }
}

Request   

GET v3/towns

Query Parameters

api_token  string  

Authentication key.

page  string optional  

Page number to return.

per_page  string 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.0 is the same as not limiting. Default is 300.

Body Parameters

country  The optional  

three letter abbreviation (ISO 3166) for the country. Defaults to ZAF.

province  Filter optional  

by province name. Valid values are: Eastern Cape, Free State, Gauteng, KwaZulu Natal, Limpopo, Mpumalanga,Northern Cape, North West, Western Cape.

search  Search optional  

by town name.

12. Suburbs

Show and filter suburbs

Index

requires authentication requires 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' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
            'page'=> '1',
            'per_page'=> '3',
        ],
        'json' => [
            'town_id' => '147',
            'country' => 'ZAF',
            'latitude' => '-26.212500',
            'longitude' => '28.037500',
            'postal_code' => '2000',
            'postal_code_range' => '100',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/suburbs"
);

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

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

let body = {
    "town_id": "147",
    "country": "ZAF",
    "latitude": "-26.212500",
    "longitude": "28.037500",
    "postal_code": "2000",
    "postal_code_range": "100"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/suburbs?api_token=OpSjx5TlXGCGkzGAvUOm&page=1&per_page=3" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"town_id":"147","country":"ZAF","latitude":"-26.212500","longitude":"28.037500","postal_code":"2000","postal_code_range":"100"}'

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 57
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "data": [
        {
            "id": 1936,
            "name": "Selby",
            "latitude": -26.2125,
            "longitude": 28.0375,
            "town": {
                "id": 147,
                "name": "Johannesburg",
                "other_name": "",
                "province": "GP",
                "latitude": -26.204103,
                "longitude": 28.047305,
                "category": "Major",
                "town_surcharge": 0
            },
            "postal_code": "2001",
            "box_postal_code": null
        },
        {
            "id": 2214,
            "name": "Ussher",
            "latitude": -26.2125,
            "longitude": 28.0375,
            "town": {
                "id": 147,
                "name": "Johannesburg",
                "other_name": "",
                "province": "GP",
                "latitude": -26.204103,
                "longitude": 28.047305,
                "category": "Major",
                "town_surcharge": 0
            },
            "postal_code": "2001",
            "box_postal_code": null
        },
        {
            "id": 9160,
            "name": "South",
            "latitude": -26.215896,
            "longitude": 28.041925,
            "town": {
                "id": 147,
                "name": "Johannesburg",
                "other_name": "",
                "province": "GP",
                "latitude": -26.204103,
                "longitude": 28.047305,
                "category": "Major",
                "town_surcharge": 0
            },
            "postal_code": "2001",
            "box_postal_code": ""
        },
        {
            "id": 1901,
            "name": "Salisbury Claims",
            "latitude": -26.2125,
            "longitude": 28.045799,
            "town": {
                "id": 147,
                "name": "Johannesburg",
                "other_name": "",
                "province": "GP",
                "latitude": -26.204103,
                "longitude": 28.047305,
                "category": "Major",
                "town_surcharge": 0
            },
            "postal_code": "2001",
            "box_postal_code": null
        },
        {
            "id": 2324,
            "name": "Wemmer",
            "latitude": -26.2125,
            "longitude": 28.045799,
            "town": {
                "id": 147,
                "name": "Johannesburg",
                "other_name": "",
                "province": "GP",
                "latitude": -26.204103,
                "longitude": 28.047305,
                "category": "Major",
                "town_surcharge": 0
            },
            "postal_code": "2001",
            "box_postal_code": null
        }
    ]
}

Request   

GET v3/suburbs

Query Parameters

api_token  string  

Authentication key.

page  string optional  

Page number to return.

per_page  string 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.0 is the same as not limiting. Default is 2000.

Body Parameters

town_id  Required optional  

without country. Can be obtained from /towns/ endpoint.

country  Required optional  

without town_id. The three letter abbreviation (ISO 3166) for the country. Defaults to ZAF.

latitude  A optional  

latitude to search for the closest 5 suburbs. Required if longitude is provided.

longitude  A optional  

longitude to search for the closest 5 suburbs. Required if latitude is provided.

postal_code  A optional  

postal code to limit the result set to.

postal_code_range  The optional  

range within which to match the postal codes. For example the 2000 with a range of 100 matches postal codes 1900 to 2100. Defaults to 0 (ie. exact postal code match)

postal_code_type  The optional  

type of postal code to limit matches to. street or box are allowed. Defaults to a match on either.

search  Search optional  

by suburb name.

Show

requires authentication requires 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/-1',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/suburbs/-1"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/suburbs/{id}?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 56
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "data": {
        "id": 1936,
        "name": "Selby",
        "latitude": -26.2125,
        "longitude": 28.0375,
        "town": {
            "id": 147,
            "name": "Johannesburg",
            "other_name": "",
            "province": "GP",
            "latitude": -26.204103,
            "longitude": 28.047305,
            "category": "Major",
            "town_surcharge": 0
        },
        "postal_code": "2001",
        "box_postal_code": null
    }
}

Request   

GET v3/suburbs/{id}

URL Parameters

id  integer  

The ID of the suburb.

suburb  number  

The suburb id.

Query Parameters

api_token  string  

Authentication key.

Body Parameters

suburb  string optional  

requires authentication requires headers

Search by name for suburbs and/or town. Results are returned in order of most populated areas by default

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/town_suburb_search',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
        'json' => [
            'search_text' => 'westcli',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/town_suburb_search"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

let body = {
    "search_text": "westcli"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/town_suburb_search?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"search_text":"westcli"}'

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 55
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "data": [
        {
            "formatted_result": "Westcliff, Johannesburg, GP",
            "suburb": {
                "id": 2336,
                "name": "Westcliff",
                "latitude": -26.170799,
                "longitude": 28.0292,
                "town": {
                    "id": 147,
                    "name": "Johannesburg",
                    "other_name": "",
                    "province": "GP",
                    "latitude": -26.204103,
                    "longitude": 28.047305,
                    "category": "Major",
                    "town_surcharge": 0
                },
                "postal_code": "2193",
                "box_postal_code": "2193"
            }
        },
        {
            "formatted_result": "Westcliff, Chatsworth, KZN",
            "suburb": {
                "id": 3721,
                "name": "Westcliff",
                "latitude": -29.9125,
                "longitude": 30.887501,
                "town": {
                    "id": 13519,
                    "name": "Chatsworth",
                    "other_name": "",
                    "province": "KZN",
                    "latitude": -29.927024,
                    "longitude": 30.884343,
                    "category": "Major",
                    "town_surcharge": 0
                },
                "postal_code": "7200",
                "box_postal_code": "7200"
            }
        }
    ]
}

13. Service Types

Show all service types or searched

Index

requires authentication 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' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/service_types"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/service_types?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 46
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "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
        },
        {
            "id": 4,
            "code": "BLK",
            "text": "Bulk services",
            "description": "For large consignments. Delivery within 3 working days",
            "delivery_days": 3
        }
    ]
}

Request   

GET v3/service_types

Query Parameters

api_token  string  

Authentication key.

Show

requires authentication requires headers

Get specific service type by id

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/service_type/2',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/service_type/2"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/service_type/{id}?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 45
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "data": {
        "id": 2,
        "code": "ONX",
        "text": "Next Day",
        "description": "Will be delivered next day at times specified",
        "delivery_days": 1
    }
}

Request   

GET v3/service_type/{id}

URL Parameters

id  integer  

Query Parameters

api_token  string  

Authentication key.

14. Location Types

Index

requires authentication requires headers

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

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

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

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/location_types?api_token=OpSjx5TlXGCGkzGAvUOm&search=business" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 47
access-control-allow-origin: *
x-robots-tag: noindex
 

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

Request   

GET v3/location_types

Query Parameters

api_token  string  

Authentication key.

search  string optional  

An optional search string matched against the location types names.

surcharge_only  string optional  

{include, exclude} include will return only surchargeable location types, exclude will return only non-surchargeable location types.

15. Battery Types

Index Get all battery types.

requires authentication requires 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' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/battery_types"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/battery_types?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 51
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "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)"
        }
    ]
}

Request   

GET v3/battery_types

Query Parameters

api_token  string  

Authentication key.

16. Parcel Types

Index

requires authentication requires headers

Get all parcel 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/parcel_types',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/parcel_types"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/parcel_types?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 32
access-control-allow-origin: *
x-robots-tag: noindex
 

[
    {
        "id": 1,
        "type_text": "Envelope",
        "type_description": "Documents less than 2Kg and A4 size"
    },
    {
        "id": 2,
        "type_text": "Package",
        "type_description": "Parcel Exceeding 2Kg and any dimension above 20cm"
    },
    {
        "id": 3,
        "type_text": "Tender Document",
        "type_description": "Documents for lodging Tenders"
    }
]

Request   

GET v3/parcel_types

Query Parameters

api_token  string  

Authentication key.

17. Terms and Conditions

Index

requires authentication requires headers

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

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/terms_and_conditions?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 37
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "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."
            },
            {
                "key": "The Customer Acknowledges That",
                "value": [
                    {
                        "key": 1,
                        "value": "In terms of the Disaster Management Act 57 of 2002 (\"the Act\") and the current Alert Level Regulations thereof (\"the Regulations\"), MDS Collivery can only deliver the goods to the Customer in relation to goods and services as defined in the Regulations (\"the allowed purpose\")"
                    },
                    {
                        "key": 2,
                        "value": "MDS Collivery is delivering the goods to the Customer on the strict understanding the goods are purchased and will be used and/or on-sold by the Customer for the allowed purpose.  The Customer indemnifies and holds(MDS Collivery, its affiliates and their respective personnel harmless from and against any liability and losses arising from or in connection with the Customer's failure to purchase the goods in accordance with the provisions of the Act and the Regulations."
                    }
                ]
            }
        ],
        "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 or damage should be lodged within 7 days of loss by completing the on-line claim form on the customer interface. Any claim lodged after such date 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": "Valid Claims will only be paid by MDS in respect of any consignment after the Client has paid all outstanding Freight Charges in respect of that consignment and where the Client’s account with MDS has been paid in accordance with the credit terms extended."
            },
            {
                "key": 5,
                "value": "Freight charges relating to the consignment covered by the Risk Cover shall not be included in the calculation of any amount payable under the risk cover offered by MDS."
            },
            {
                "key": 6,
                "value": "Where a claim has been paid in full for goods damaged, MDS reserves the right to take possession of the goods as salvage and to dispose of such goods as it sees fit."
            },
            {
                "key": 7,
                "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": 8,
                "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": 9,
                "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": 10,
                "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": 11,
                "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": 12,
                "value": "Disputes and account queries must be made in writing to the accounts department within 7 (seven) days after receipt of invoice with specific details of the dispute or query."
            },
            {
                "key": 13,
                "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, motor vehicle panels and body parts including windscreens 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": 1605175290
}

Request   

GET v3/terms_and_conditions

Query Parameters

api_token  string  

Authentication key.

18. Vendors

Manage Vendors

Index

requires authentication requires headers

Show all vendors, or all vendors of a certain type

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/vendors',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
        'json' => [
            'vendor_type' => 'TAK_SUP',
            'vendor_id' => '123152',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/vendors"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

let body = {
    "vendor_type": "TAK_SUP",
    "vendor_id": "123152"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/vendors?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"vendor_type":"TAK_SUP","vendor_id":"123152"}'

Example response (200):


{
    "data": [
        {
            "id": 1770,
            "vendor_type": "TAK_SUP",
            "vendor_id": 32143451,
            "verified": false,
            "deleted": false
        },
        {
            "id": 1774,
            "vendor_type": "TAK_SUP",
            "vendor_id": 32143451,
            "verified": false,
            "deleted": false
        },
        {
            "id": 1775,
            "vendor_type": "TAK_SUP",
            "vendor_id": 32143451,
            "verified": false,
            "deleted": false
        },
        {
            "id": 1776,
            "vendor_type": "TAK_SUP",
            "vendor_id": 32143451,
            "verified": false,
            "deleted": false
        }
    ]
}

Request   

GET v3/vendors

Query Parameters

api_token  string  

Authentication key.

Body Parameters

vendor_type  string optional  

Must be one of TAK_SUP, TAK_SEL, or SUP_SUP.

waybill_id  string optional  

vendor_id  string optional  

optional The vendor id. Required if vendor_type TAK_SEL.

id  optional optional  

The waybill id.

Store

requires authentication requires headers

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://api.collivery.co.za/v3/vendors',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
        'json' => [
            'vendor_type' => 'TAK_SUP',
            'vendor_id' => '123152',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/vendors"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

let body = {
    "vendor_type": "TAK_SUP",
    "vendor_id": "123152"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X POST \
"https://api.collivery.co.za/v3/vendors?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"vendor_type":"TAK_SUP","vendor_id":"123152"}'

Example response (200):


{
    "data": [
        {
            "id": 1770,
            "vendor_type": "TAK_SUP",
            "vendor_id": 123152,
            "verified": false,
            "deleted": false
        }
    ]
}

Request   

POST v3/vendors

URL Parameters

id  string  

The vendor's ID.

Query Parameters

api_token  string  

Authentication key.

Body Parameters

vendor_type  string  

The vendor type SUP_SUP, TAK_SUP or TAK_SEL.

vendor_id  string optional  

optional The vendor id. Required if vendor_type TAK_SEL.

Update

requires authentication requires headers

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->put(
    'https://api.collivery.co.za/v3/vendors/123152',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
        'json' => [
            'vendor_type' => 'TAK_SUP',
            'vendor_id' => '123152',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/vendors/123152"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

let body = {
    "vendor_type": "TAK_SUP",
    "vendor_id": "123152"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X PUT \
"https://api.collivery.co.za/v3/vendors/{id}?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"vendor_type":"TAK_SUP","vendor_id":"123152"}'

Example response (200):


{
    "data": [
        {
            "id": 1770,
            "vendor_type": "TAK_SUP",
            "vendor_id": 123152,
            "verified": false,
            "deleted": false
        }
    ]
}

Request   

PUT v3/vendors/{id}

PATCH v3/vendors/{id}

URL Parameters

id  string  

The vendor's ID.

Query Parameters

api_token  string  

Authentication key.

Body Parameters

vendor_type  string  

The vendor type SUP_SUP, TAK_SUP or TAK_SEL.

vendor_id  string optional  

optional The vendor id. Required if vendor_type TAK_SEL.

Destroy

requires authentication requires headers

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->delete(
    'https://api.collivery.co.za/v3/vendors/3',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/vendors/3"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());
curl -X DELETE \
"https://api.collivery.co.za/v3/vendors/{id}?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

Example response (200):


{
    "data": [
        {
            "id": 1770,
            "vendor_type": "TAK_SUP",
            "vendor_id": 123152,
            "verified": false,
            "deleted": true
        }
    ]
}

Request   

DELETE v3/vendors/{id}

URL Parameters

id  integer  

The ID of the vendor.

vendor  number  

The vendor id.

Query Parameters

api_token  string  

Authentication key.

19. Vendor Reports

View

Index

requires authentication requires headers

List of Takealot waybills

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/vendor/reports',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
        'json' => [
            'per_page' => 18,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/vendor/reports"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

let body = {
    "per_page": 18
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/vendor/reports?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"per_page":18}'

Example response (200):


{
    "data": [
        {
            "waybill": 5518724,
            "purchase_orders": [
                {
                    "po": "12345678",
                    "asn": null,
                    "due_date": "2021-10-25",
                    "quantity": 1
                },
                {
                    "po": "12345679",
                    "asn": null,
                    "due_date": "2021-10-25",
                    "quantity": 2
                },
                {
                    "po": "12345673",
                    "asn": null,
                    "due_date": "2021-10-25",
                    "quantity": 1
                },
                {
                    "po": "12345674",
                    "asn": null,
                    "due_date": "2021-10-25",
                    "quantity": 2
                },
                {
                    "po": "12345672",
                    "asn": null,
                    "due_date": "2021-10-25",
                    "quantity": 1
                }
            ],
            "client": "Nuoli",
            "waybill_quantity": 7,
            "service": "Road Freight",
            "status": "Quote Accepted",
            "sla_status": "not delivered"
        }
    ],
    "meta": {
        "next_url": null,
        "previous_url": null,
        "pages": 0
    }
}

Request   

GET v3/vendor/reports

URL Parameters

dc  string optional  

The id of the DC. Takealot JNB (40) or Takealot JNB Bulk (39) or Takealot CPT (41) depot.

per_page  integer optional  

Number of waybills per page. Max is 50.

vendor  string optional  

MDS Vendor id. Can be obtained from /vendors/ endpoint.

status  string optional  

Status id. Can be obtained from /statuses/ endpoint.

po_number  integer optional  

Purchase order number.

asn  string optional  

ASN.

Query Parameters

api_token  string  

Authentication key.

Body Parameters

dc  string optional  

per_page  number optional  

Must not be greater than 50.

OnTime

requires authentication requires headers

On time report for Takealot Waybills

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/vendor/reports/on_time',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
        'json' => [
            'direction' => 'collection',
            'distribution_center' => 'DBN Main DC',
            'po_number_search' => 'ex',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/vendor/reports/on_time"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

let body = {
    "direction": "collection",
    "distribution_center": "DBN Main DC",
    "po_number_search": "ex"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/vendor/reports/on_time?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"direction":"collection","distribution_center":"DBN Main DC","po_number_search":"ex"}'

Example response (200):


{
    "data": [
        {
            "waybill": 5674754,
            "status": "Invoiced",
            "po": "12345678",
            "asn": "1",
            "client": "Acme Trading (Pty) Ltd",
            "quantity": 1,
            "service": "Road Freight",
            "due_date": "2022-01-06",
            "collection_time": "2022-01-05 09:00:00",
            "collected_at": "2022-01-05 13:44:58",
            "deliver_before": "2022-01-6 14:00:00",
            "days_late": 2
        }
    ],
    "meta": {
        "summary": {
            "total_failures": 0,
            "total": 1,
            "percentage": 0
        }
    }
}

Request   

GET v3/vendor/reports/on_time

URL Parameters

start_date  string optional  

The date of the start of the report.

end_date  string optional  

The date of the end of the report.

direction  string optional  

Direction. Collect from client (collection), Deliver to client (delivery), or Collection and Delivery (both) .

distribution_center  string optional  

The id of the DC. Takealot JNB (JNB) or Takealot JNB Bulk (JNB_BULK) or Takealot CPT (CPT) depot.

po_number_search  integer optional  

Comma seperated Purchase order numbers to search.

Query Parameters

api_token  string  

Authentication key.

Body Parameters

start_date  string optional  

end_date  string optional  

direction  string optional  

Must be one of collection, delivery, or both.

distribution_center  string optional  

Must be one of JHB Bulk DC3, CPT Main DC, JHB Main DC, CPT Bulk DC2, or DBN Main DC.

po_number_search  string optional  

InFull

requires authentication requires headers

In full report for Takealot Waybills

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/vendor/reports/in_full',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
        'json' => [
            'direction' => 'collection',
            'distribution_center' => 'DBN Main DC',
            'po_number_search' => 'ex',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/vendor/reports/in_full"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

let body = {
    "direction": "collection",
    "distribution_center": "DBN Main DC",
    "po_number_search": "ex"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/vendor/reports/in_full?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"direction":"collection","distribution_center":"DBN Main DC","po_number_search":"ex"}'

Example response (200):


{
    "data": [
        {
            "waybill": 5504810,
            "status": "Invoiced",
            "po": "34456899",
            "asn": null,
            "client": "Acme Trading  Pty Ltd",
            "quantity": 2,
            "service": "Road Freight",
            "quantity_at_dest": 0
        },
        {
            "waybill": 5504810,
            "status": "Invoiced",
            "po": "123789",
            "asn": null,
            "client": "Acme Trading Pty Ltd",
            "quantity": 2,
            "service": "Road Freight",
            "quantity_at_dest": 0
        },
        {
            "waybill": 5504810,
            "status": "Invoiced",
            "po": "23456789",
            "asn": null,
            "client": "Acme Trading Pty Ltd",
            "quantity": 2,
            "service": "Road Freight",
            "quantity_at_dest": 0
        }
    ],
    "meta": {
        "summary": {
            "failures": 3,
            "total": 137961,
            "percentage": 0
        }
    }
}

Request   

GET v3/vendor/reports/in_full

URL Parameters

start_date  string optional  

The date of the start of the report.

end_date  string optional  

The date of the end of the report.

direction  string optional  

Direction. Collect from client (collection), Deliver to client (delivery), or Collection and Delivery (both) .

distribution_center  string optional  

The id of the DC. Takealot JNB (JNB) or Takealot JNB Bulk (JNB_BULK) or Takealot CPT (CPT) depot.

po_number_search  integer optional  

Comma seperated Purchase order numbers to search.

Query Parameters

api_token  string  

Authentication key.

Body Parameters

start_date  string optional  

end_date  string optional  

direction  string optional  

Must be one of collection, delivery, or both.

distribution_center  string optional  

Must be one of JHB Bulk DC3, CPT Main DC, JHB Main DC, CPT Bulk DC2, or DBN Main DC.

po_number_search  string optional  

LostOrDamaged

requires authentication requires headers

Lost or damaged report for Takealot Waybills including claim status

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/vendor/reports/lost_or_damaged',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
        'json' => [
            'direction' => 'collection',
            'distribution_center' => 'DBN Main DC',
            'po_number_search' => 'ex',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/vendor/reports/lost_or_damaged"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

let body = {
    "direction": "collection",
    "distribution_center": "DBN Main DC",
    "po_number_search": "ex"
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/vendor/reports/lost_or_damaged?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"direction":"collection","distribution_center":"DBN Main DC","po_number_search":"ex"}'

Example response (200):


{
    "data": [
        {
            "waybill": 4899591,
            "status": "Invoiced",
            "po": "12312351",
            "asn": "ASNCQWERT036712920",
            "client": "Acme Trading Pty Ltd",
            "quantity": 2,
            "service": "Road Freight",
            "claim_approved": false,
            "claim_value_rands": 400,
            "claim_status": "Denied",
            "claim_reason": "Dear Acme, it appears the item was not packaged in line with TakeAlot packaging standards. Unfortunately we are unable to assist with the claim"
        },
        {
            "waybill": 4909021,
            "status": "Invoiced",
            "po": "3622220",
            "asn": null,
            "client": "Acme Trading Pty Ltd",
            "quantity": 2,
            "service": "Road Freight",
            "claim_approved": true,
            "claim_value_rands": 3995,
            "claim_status": "Completed",
            "claim_reason": "Dear Acme, thank you for submitted your claim. After review of the photographic evidence your claim has been approved. Please supply invoice for cost"
        }
    ],
    "meta": {
        "summary": {
            "claims_total": 2,
            "accepted_total": 1,
            "rejected_total": 1,
            "total": 2590,
            "percentage": 0.04
        }
    }
}

Request   

GET v3/vendor/reports/lost_or_damaged

URL Parameters

start_date  string optional  

The date of the start of the report.

end_date  string optional  

The date of the end of the report.

direction  string optional  

Direction. Collect from client (collection), Deliver to client (delivery), or Collection and Delivery (both) .

distribution_center  string optional  

The id of the DC. Takealot JNB (JNB) or Takealot JNB Bulk (JNB_BULK) or Takealot CPT (CPT) depot.

po_number_search  integer optional  

Comma seperated Purchase order numbers to search.

Query Parameters

api_token  string  

Authentication key.

Body Parameters

start_date  string optional  

end_date  string optional  

direction  string optional  

Must be one of collection, delivery, or both.

distribution_center  string optional  

Must be one of JHB Bulk DC3, CPT Main DC, JHB Main DC, CPT Bulk DC2, or DBN Main DC.

po_number_search  string optional  

20. Vendor Waybills

Add Vendor Waybill bookings

Store

requires authentication requires headers

Create a new vendor waybill

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://api.collivery.co.za/v3/vendor_bookings',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
        'json' => [
            'vendor_depot' => 'JHB Bulk DC3',
            'vehicle_type' => 2,
            'risk_cover' => true,
            'collection_time' => '2025-01-24',
            'orders' => [
                [
                    'purchase_order_number' => 'ex',
                    'parcel_count' => 2,
                    'vendor_id' => 1772,
                    'due_date' => '2012-02-25',
                    'asn' => 'ex',
                    'length' => 21.5,
                    'width' => 10.0,
                    'height' => 5.5,
                    'weight' => 5.5,
                ],
            ],
            'delivery_address' => '952',
            'service_type' => 3,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/vendor_bookings"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

let body = {
    "vendor_depot": "JHB Bulk DC3",
    "vehicle_type": 2,
    "risk_cover": true,
    "collection_time": "2025-01-24",
    "orders": [
        {
            "purchase_order_number": "ex",
            "parcel_count": 2,
            "vendor_id": 1772,
            "due_date": "2012-02-25",
            "asn": "ex",
            "length": 21.5,
            "width": 10,
            "height": 5.5,
            "weight": 5.5
        }
    ],
    "delivery_address": "952",
    "service_type": 3
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X POST \
"https://api.collivery.co.za/v3/vendor_bookings?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"vendor_depot":"JHB Bulk DC3","vehicle_type":2,"risk_cover":true,"collection_time":"2025-01-24","orders":[{"purchase_order_number":"ex","parcel_count":2,"vendor_id":1772,"due_date":"2012-02-25","asn":"ex","length":21.5,"width":10,"height":5.5,"weight":5.5}],"delivery_address":"952","service_type":3}'

Example response (201):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 36
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "data": {
        "id": 7742290,
        "custom_id": "",
        "service_type_id": 3,
        "service_type_name": "Road Freight",
        "collection_time": 1737698400,
        "collected_at": null,
        "customer_reference": "",
        "delivery_time": 1738159200,
        "delivered_at": null,
        "parcel_count": 2,
        "special_instructions": "Takealot : ex",
        "collection_address_id": 39,
        "collection_contact_id": 3732661,
        "delivery_address_id": 952,
        "delivery_contact_id": 593,
        "status_id": 1,
        "status_name": "Waiting Client Acceptance",
        "parcel_description": "",
        "weight": 11,
        "volumetric_weight": 0.6,
        "total_price": 324.2,
        "risk_cover": true,
        "client": {
            "id": 116,
            "name": "Demo Collivery (PTY) Ltd.",
            "landline_number": "011 241 4911",
            "mobile_number": null,
            "account_code": "TESTCOLLIVER",
            "account_type": "account"
        },
        "collection_address": {
            "id": 39,
            "address_id": 39,
            "custom_id": "",
            "town_id": 154,
            "town_name": "Kempton Park",
            "town_other_name": "",
            "suburb_id": 769,
            "suburb_name": "Glen Marais",
            "company_name": "takealot.com Johannesburg",
            "building_complex_name": "JT Ross Park",
            "street_number": "",
            "street_name": "5 Merlot Close",
            "postal_code": "1619",
            "country_name": "SOUTH AFRICA",
            "text": "takealot.com Johannesburg, JT Ross Park, 5 Merlot Close, Glen Marais, Kempton Park",
            "short_text": "takealot.com Johannesburg, Glen Marais, Kempton Park",
            "location_type": {
                "id": 1,
                "name": "Business Premises",
                "surcharge": false,
                "surcharge_amount": 0
            },
            "town": {
                "id": 154,
                "name": "Kempton Park",
                "other_name": "",
                "province": "GP",
                "latitude": -26.0937,
                "longitude": 28.231001,
                "category": "Major",
                "town_surcharge": 0
            },
            "geocode_data": {
                "accuracy": 6,
                "accuracy_type": "Street",
                "last_geocoded_at": "2022-11-04",
                "latitude": -26.069174,
                "longitude": 28.278063
            }
        },
        "parcels": []
    },
    "meta": [
        "The earliest collect after time is 8:00. Collection time has been adjusted."
    ]
}

Request   

POST v3/vendor_bookings

Query Parameters

api_token  string  

Authentication key.

Body Parameters

vendor_depot  string  

JNB Main (JHB Main DC), CPT Main (CPT Main DC), JNB Bulk (JHB Bulk DC3), CPT Bulk (CPT Bulk DC2) .

vehicle_type  integer  

The vehicle that we should collect it with. Defaults to 1 (Motorbike).

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.

collection_time  string  

Any future date/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.

orders  object[] optional  

Purchase orders.

orders[].purchase_order_number  string  

The Purchase order number. Example 165488742

orders[].parcel_count  integer  

The amount of parcels of this type.

orders[].vendor_id  integer  

The id of the vendor stored with Collivery.

orders[].due_date  date  

The date the order is due at Vendor depot.

orders[].asn  string optional  

optional The ASN of order. Example TAL_12341

orders[].length  number optional  

optional The length of the parcel. Values in centimetres. Can be supplied as floats or integers.

orders[].width  number optional  

optional The width of the parcel. Values in centimetres. Can be supplied as floats or integers.

orders[].height  number optional  

optional The height of the parcel. Values in centimetres. Can be supplied as floats or integers.

orders[].weight  number optional  

optional The weight of the parcel. Values in kilograms. Can be supplied as floats or integers.

collection_address  integer/object optional  

optional Required if delivery_address not supplied, can be the id of the address or a json object if the address is not yet stored. See below for object structure.

collection_address.custom_id  string optional  

The custom id you would like to assign to this address. Must be unique. Max 20 characters.

collection_address.town_id  integer optional  

Required without town_name and suburb_id. Can be obtained from /towns/ endpoint.

collection_address.town_name  string optional  

Required without town_idand suburb_id. Can be obtained from /towns/ endpoint.

collection_address.suburb_id  integer optional  

Required without suburb_name. Can be obtained from /suburbs/ endpoint.

collection_address.suburb_name  string optional  

Required without suburb_id. Can be obtained from /suburbs/ endpoint.

collection_address.company_name  string optional  

The name of the company of the address. Max 50 characters.

collection_address.building  string optional  

The building of the address. Max 50 characters.

collection_address.street_number  string optional  

The number on the street of the address. Max 5 characters.

collection_address.street  string optional  

optional Required if the address is filled. The name of the street that the address is on. Max 50 characters.

collection_address.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.

collection_address.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.

collection_address.contact  object optional  

optional If you are creating a contact with the address, please ensure that it is a valid JSON object.

collection_address.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.

collection_address.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.

collection_address.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.

collection_address.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.

delivery_address  integer/object optional  

optional Required if collection_address not supplied, can be the id of the address or a json object if the address is not yet stored. See below for object structure.

delivery_address.custom_id  string optional  

The custom id you would like to assign to this address. Must be unique. Max 20 characters.

delivery_address.town_id  integer optional  

Required without town_name and suburb_id. Can be obtained from /towns/ endpoint.

delivery_address.town_name  string optional  

Required without town_id and suburb_id. Can be obtained from /towns/ endpoint.

delivery_address.suburb_id  integer optional  

Required without suburb_name. Can be obtained from /suburbs/ endpoint.

delivery_address.suburb_name  string optional  

Required without suburb_id. Can be obtained from /suburbs/ endpoint.

delivery_address.company_name  string optional  

The name of the company of the address. Max 50 characters.

delivery_address.building  string optional  

The building of the address. Max 50 characters.

delivery_address.street_number  string optional  

The number on the street of the address. Max 5 characters.

delivery_address.street  string optional  

optional Required if the address is filled. The name of the street that the address is on. Max 50 characters.

delivery_address.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.

delivery_address.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.

delivery_address.contact  object optional  

optional If you are creating a contact with the address, please ensure that it is a valid JSON object.

delivery_address.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.

delivery_address.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.

delivery_address.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.

delivery_address.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.

service_type  integer  

A service you would like to deliver the waybill on. Defaults to 2 (Overnight Express).

Quote

requires authentication requires headers

Quote on a vendor waybill

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://api.collivery.co.za/v3/vendor_bookings/quote',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
        'json' => [
            'vendor_depot' => 'JHB Bulk DC3',
            'vehicle_type' => 2,
            'risk_cover' => true,
            'collection_time' => '2025-01-24',
            'orders' => [
                [
                    'purchase_order_number' => 'ex',
                    'parcel_count' => 2,
                    'vendor_id' => 1772,
                    'due_date' => '2012-02-25',
                    'asn' => 'ex',
                    'length' => 21.5,
                    'width' => 10.0,
                    'height' => 5.5,
                    'weight' => 5.5,
                ],
            ],
            'delivery_address' => '952',
            'service_types' => [
                2,
                5,
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/vendor_bookings/quote"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

let body = {
    "vendor_depot": "JHB Bulk DC3",
    "vehicle_type": 2,
    "risk_cover": true,
    "collection_time": "2025-01-24",
    "orders": [
        {
            "purchase_order_number": "ex",
            "parcel_count": 2,
            "vendor_id": 1772,
            "due_date": "2012-02-25",
            "asn": "ex",
            "length": 21.5,
            "width": 10,
            "height": 5.5,
            "weight": 5.5
        }
    ],
    "delivery_address": "952",
    "service_types": [
        2,
        5
    ]
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X POST \
"https://api.collivery.co.za/v3/vendor_bookings/quote?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"vendor_depot":"JHB Bulk DC3","vehicle_type":2,"risk_cover":true,"collection_time":"2025-01-24","orders":[{"purchase_order_number":"ex","parcel_count":2,"vendor_id":1772,"due_date":"2012-02-25","asn":"ex","length":21.5,"width":10,"height":5.5,"weight":5.5}],"delivery_address":"952","service_types":[2,5]}'

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 35
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "data": [
        {
            "service_type": 2,
            "total": 293,
            "total_inclusive": 336.95,
            "delivery_type": "local"
        },
        {
            "service_type": 5,
            "total": 302.8,
            "total_inclusive": 348.22,
            "delivery_type": "local"
        }
    ],
    "meta": {
        "times": {
            "2": {
                "collection_time": "2025-01-24T06:00:00.000000Z",
                "delivery_time": "2025-01-27T14:00:00.000000Z"
            },
            "5": {
                "collection_time": "2025-01-24T06:00:00.000000Z",
                "delivery_time": "2025-01-28T14:00:00.000000Z"
            }
        },
        "warnings": {
            "2": "The earliest collect after time is 8:00. Collection time has been adjusted.",
            "5": "The earliest collect after time is 8:00. Collection time has been adjusted."
        },
        "surcharges": {
            "2": {
                "riskCover": 95.67
            },
            "5": {
                "riskCover": 95.67
            }
        },
        "extras": {
            "2": {
                "inc_weight": 15,
                "vol_weight": 0.6,
                "vm_divisor": 5000,
                "weight": 11,
                "rate_per_kg": 1.92
            },
            "5": {
                "inc_weight": 20,
                "vol_weight": 0.6,
                "vm_divisor": 4500,
                "weight": 11,
                "rate_per_kg": 0.88
            }
        }
    }
}

Request   

POST v3/vendor_bookings/quote

Query Parameters

api_token  string  

Authentication key.

Body Parameters

vendor_depot  string  

JNB Main (JHB Main DC), CPT Main (CPT Main DC), JNB Bulk (JHB Bulk DC3), CPT Bulk (CPT Bulk DC2) .

vehicle_type  integer  

The vehicle that we should collect it with. Defaults to 1 (Motorbike).

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.

collection_time  string  

Any future date/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.

orders  object[] optional  

Purchase orders.

orders[].purchase_order_number  string  

The Purchase order number. Example 165488742

orders[].parcel_count  integer  

The amount of parcels of this type.

orders[].vendor_id  integer  

The id of the vendor stored with Collivery.

orders[].due_date  date  

The date the order is due at Vendor depot.

orders[].asn  string optional  

optional The ASN of order. Example TAL_12341

orders[].length  number optional  

optional The length of the parcel. Values in centimetres. Can be supplied as floats or integers.

orders[].width  number optional  

optional The width of the parcel. Values in centimetres. Can be supplied as floats or integers.

orders[].height  number optional  

optional The height of the parcel. Values in centimetres. Can be supplied as floats or integers.

orders[].weight  number optional  

optional The weight of the parcel. Values in kilograms. Can be supplied as floats or integers.

collection_address  integer/object optional  

optional Required if delivery_address not supplied, can be the id of the address or a json object if the address is not yet stored. See below for object structure.

collection_address.custom_id  string optional  

The custom id you would like to assign to this address. Must be unique. Max 20 characters.

collection_address.town_id  integer optional  

Required without town_name and suburb_id. Can be obtained from /towns/ endpoint.

collection_address.town_name  string optional  

Required without town_idand suburb_id. Can be obtained from /towns/ endpoint.

collection_address.suburb_id  integer optional  

Required without suburb_name. Can be obtained from /suburbs/ endpoint.

collection_address.suburb_name  string optional  

Required without suburb_id. Can be obtained from /suburbs/ endpoint.

collection_address.company_name  string optional  

The name of the company of the address. Max 50 characters.

collection_address.building  string optional  

The building of the address. Max 50 characters.

collection_address.street_number  string optional  

The number on the street of the address. Max 5 characters.

collection_address.street  string optional  

optional Required if the address is filled. The name of the street that the address is on. Max 50 characters.

collection_address.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.

collection_address.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.

collection_address.contact  object optional  

optional If you are creating a contact with the address, please ensure that it is a valid JSON object.

collection_address.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.

collection_address.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.

collection_address.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.

collection_address.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.

delivery_address  integer/object optional  

optional Required if collection_address not supplied, can be the id of the address or a json object if the address is not yet stored. See below for object structure.

delivery_address.custom_id  string optional  

The custom id you would like to assign to this address. Must be unique. Max 20 characters.

delivery_address.town_id  integer optional  

Required without town_name and suburb_id. Can be obtained from /towns/ endpoint.

delivery_address.town_name  string optional  

Required without town_id and suburb_id. Can be obtained from /towns/ endpoint.

delivery_address.suburb_id  integer optional  

Required without suburb_name. Can be obtained from /suburbs/ endpoint.

delivery_address.suburb_name  string optional  

Required without suburb_id. Can be obtained from /suburbs/ endpoint.

delivery_address.company_name  string optional  

The name of the company of the address. Max 50 characters.

delivery_address.building  string optional  

The building of the address. Max 50 characters.

delivery_address.street_number  string optional  

The number on the street of the address. Max 5 characters.

delivery_address.street  string optional  

optional Required if the address is filled. The name of the street that the address is on. Max 50 characters.

delivery_address.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.

delivery_address.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.

delivery_address.contact  object optional  

optional If you are creating a contact with the address, please ensure that it is a valid JSON object.

delivery_address.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.

delivery_address.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.

delivery_address.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.

delivery_address.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.

service_types  object[] optional  

number A list of the services you would like a quote on. Any or none of 2,3,5. Defaults to all services.

21. Statuses

View Statuses

Index

requires authentication requires headers

List all in use statuses

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/statuses',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/statuses"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/statuses?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 34
access-control-allow-origin: *
x-robots-tag: noindex
 

[
    {
        "id": 1,
        "name": "Waiting Client Acceptance"
    },
    {
        "id": 2,
        "name": "Waiting Payment"
    },
    {
        "id": 3,
        "name": "Quote Accepted"
    },
    {
        "id": 5,
        "name": "Collivery Cancelled"
    },
    {
        "id": 6,
        "name": "Invoiced"
    },
    {
        "id": 7,
        "name": "Collected"
    },
    {
        "id": 8,
        "name": "Delivered"
    },
    {
        "id": 9,
        "name": "In Transit"
    },
    {
        "id": 10,
        "name": "Collection Driver Dispatched"
    },
    {
        "id": 11,
        "name": "Collection Failed"
    },
    {
        "id": 12,
        "name": "Delivery Failed"
    },
    {
        "id": 13,
        "name": "Processing Order"
    },
    {
        "id": 14,
        "name": "Received By Branch"
    },
    {
        "id": 15,
        "name": "Delivery Driver Dispatched"
    },
    {
        "id": 16,
        "name": "Collection Courier Allocated"
    },
    {
        "id": 17,
        "name": "Delivery Courier Allocated"
    },
    {
        "id": 18,
        "name": "Collection Driver Allocated"
    },
    {
        "id": 19,
        "name": "Delivery Driver Allocated"
    },
    {
        "id": 20,
        "name": "POD Received"
    },
    {
        "id": 21,
        "name": "Received By Courier"
    },
    {
        "id": 22,
        "name": "Collivery Modified"
    },
    {
        "id": 27,
        "name": "On Hold"
    },
    {
        "id": 29,
        "name": "Pending Investigation"
    },
    {
        "id": 30,
        "name": "Collection Courier Dispatched"
    },
    {
        "id": 31,
        "name": "Delivery Courier Dispatched"
    },
    {
        "id": 32,
        "name": "Completed"
    },
    {
        "id": 33,
        "name": "Accounting transferred"
    },
    {
        "id": 34,
        "name": "Unhold"
    }
]

Request   

GET v3/statuses

Query Parameters

api_token  string  

Authentication key.

22. WebPrinter

Get your Printers Available and execute jobs

Index

requires authentication requires headers

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/web_printer',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/web_printer"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/web_printer?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

Example response (400):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 31
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "error": {
        "http_code_text": "Bad Request",
        "http_code": 400,
        "message": "You have no WebPrinters linked to your account please contact support@collivery.co.za"
    }
}

Request   

GET v3/web_printer

Query Parameters

api_token  string  

Authentication key.

23. Predefined Parcels

Manage Predefined Parcels

Index

requires authentication requires headers

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/predefined_parcels',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
            'search'=> 'pizza',
            'page'=> '1',
            'per_page'=> '3',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/predefined_parcels"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
    "search": "pizza",
    "page": "1",
    "per_page": "3",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/predefined_parcels?api_token=OpSjx5TlXGCGkzGAvUOm&search=pizza&page=1&per_page=3" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

Example response (200):


{
   "data": [
     {
       'product_id': 1,
       'client_id': 1,
       'description': 'Small Pizza Box',
       'length': 20,
       'width': 20,
       'height': 20,
       'weight': 1,
       'deleted': false
     },
     {
       'product_id': 2,
       'client_id': 1,
       'description': 'Medium Pizza Box',
       'length': 30,
       'width': 30,
       'height': 30,
       'weight': 2,
       'deleted': false
     }
   ],
   "links": {
     'first': 'http://collivery.net/api/external/predefined-parcels?page=1',
     'last': 'http://collivery.net/api/external/predefined-parcels?page=1',
     'prev': null,
     'next': null
   },
   "meta": {
     'current_page': 1,
     'from': 1,
     'last_page': 1,
     'path': 'http://collivery.net/api/external/predefined-parcels',
     'per_page': 100,
     'to': 2,
     'total': 2
   }
 }

Request   

GET v3/predefined_parcels

Query Parameters

api_token  string  

Authentication key.

search  string optional  

An optional search string matched against the location types names.

page  string optional  

Page number to return.

per_page  string 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.0 is the same as not limiting. Default is 100.

Store

requires authentication requires headers

Save a new Predefined Parcel.

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->post(
    'https://api.collivery.co.za/v3/predefined_parcels',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
        'json' => [
            'length' => 21.5,
            'width' => 10.0,
            'height' => 5.5,
            'weight' => 5.2,
            'description' => 'Pizza box',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/predefined_parcels"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

let body = {
    "length": 21.5,
    "width": 10,
    "height": 5.5,
    "weight": 5.2,
    "description": "Pizza box"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X POST \
"https://api.collivery.co.za/v3/predefined_parcels?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"length":21.5,"width":10,"height":5.5,"weight":5.2,"description":"Pizza box"}'

Example response (201):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 30
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "id": 18729,
    "length": 21.5,
    "width": 10,
    "height": 5.5,
    "weight": 5.2,
    "description": "Pizza box"
}

Request   

POST v3/predefined_parcels

Query Parameters

api_token  string  

Authentication key.

Body Parameters

length  number  

The length of the parcel. Values in centimetres. Can be supplied as floats or integers.

width  number  

The width of the parcel. Values in centimetres. Can be supplied as floats or integers.

height  number  

The height of the parcel. Values in centimetres. Can be supplied as floats or integers.

weight  number  

The weight of the parcel. Values in kilograms. Can be supplied as floats or integers.

description  string  

The description of the box/parcel. Max 50 characters.

Show

requires authentication requires headers

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/predefined_parcels/13900',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/predefined_parcels/13900"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());
curl -X GET \
-G "https://api.collivery.co.za/v3/predefined_parcels/{id}?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com"

Example response (404):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 29
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "message": "Predefined Parcel for id 1 not found"
}

Request   

GET v3/predefined_parcels/{id}

URL Parameters

id  integer optional  

required.

Query Parameters

api_token  string  

Authentication key.

Update

requires authentication requires headers

Example request:
$client = new \GuzzleHttp\Client();
$response = $client->put(
    'https://api.collivery.co.za/v3/predefined_parcels/13900',
    [
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json',
            'X-App-Name' => 'My Custom App',
            'X-App-Version' => '0.2.1',
            'X-App-Host' => '.NET Framework 4.8',
            'X-App-Lang' => 'C#',
            'X-App-Url' => 'https://example.com',
        ],
        'query' => [
            'api_token'=> 'OpSjx5TlXGCGkzGAvUOm',
        ],
        'json' => [
            'length' => 21.5,
            'width' => 10.0,
            'height' => 5.5,
            'weight' => 5.2,
            'description' => 'Pizza box',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/predefined_parcels/13900"
);

const params = {
    "api_token": "OpSjx5TlXGCGkzGAvUOm",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

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

let body = {
    "length": 21.5,
    "width": 10,
    "height": 5.5,
    "weight": 5.2,
    "description": "Pizza box"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());
curl -X PUT \
"https://api.collivery.co.za/v3/predefined_parcels/{id}?api_token=OpSjx5TlXGCGkzGAvUOm" \
  -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -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 "X-App-Url: https://example.com" \
    -d '{"length":21.5,"width":10,"height":5.5,"weight":5.2,"description":"Pizza box"}'

Example response (404):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 60
x-ratelimit-remaining: 28
access-control-allow-origin: *
x-robots-tag: noindex
 

{
    "message": "Predefined Parcel for id 1 not found"
}

Request   

PUT v3/predefined_parcels/{id}

PATCH v3/predefined_parcels/{id}

URL Parameters

id  string  

The id

Query Parameters

api_token  string  

Authentication key.

Body Parameters

length  number  

The length of the parcel. Values in centimetres. Can be supplied as floats or integers.

width  number  

The width of the parcel. Values in centimetres. Can be supplied as floats or integers.

height  number  

The height of the parcel. Values in centimetres. Can be supplied as floats or integers.

weight  number  

The weight of the parcel. Values in kilograms. Can be supplied as floats or integers.

description  string  

The description of the box/parcel. Max 50 characters.