NAV
php javascript bash

Info

Welcome to the V3 Collivery.net API reference.

Please refer to the documentation of our older api Learn more

Headers

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


Customise this page's example headers


We offer a json collection for you to import into PostMan while testing.
Get Postman Collection

1. Authentication

Please note:

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"
);

let 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: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(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 (503):

{
    "message": ""
}

HTTP Request

POST v3/login

Body Parameters

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

Register

Create a new client account

Requires headers

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',
        ],
        'json' => [
            'name' => 'John Doe',
            'terms' => '1',
            'email_address' => 'foobar@example.com',
            'cellphone' => 123456789.0,
            'town_id' => '147',
            'suburb_id' => '1936',
            'street_name' => 'Webber Street',
            'street_number' => '58c',
            'building' => 'MDS House',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/register"
);

let headers = {
    "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": "1",
    "email_address": "foobar@example.com",
    "cellphone": 123456789,
    "town_id": "147",
    "suburb_id": "1936",
    "street_name": "Webber Street",
    "street_number": "58c",
    "building": "MDS House"
}

fetch(url, {
    method: "POST",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X POST \
    "https://api.collivery.co.za/v3/register" \
    -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":"1","email_address":"foobar@example.com","cellphone":123456789,"town_id":"147","suburb_id":"1936","street_name":"Webber Street","street_number":"58c","building":"MDS House"}'

Example response (200):

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

Example response (412):

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

HTTP Request

POST v3/register

Body Parameters

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

2. Addresses

Manage Addresses

Index

List your addresses

Requires authentication Requires headers

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' => [
            'per_page'=> '3',
            'search'=> 'Johannes',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/address"
);

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

let headers = {
    "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: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET \
    -G "https://api.collivery.co.za/v3/address?per_page=3&search=Johannes" \
    -H "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 (503):

{
    "message": ""
}

HTTP Request

GET v3/address

Query Parameters

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

Store

Save a new Address.

Requires authentication Requires headers

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',
        ],
        'json' => [
            'town_id' => 147,
            'town_name' => 'Johannesburg',
            'suburb_id' => 1936,
            'suburb_name' => 'Selby',
            'company_name' => 'MDS Collivery',
            'building' => 'MDS House',
            'street_number' => '58c',
            'street' => 'Webber Street',
            'location_type' => 1,
            'location_type_name' => 'Business Premises',
            'contact' => [
                'id' => 2519728,
                'full_name' => 'John Doe',
                'cellphone' => '0723456789',
                'email_address' => 'demo@collivery.co.za',
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/address"
);

let headers = {
    "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",
    "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"
    }
}

fetch(url, {
    method: "POST",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X POST \
    "https://api.collivery.co.za/v3/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 '{"town_id":147,"town_name":"Johannesburg","suburb_id":1936,"suburb_name":"Selby","company_name":"MDS Collivery","building":"MDS House","street_number":"58c","street":"Webber Street","location_type":1,"location_type_name":"Business Premises","contact":{"id":2519728,"full_name":"John Doe","cellphone":"0723456789","email_address":"demo@collivery.co.za"}}'

Example response (503):

{
    "message": ""
}

HTTP Request

POST v3/address

Body Parameters

Parameter Type Status Description
custom_id string optional The custom id you would like to assign to this address. Must be unique. Max 20 characters.
town_id integer optional Required without town_name. Can be obtained from /towns/ endpoint.
town_name string optional Required without town_id. Can be obtained from /towns/ endpoint.
suburb_id integer optional Required without suburb_name. Can be obtained from /suburbs/ endpoint.
suburb_name string optional Required without suburb_id. Can be obtained from /suburbs/ endpoint.
company_name string optional The name of the company of the address. Max 50 characters.
building string optional The building of the address. Max 50 characters.
street_number string optional The number on the street of the address. Max 5 characters.
street string required The name of the street that the address is on. Max 50 characters.
location_type integer optional Required without location_type_name. The id of the location type for the address. Can be obtained from /location_types/ endpoint.
location_type_name string optional Required without location_type. The name of the location type for the address. Can be obtained from /location_types/ endpoint.
contact 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.

Show

Requires authentication Requires headers

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get(
    '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',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/address/952"
);

let 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: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET \
    -G "https://api.collivery.co.za/v3/address/952" \
    -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 (503):

{
    "message": ""
}

HTTP Request

GET v3/address/{address}

URL Parameters

Parameter Status Description
address optional number required The address id.

Update

Modify the details of a pre-existing address.

Requires authentication Requires headers

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->put(
    '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',
        ],
        'json' => [
            'town_id' => 147,
            'town_name' => 'Johannesburg',
            'suburb_id' => 1936,
            'suburb_name' => 'Selby',
            'company_name' => 'MDS Collivery',
            'building' => 'MDS House',
            'street_number' => '58c',
            'street' => 'Webber Street',
            'location_type' => 1,
            'location_type_name' => 'Business Premises',
            'contact' => [
                'id' => 2519728,
                'full_name' => 'John Doe',
                'cellphone' => '0723456789',
                'email_address' => 'demo@collivery.co.za',
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/address/952"
);

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

fetch(url, {
    method: "PUT",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X PUT \
    "https://api.collivery.co.za/v3/address/952" \
    -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","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"}}'

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

HTTP Request

PUT v3/address/{address}

PATCH v3/address/{address}

URL Parameters

Parameter Status Description
address optional number required The address id.

Body Parameters

Parameter Type Status Description
custom_id string optional The custom id you would like to assign to this address. Must be unique. Max 20 characters.
town_id integer optional Required without town_name. Can be obtained from /towns/ endpoint.
town_name string optional Required without town_id. Can be obtained from /towns/ endpoint.
suburb_id integer optional Required without suburb_name. Can be obtained from /suburbs/ endpoint.
suburb_name string optional Required without suburb_id. Can be obtained from /suburbs/ endpoint.
company_name string optional The name of the company of the address. Max 50 characters.
building string optional The building of the address. Max 50 characters.
street_number string optional The number on the street of the address. Max 5 characters.
street string required The name of the street that the address is on. Max 50 characters.
location_type integer optional Required without location_type_name. The id of the location type for the address. Can be obtained from /location_types/ endpoint.
location_type_name string optional Required without location_type. The name of the location type for the address. Can be obtained from /location_types/ endpoint.
contact 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.

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',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/address/952"
);

let 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: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X DELETE \
    "https://api.collivery.co.za/v3/address/952" \
    -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."
    }
}

HTTP Request

DELETE v3/address/{address}

URL Parameters

Parameter Status Description
address optional number required The address id.

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',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/default_address"
);

let 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: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET \
    -G "https://api.collivery.co.za/v3/default_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": 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."
    }
}

HTTP Request

GET v3/default_address

3. Contacts

Manage Address Contacts

For legacy reasons, on all endpoints all of cell_no/cellphone and work_no/work_phone are returned

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' => [
            'per_page'=> '3',
            'search'=> 'Collivery',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/contacts"
);

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

let headers = {
    "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: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET \
    -G "https://api.collivery.co.za/v3/contacts?per_page=3&search=Collivery" \
    -H "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
    }
}

HTTP Request

GET v3/contacts

Query Parameters

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

Store

Save a new Contact.

Requires authentication Requires headers

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',
        ],
        'json' => [
            'address_id' => 952,
            'email' => 'foo@example.com',
            'full_name' => 'John Doe',
            'cellphone' => '0721234567',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/contacts"
);

let 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",
    "cellphone": "0721234567"
}

fetch(url, {
    method: "POST",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X POST \
    "https://api.collivery.co.za/v3/contacts" \
    -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","cellphone":"0721234567"}'

Example response (503):

{
    "message": ""
}

HTTP Request

POST v3/contacts

Body Parameters

Parameter Type Status Description
address_id integer required The id of the address you wish to add this contact to. Can be fetched through the /addresses endpoint.
email string optional optional Valid email address. Minimum 5 characters.
full_name string optional required. The contact's full name. Minimum 3 characters.
cellphone string optional Required without work_phone. Minimum 10 characters. For legacy reasons, cell_no is also supported.
work_phone string optional Required 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',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/contacts/593"
);

let 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: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET \
    -G "https://api.collivery.co.za/v3/contacts/593" \
    -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 (503):

{
    "message": ""
}

HTTP Request

GET v3/contacts/{contact}

URL Parameters

Parameter Status Description
contact optional number required The contact id

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',
        ],
        'json' => [
            'address_id' => 952,
            'email' => 'foo@example.com',
            'full_name' => 'John Doe',
            'cellphone' => '0721234567',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/contacts/593"
);

let 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",
    "cellphone": "0721234567"
}

fetch(url, {
    method: "PUT",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X PUT \
    "https://api.collivery.co.za/v3/contacts/593" \
    -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","cellphone":"0721234567"}'

Example response (503):

{
    "message": ""
}

HTTP Request

PUT v3/contacts/{contact}

PATCH v3/contacts/{contact}

URL Parameters

Parameter Status Description
contact optional number required The contact id

Body Parameters

Parameter Type Status Description
address_id integer required The id of the address you wish to add this contact to. Can be fetched through the /addresses endpoint.
email string optional optional Valid email address. Minimum 5 characters.
full_name string optional required. The contact's full name. Minimum 3 characters.
cellphone string optional Required without work_phone. Minimum 10 characters. For legacy reasons, cell_no is also supported.
work_phone string optional Required 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/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',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/contacts/593"
);

let 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: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X DELETE \
    "https://api.collivery.co.za/v3/contacts/593" \
    -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."
    }
}

HTTP Request

DELETE v3/contacts/{contact}

URL Parameters

Parameter Status Description
contact optional

4. Get Quote

Request a quote

Get a waybill quote based on the parameters provided.

### Any time warnings as well as adjusted times are returned in a "meta" array

Requires authentication Requires headers

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',
        ],
        'json' => [
            'services' => [
                2.0,
            ],
            'parcels' => [
                [
                    'length' => 21.5,
                    'width' => 10.0,
                    'height' => 5.5,
                    'weight' => 5.2,
                    'quantity' => 2.0,
                ],
            ],
            'collection_town' => 147.0,
            'delivery_town' => 200.0,
            'collection_location_type' => 1.0,
            'delivery_location_type' => 5.0,
            'collection_time' => '2025-01-24 12:00',
            'delivery_time' => '2025-01-25 16:00:00',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/quote"
);

let 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
        }
    ],
    "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"
}

fetch(url, {
    method: "POST",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X POST \
    "https://api.collivery.co.za/v3/quote" \
    -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}],"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"}'

Example response (503):

{
    "message": ""
}

HTTP Request

POST v3/quote

Body Parameters

Parameter Type Status Description
services.* number optional A list of the services you would like a quote on. Any or none of 1,2,3,5. Defaults to all services.
parcels.* object optional Very important for determining accurate an quote. Will default to an "average" parcel if not supplied. Dimensions are limited to 1000, weight is limited to 400
parcels.*.length float optional The length of the parcel. Values in centimetres. Can be supplied as floats or integers.
parcels.*.width float optional The width of the parcel. Values in centimetres. Can be supplied as floats or integers.
parcels.*.height float optional The height of the parcel. Values in centimetres. Can be supplied as floats or integers.
parcels.*.weight float optional The weight of the parcel. Values in kilograms. Can be supplied as floats or integers.
parcels.*.quantity number optional The amount of parcels of this type.
collection_address number/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
delivery_address number/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
collection_town number optional optional Required if collection_address is not supplied.
delivery_town number optional optional Required if delivery_address is not supplied.
collection_location_type number optional optional Must be a valid location type. Values can be gotten from our /location_type endpoint.
delivery_location_type number optional optional Must be a valid location type. Values can be gotten from our /location_type endpoint.
collection_time string 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.
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. Can be obtained from /towns/ endpoint.
collection_address.town_name string optional Required without town_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 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.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. Can be obtained from /towns/ endpoint.
delivery_address.town_name string optional Required without town_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 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.

5. Waybills

Store

Create a new waybill

Requires authentication Requires headers

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',
        ],
        'json' => [
            'service' => 3,
            'parcels' => [
                [
                    'length' => 21.5,
                    'width' => 10.0,
                    'height' => 5.5,
                    'weight' => 5.2,
                    'quantity' => 2.0,
                ],
            ],
            'collection_address' => '952',
            'collection_contact' => 593.0,
            'delivery_address' => '955',
            'delivery_contact' => 596.0,
            'collection_time' => '2025-01-24',
            'delivery_time' => '2025-01-25',
            'exclude_weekend' => true,
            'risk_cover' => true,
            'battery_type' => 'pi_965',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/waybill"
);

let headers = {
    "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
        }
    ],
    "collection_address": "952",
    "collection_contact": 593,
    "delivery_address": "955",
    "delivery_contact": 596,
    "collection_time": "2025-01-24",
    "delivery_time": "2025-01-25",
    "exclude_weekend": true,
    "risk_cover": true,
    "battery_type": "pi_965"
}

fetch(url, {
    method: "POST",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X POST \
    "https://api.collivery.co.za/v3/waybill" \
    -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}],"collection_address":"952","collection_contact":593,"delivery_address":"955","delivery_contact":596,"collection_time":"2025-01-24","delivery_time":"2025-01-25","exclude_weekend":true,"risk_cover":true,"battery_type":"pi_965"}'

Example response (503):

{
    "message": ""
}

HTTP Request

POST v3/waybill

Body Parameters

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

Show

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

Requires authentication Requires headers

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/waybill/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' => [
            'include'=> 'client,collection_address',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/waybill/4001907"
);

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

let headers = {
    "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: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET \
    -G "https://api.collivery.co.za/v3/waybill/4001907?include=client,collection_address" \
    -H "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,
        "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."
    }
}

HTTP Request

GET v3/waybill/{waybill}

URL Parameters

Parameter Status Description
waybill optional number required The waybill id.

Query Parameters

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

6. Status Tracking

Fetch and query status updates for your waybills

Index

Show a list of status tracking records

Requires authentication Requires headers

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' => [
            'statuses'=> '1,3',
            'per_page'=> '3',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/status_tracking"
);

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

let headers = {
    "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: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET \
    -G "https://api.collivery.co.za/v3/status_tracking?statuses=1,3&per_page=3" \
    -H "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": [
        {
            "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.local\/v3\/status_tracking?page=1",
        "last": "http:\/\/api.collivery.local\/v3\/status_tracking?page=33",
        "prev": null,
        "next": "http:\/\/api.collivery.local\/v3\/status_tracking?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 33,
        "path": "http:\/\/api.collivery.local\/v3\/status_tracking",
        "per_page": "3",
        "to": 3,
        "total": 98
    }
}

HTTP Request

GET v3/status_tracking

Query Parameters

Parameter Status Description
statuses optional optional A comma-separated list of statuses to limit the results to. Defaults to all statuses.
per_page optional optional The limit per page. If this option is provided, links and meta will exist in the response with further information about the full list of addresses. 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.

Show

Display all status tracking for a specific waybill

Requires authentication Requires headers

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/status_tracking/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',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/status_tracking/4001907"
);

let 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: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET \
    -G "https://api.collivery.co.za/v3/status_tracking/4001907" \
    -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 (503):

{
    "message": ""
}

HTTP Request

GET v3/status_tracking/{waybill}

URL Parameters

Parameter Status Description
waybill optional number required The waybill id.

Update

Accept or Cancel a waybill

Requires authentication Requires headers

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->put(
    'https://api.collivery.co.za/v3/status_tracking/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',
        ],
        'json' => [
            'status_id' => 3.0,
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/status_tracking/4001907"
);

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

fetch(url, {
    method: "PUT",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X PUT \
    "https://api.collivery.co.za/v3/status_tracking/4001907" \
    -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}'

Example response (200):

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

Example response (400):

null

Example response (400):

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

HTTP Request

PUT v3/status_tracking/{waybill}

PATCH v3/status_tracking/{waybill}

URL Parameters

Parameter Status Description
waybill optional number required The waybill id.

Body Parameters

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

7. Waybill Documents

Get your Quote or Waybill documents

Index

List your waybill documents

Requires authentication Requires headers

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',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/waybill_documents/4001907"
);

let 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: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET \
    -G "https://api.collivery.co.za/v3/waybill_documents/4001907" \
    -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 (503):

{
    "message": ""
}

HTTP Request

GET v3/waybill_documents/{waybill}

URL Parameters

Parameter Status Description
waybill optional number required The waybill id you are requesting documents for.

Show

Get the details and base64 encoded image of the waybill document

Requires authentication Requires headers

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',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/waybill_documents/4001907/waybill"
);

let 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: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET \
    -G "https://api.collivery.co.za/v3/waybill_documents/4001907/waybill" \
    -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"
    }
}

HTTP Request

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

URL Parameters

Parameter Status Description
waybill optional number required The waybill id you are requesting documents for.
type optional string required The type of document, 'waybill' or 'quote'.

8. Proofs of Delivery

Index

List your waybill proofs of delivery

Requires authentication Requires headers

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' => [
            '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"
);

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

let 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: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET \
    -G "https://api.collivery.co.za/v3/proofs_of_delivery?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 (503):

{
    "message": ""
}

HTTP Request

GET v3/proofs_of_delivery

Query Parameters

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

Show

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

Requires authentication Requires headers

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',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/proofs_of_delivery/211515"
);

let 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: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET \
    -G "https://api.collivery.co.za/v3/proofs_of_delivery/211515" \
    -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"
    }
}

HTTP Request

GET v3/proofs_of_delivery/{proofs_of_delivery}

URL Parameters

Parameter Status Description
proofs_of_delivery optional number required The proof of delivery id.

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' => [
            'per_page'=> '3',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/parcel_images"
);

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

let headers = {
    "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: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET \
    -G "https://api.collivery.co.za/v3/parcel_images?per_page=3" \
    -H "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
    }
}

HTTP Request

GET v3/parcel_images

Query Parameters

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

Show

Get the base64 encoded image

Requires authentication Requires headers

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/parcel_images/3041631',
    [
        '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',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/parcel_images/3041631"
);

let 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: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET \
    -G "https://api.collivery.co.za/v3/parcel_images/3041631" \
    -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"
    }
}

HTTP Request

GET v3/parcel_images/{parcel_image}

URL Parameters

Parameter Status Description
parcel_image optional number required The parcel image id.

10. Towns

Show and search for Towns

Index

Show all towns for a country or search towns.

Requires authentication Requires headers

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' => [
            'per_page'=> '3',
            'search'=> 'Joh',
            'province'=> 'Gauteng',
            'country'=> 'ZAF',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/towns"
);

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

let 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: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET \
    -G "https://api.collivery.co.za/v3/towns?per_page=3&search=Joh&province=Gauteng&country=ZAF" \
    -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 (503):

{
    "message": ""
}

HTTP Request

GET v3/towns

Query Parameters

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

11. Suburbs

Show and filter suburbs

Index

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

Requires authentication Requires headers

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' => [
            'per_page'=> '3',
            'latitude'=> '-26.212500',
            'longitude'=> '28.037500',
            'town_id'=> '147',
            'country'=> 'ZAF',
            '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"
);

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

let 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: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET \
    -G "https://api.collivery.co.za/v3/suburbs?per_page=3&latitude=-26.212500&longitude=28.037500&town_id=147&country=ZAF&postal_code=2000&postal_code_range=100" \
    -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 (503):

{
    "message": ""
}

HTTP Request

GET v3/suburbs

Query Parameters

Parameter Status Description
per_page optional The limit per page. If this option is provided, links and meta will exist in the response with further information about the full list of addresses. 0 is the same as not limiting. Defaults is 2000.
search optional Search by suburb name.
latitude optional A latitude to match a closest suburb against. Required if longitude is provided.
longitude optional A longitude to match a closest suburb against. Required if latitude is provided.
town_id optional Required without country. Can be obtained from /towns/ endpoint.
country optional Required without town_id. The three letter abbreviation (ISO 3166) for the country. Defaults to ZAF.
postal_code optional A postal code to limit the result set to.
postal_code_range optional The 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 optional The type of postal code to limit matches to. street or box are allowed. Defaults to a match on either.

Show

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

Requires authentication Requires headers

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/suburbs/1936',
    [
        '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',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/suburbs/1936"
);

let 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: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET \
    -G "https://api.collivery.co.za/v3/suburbs/1936" \
    -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 (503):

{
    "message": ""
}

HTTP Request

GET v3/suburbs/{suburb}

URL Parameters

Parameter Status Description
suburb optional number required The suburb id.

12. Service Types

Show all service types or searched

Index

Get available service types with delivery days

Requires headers

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',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/service_types"
);

let 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: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET \
    -G "https://api.collivery.co.za/v3/service_types" \
    -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 (503):

{
    "message": ""
}

HTTP Request

GET v3/service_types

Show

Get specific service type by id

Requires authentication Requires headers

Example request:


$client = new \GuzzleHttp\Client();
$response = $client->get(
    'https://api.collivery.co.za/v3/service_type/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',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/service_type/1"
);

let 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: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET \
    -G "https://api.collivery.co.za/v3/service_type/1" \
    -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 (503):

{
    "message": ""
}

HTTP Request

GET v3/service_type/{id}

13. 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' => [
            'search'=> 'business',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/location_types"
);

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

let headers = {
    "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: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET \
    -G "https://api.collivery.co.za/v3/location_types?search=business" \
    -H "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 (503):

{
    "message": ""
}

HTTP Request

GET v3/location_types

Query Parameters

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

14. 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',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/terms_and_conditions"
);

let 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: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET \
    -G "https://api.collivery.co.za/v3/terms_and_conditions" \
    -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 (503):

{
    "message": ""
}

HTTP Request

GET v3/terms_and_conditions

15. Battery Types

Index

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

Requires authentication Requires headers

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',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/battery_types"
);

let 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: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET \
    -G "https://api.collivery.co.za/v3/battery_types" \
    -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 (503):

{
    "message": ""
}

HTTP Request

GET v3/battery_types

16. Vendors

Manage Vendors

Index

Show all vendors, or all vendors of a certain type

Requires authentication Requires headers

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',
        ],
        'json' => [
            'vendor_id' => '123152',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/vendors"
);

let 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_id": "123152"
}

fetch(url, {
    method: "GET",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X GET \
    -G "https://api.collivery.co.za/v3/vendors" \
    -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_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
        }
    ]
}

HTTP Request

GET v3/vendors

Body Parameters

Parameter Type Status Description
vendor_id string optional optional The vendor id. Required if vendor_type TAK_SEL.

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',
        ],
        '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"
);

let 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: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X POST \
    "https://api.collivery.co.za/v3/vendors" \
    -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
        }
    ]
}

HTTP Request

POST v3/vendors

Body Parameters

Parameter Type Status Description
vendor_type string required 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/1770',
    [
        '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' => [
            '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/1770"
);

let 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: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X PUT \
    "https://api.collivery.co.za/v3/vendors/1770" \
    -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
        }
    ]
}

HTTP Request

PUT v3/vendors/{vendor}

PATCH v3/vendors/{vendor}

URL Parameters

Parameter Status Description
vendor optional number required The vendor id.

Body Parameters

Parameter Type Status Description
vendor_type string required 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/1770',
    [
        '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',
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/vendors/1770"
);

let 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: headers,
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X DELETE \
    "https://api.collivery.co.za/v3/vendors/1770" \
    -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
        }
    ]
}

HTTP Request

DELETE v3/vendors/{vendor}

URL Parameters

Parameter Status Description
vendor optional number required The vendor id.

17. Vendor Waybills

Add Vendor Waybill bookings

Store

Create a new vendor waybill

Requires authentication Requires headers

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',
        ],
        'json' => [
            'collection_address' => '955',
            'delivery_address' => '955',
            'vendor_depot' => 'CPT',
            'service_type' => 3,
            'vehicle_type' => 2,
            'collection_time' => '2025-01-24',
            'risk_cover' => true,
            'orders' => [
                [
                    'length' => 21.5,
                    'width' => 10.0,
                    'height' => 5.5,
                    'weight' => 5.5,
                    'parcel_count' => 2.0,
                    'vendor_id' => 1772.0,
                    'due_date' => '2012-02-25',
                    'purchase_order_number' => 'ex',
                    'asn' => 'ex',
                ],
            ],
        ],
    ]
);
$body = $response->getBody();
print_r(json_decode((string) $body));
const url = new URL(
    "https://api.collivery.co.za/v3/vendor_bookings"
);

let 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 = {
    "collection_address": "955",
    "delivery_address": "955",
    "vendor_depot": "CPT",
    "service_type": 3,
    "vehicle_type": 2,
    "collection_time": "2025-01-24",
    "risk_cover": true,
    "orders": [
        {
            "length": 21.5,
            "width": 10,
            "height": 5.5,
            "weight": 5.5,
            "parcel_count": 2,
            "vendor_id": 1772,
            "due_date": "2012-02-25",
            "purchase_order_number": "ex",
            "asn": "ex"
        }
    ]
}

fetch(url, {
    method: "POST",
    headers: headers,
    body: body
})
    .then(response => response.json())
    .then(json => console.log(json));
curl -X POST \
    "https://api.collivery.co.za/v3/vendor_bookings" \
    -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 '{"collection_address":"955","delivery_address":"955","vendor_depot":"CPT","service_type":3,"vehicle_type":2,"collection_time":"2025-01-24","risk_cover":true,"orders":[{"length":21.5,"width":10,"height":5.5,"weight":5.5,"parcel_count":2,"vendor_id":1772,"due_date":"2012-02-25","purchase_order_number":"ex","asn":"ex"}]}'

Example response (503):

{
    "message": ""
}

HTTP Request

POST v3/vendor_bookings

Body Parameters

Parameter Type Status Description
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.
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.
vendor_depot string required Takealot JNB (JNB) or Takealot CPT (CPT) depot.
service_type integer required A service you would like to deliver the waybill on. Defaults to 2 (Overnight Express).
vehicle_type integer required The vehicle that we should collect it with. Defaults to 1 (Motorbike).
collection_time string required 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.
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.
orders.*.length float optional optional The length of the parcel. Values in centimetres. Can be supplied as floats or integers.
orders.*.width float optional optional The width of the parcel. Values in centimetres. Can be supplied as floats or integers.
orders.*.height float optional optional The height of the parcel. Values in centimetres. Can be supplied as floats or integers.
orders.*.weight float optional optional The weight of the parcel. Values in kilograms. Can be supplied as floats or integers.
orders.*.parcel_count number required The amount of parcels of this type.
orders.*.vendor_id number required The id of the vendor stored with Collivery.
orders.*.due_date date required The date the order is due at Vendor depot.
orders.*.purchase_order_number string required The Purchase order number. Example 165488742
orders.*.asn string optional optional The ASN of order. Example TAL_12341
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. Can be obtained from /towns/ endpoint.
collection_address.town_name string optional Required without town_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.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. Can be obtained from /towns/ endpoint.
delivery_address.town_name string optional Required without town_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.

18. Errors

The API uses the following error codes:

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