API Integration

Documentation REST JSON v1.0

Intro to API documentation

YouSend API, is a way to formalize your sendings 100% automatically. Each time your customer would place an order on your platform you automatically make its shipment on YouSend

API Documentation described below is an instrument that integrates with YouSend and synchronizes your data with our service

i
YouSend
i
Our API
i
Your Business

Table Of Contents

Available Services

Please don't be afraid of the code below. It is easy to understand to anyone who is familiar with coding. Simply email link to this page to anyone who is managing your webpage and hopefully they will make API connection with us easily. However if you will need any assitstance - please contact us and we will be happy to help!

Base url

The base URL of the api is located at https://yousend.lv/api/[_env]/v1


Authentication

You authenticate against the API using “Bearer authentication
The name “Bearer authentication” can be understood
as “give access to the bearer of this token.”

Bearer authentication (also called token authentication)
is an HTTP authentication scheme that involves
security tokens called bearer tokens.


An example how to get a "Bearer authentication token"


*** Method ***

POST

*** Production and development HTTPS URL ***

Production url:
https://yousend.lv/api/production/v1/auth/login;

Development url:
https://yousend.lv/api/development/v1/auth/login;



*** HTTPS Request Headers ***

$header = [
    Content-Type     : application/json,
    X-Requested-With : XMLHttpRequest
];


*** HTTPS Request with json data ***

$data = json_encode([
    'email'         => 'YOUR_EMAIL_ADDRESS',
    'password'      => 'YOUR_PASSWORD'
]);


*** HTTPS responses ***

Status code [200] - your request has been successfully processed

{
    "access_token" : "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImE1YTlmYzE1Z
    jc1MGRhZjk3NTljZjJlOWY3NWFlMGM0OTI5NWIzNjNlODc3MTAyOGZhYjc4YmZkZDgxMWQxOGZl
    YWRmNDkyMDc0ODJhNzAzIn0.eyJhdWQiOiIzIiwianRpIjoiYTVhOWZjMTVmNzUwZGFmOTc1OWN
    mMmU5Zjc1YWUwYzQ5Mjk1YjM2M2U4NzcxMDI4ZmFiNzhiZmRkODExZDE4ZmVhZGY0OTIwNzQ4Mm
    E3MDMiLCJpYXQiOjE1NDgzMzYxMjUsIm5iZiI6MTU0ODMzNjEyNSwiZXhwIjoxNTc5ODcyMTI1L
    CJzdWIiOiIxMjAiLCJzY29wZXMiOltdfQ.DzZv_es9NbF3yjQTj3tOyNFxxBRa29TdJqbXWGBl3
    c_0V_yIrNvl9qJPOStlRFLUDbDDkDRY6EtRwFhGrALv2nw2a7TWGhtBOBz2VaYiQ1cdus855lRZ
    NbApYcOop4PFJkX5IgUlypefWW3RTjzayp1UdCS7UcnFB_-DPTnk90Fbb170ypgBLNwWzVAjqI_
    KmSfRgjALXO4xXg6HsUD3snkgt_tzZ_-Dk_xbza67KvJ0lFPbI4pj706LbXERbjRF2a-VTP5FD8
    vCXPLJxEjJNZJemC3OQ0WOcRNg2VTYpGK84rlnjqOfIVDbVehemBYLgjkHyk6ZWrYQtRcdpfKvy
    qcSqfc6WDl71d93RyHG5Lz28TfckYjvRzT_sjWeb_qhRyA_gvnVM826EdggO_Oaa7kcq0hhmlm-
    NL-nX1Yelz7U_Bob76slo6tESdG-V7z9CcjQ_7Jvn2DJzhcFC0tCiP-NbwepfgivGRBv65pFxs-
    llhDXziNFubw8Ax3JvAXR9VRhNobO935svY9SlEcUCOrlERJ0AbE-RUSorm7-oFX5XCh9uCRsub
    VAuvx0t5TkEsNdA_XSLJZXQcLizugs_hWIljEuBqTNInp7o6KisU_MC7mrjiPbQQYsawx1CR3m2
    ZSt4ONcQP28wgv2MItG7AA3I78m3uY54YubKh0ofh8",
    "token_type":"Bearer",
    "expires_at":"2024-01-30 00:00:00"
}

Status code [401] - Invalid or email/password

{
    "message" : "Unauthorized"
}
                            
Base url

The base URL of the api is located at https://yousend.lv/api/[_env]/v1

An example how to get prices

*** Production and development HTTPS URL ***

production url:
https://yousend.lv/api/production/v1/services/calculate;

Development url:
https://yousend.lv/api/development/v1/services/calculate;


*** HTTPS Request Headers ***

$header = [
    Content-Type     : application/json,
    X-Requested-With : XMLHttpRequest
    Authorization    : Bearer 'TOKEN'
];


*** HTTPS Request with valid json data ***

=============================== Austria 4690 2 packages ===============================

    2 Kg [27 x 28 x 29]
    3 Kg [50 x 50 x 50]

Request URL

https://yousend.lv/api/development/v1/services/calculate?zip_code=4690&weight%5B%5D=2
&length%5B%5D=27&width%5B%5D=28&height%5B%5D=29&weight%5B%5D=3&length%5B%5D=50
&width%5B%5D=50&height%5B%5D=50&country_code=at&package_type=1&send_adr=0

Status code 200 - Request was successfully

{
    "type": "success",
    "message": "OK",
    "data": [
        {
            "package_type": 1,
            "service_code": "ups_standard",
            "service_name": "UPS Standard",
            "final_price_without_tax": "43.85",
            "final_price_with_tax": "53.06",
            "is_eu": 1,
            "service_type": 2,
            "zip_code": "4690",
            "country_code": "at",
            "dimensions": [
                {
                    "weight": "2",
                    "length": "27",
                    "height": "29",
                    "width": "28"
                },
                {
                    "weight": "3",
                    "length": "50",
                    "height": "50",
                    "width": "50"
                }
            ],
            "delivery_days": "5-6"
        },
        {
            "package_type": 1,
            "service_code": "ups_express_saver",
            "service_name": "UPS Express Saver",
            "final_price_without_tax": "100.85",
            "final_price_with_tax": "122.03",
            "is_eu": 1,
            "service_type": 1,
            "zip_code": "4690",
            "country_code": "at",
            "dimensions": [
                {
                    "weight": "2",
                    "length": "27",
                    "height": "29",
                    "width": "28"
                },
                {
                    "weight": "3",
                    "length": "50",
                    "height": "50",
                    "width": "50"
                }
            ],
            "delivery_days": "1-2"
        }
    ]
}

=============================== Austria 4690 1 packages ===============================

    2 Kg [27 x 28 x 29]

Request URL

https://yousend.lv/api/development/v1/services/calculate?zip_code=4690&weight%5B%5D=2
&length%5B%5D=27&width%5B%5D=28&height%5B%5D=29&country_code=at&package_type=1&send_adr=0


Status code 200 - Request was successfully

{
    "type": "success",
    "message": "OK",
    "data": [
        {
            "package_type": 1,
            "service_code": "ups_standard",
            "service_name": "UPS Standard",
            "final_price_without_tax": "39.79",
            "final_price_with_tax": "46.05",
            "is_eu": 1,
            "service_type": 2,
            "zip_code": "4690",
            "country_code": "at",
            "dimensions": [
                {
                    "weight": "2",
                    "length": "27",
                    "height": "29",
                    "width": "28"
                }
            ],
            "delivery_days": "5-6"
        },
        {
            "package_type": 1,
            "service_code": "ups_express_saver",
            "service_name": "UPS Express Saver",
            "final_price_without_tax": "51.60",
            "final_price_with_tax": "60.34",
            "is_eu": 1,
            "service_type": 1,
            "zip_code": "4690",
            "country_code": "at",
            "dimensions": [
                {
                    "weight": "2",
                    "length": "27",
                    "height": "29",
                    "width": "28"
                }
            ],
            "delivery_days": "1-2"
        }
    ]
}

=============================== Austria 4690 1 envelope ===============================

    0.5 Kg [27 x 28 x 29]

Request URL

https://yousend.lv/api/development/v1/services/calculate?&zip_code=4690
&weight%5B%5D=0.5&country_code=at&package_type=2&send_adr=0


Status code 200 - Request was successfully

{
    "type": "success",
    "message": "OK",
    "data": [
        {
            "package_type": 2,
            "service_code": "ups_express_saver",
            "service_name": "UPS Express Saver",
            "final_price_without_tax": "28.36",
            "final_price_with_tax": "34.32",
            "is_eu": 1,
            "service_type": 1,
            "zip_code": "4690",
            "country_code": "at",
            "dimensions": [
                {
                    "weight": "0.5",
                    "length": 10,
                    "height": 10,
                    "width": 10
                }
            ],
            "delivery_days": "1-2"
        },
        {
            "package_type": 2,
            "service_code": "ups_express_envelope",
            "service_name": "UPS Express Envelope",
            "final_price_without_tax": "28.36",
            "final_price_with_tax": "34.32",
            "is_eu": 1,
            "service_type": 1,
            "zip_code": "4690",
            "country_code": "at",
            "dimensions": [
                {
                    "weight": "0.5",
                    "length": 10,
                    "height": 10,
                    "width": 10
                }
            ],
            "delivery_days": "1-2"
        }
    ]
}

*** HTTPS Request with invalid json data ***

=============================== Austria 4690d 2 packages ===============================

    2 Kg [27 x 28 x 29]
    3 Kg [50 x 50 x 50]

Request URL

https://yousend.lv/api/development/v1/services/calculate?zip_code=4690d&weight%5B%5D=2
&length%5B%5D=27&width%5B%5D=28&height%5B%5D=29&weight%5B%5D=3&length%5B%5D=50
&width%5B%5D=50&height%5B%5D=50&country_code=at&package_type=1&send_adr=0

Status code 422 - Validation error
{
    "type": "error",
    "message": "An exception has been raised as a result of client data",
    "errors": {
        "zip_code": [
            "Available post code format(s):####"
        ]
    }
}

=============================== Austria 4690 2 packages ===============================

    2 Kg [27 x 28 x 29]
    3 Kg [50 x 50 x 50]

Request URL

https://yousend.lv/api/development/v1/services/calculate?zip_code=4690d&weight%5B%5D=2
&length%5B%5D=27&width%5B%5D=28&height%5B%5D=29&weight%5B%5D=3&length%5B%5D=50
&width%5B%5D=50&height%5B%5D=50&country_code=at&parcel_copy_id=&package_type=3&send_adr=0

Status code 422 - Validation error
{
    "type": "error",
    "message": "An exception has been raised as a result of client data",
    "errors": {
        "package_type": [
            "The selected package type is invalid.",
            "The package type may not be greater than 2."
        ]
    }
}

Base url

The base URL of the api is located at https://yousend.lv/api/[_env]/v1

An example how to create a new order

*** Production and development HTTPS URLs ***

$url_prod = 'https://yousend.lv/api/production/v1/services/order-store';
$url_dev = 'https://yousend.lv/api/development/v1/services/order-store';


*** HTTPS Request Headers ***

$header = [
    Content-Type     : application/json,
    X-Requested-With : XMLHttpRequest
    Authorization    : Bearer 'TOKEN'
];


*** HTTPS Request with valid json data ***

=============================== Austria 4690 2 packages ===============================

    2 kg [27 x 28 x 29]
    3 kg [50 x 50 x 50]

Request data

{
    "send_adr":"1",
    "parcel_price":"8.99",
    "parcel_currency":"1",
    "parcel_description":"Books",
    "parcel_sender":"Petter Parker",
    "parcel_pickup_address":"Marupes 56",
    "parcel_pickup_date":"2019-01-31 17:26:24",
    "reason_for_export":"sold",

    "weight":[
        "2","3"
    ],
    "length":[
        "27","50"
    ],
    "height":[
        "28","50"
    ],
    "width":[
        "29","50"
    ],

    "recipient_house_number":"23",
    "recipient_address_1":"test 5-6",
    "recipient_company_name":"SIA GT",

    "recipient_city":"AMPASS",
    "recipient_state_or_province":"TILON",

    "zip_code":"4690",
    "country_code":"at",
    "recipient_name":"Petter",
    "recipient_phone":"29878473829",
    "recipient_email":"petterparker@gmail.com",

    "package_type":"1",
    "service_code":"ups_express_saver"
}

Status code 200 - Request was successfully

{
    "type": "success",
    "message": "Shipment has been successfully created",
    "data": {
        "shipment_id": 543311
    }
}


=============================== Austria 4690 1 packages ===============================

    2 kg [27 x 28 x 29]

Request data

{
    "send_adr":"1",
    "parcel_price":"8.99",
    "parcel_currency":"1",
    "parcel_description":"Books",
    "parcel_sender":"Petter Parker",
    "parcel_pickup_address":"Marupes 56",
    "parcel_pickup_date":"2019-01-31 17:26:24",
    "reason_for_export":"sold",

    "weight":[
        "2"
    ],
    "length":[
        "27"
    ],
    "height":[
        "28"
    ],
    "width":[
        "29"
    ],

    "recipient_house_number":"23",
    "recipient_address_1":"test 5-6",
    "recipient_company_name":"SIA GT",

    "recipient_city":"AMPASS",
    "recipient_state_or_province":"TILON",

    "zip_code":"4690",
    "country_code":"at",
    "recipient_name":"Petter",
    "recipient_phone":"29878473829",
    "recipient_email":"petterparker@gmail.com",

    "package_type":"1",
    "service_code":"ups_express_saver"
}


Status code 200: Request was successfully

{
    "type": "success",
    "message": "Shipment has been successfully created",
    "data": {
        "shipment_id": 443212
    }
}


=============================== Austria 4690 1 envelope ===============================

    0.5 kg

Request data

{
    "send_adr":"1",
    "parcel_price":"8.99",
    "parcel_currency":"1",
    "parcel_description":"Books",
    "parcel_sender":"Petter Parker",
    "parcel_pickup_address":"Marupes 56",
    "parcel_pickup_date":"2019-01-31 17:26:24",
    "reason_for_export":"sold",

    "weight":[
        "0.5"
    ],

    "recipient_house_number":"23",
    "recipient_address_1":"test 5-6",
    "recipient_company_name":"SIA GT",

    "recipient_city":"AMPASS",
    "recipient_state_or_province":"TILON",

    "zip_code":"4690",
    "country_code":"at",
    "recipient_name":"Petter",
    "recipient_phone":"29878473829",
    "recipient_email":"petterparker@gmail.com",

    "package_type":"2",
    "service_code":"ups_express_saver"
}

Status code 200 - Request was successfully

{
    "type": "success",
    "message": "Shipment has been successfully created",
    "data": {
        "shipment_id": 4332313
    }
}



*** HTTPS Request with invalid json data ***


=============================== Austria 4690d 2 packages ===============================

    2 kg [27 x 28 x 29]
    3 kg [50 x 50 x 50]

Request data

{
    "send_adr":"1",
    "parcel_price":"8.99",
    "parcel_currency":"1",
    "parcel_description":"Books",
    "parcel_sender":"Petter Parker",
    "parcel_pickup_address":"Marupes 56",
    "parcel_pickup_date":"2019-01-31 17:26:24",
    "reason_for_export":"sold",

    "weight":[
        "2","3"
    ],
    "length":[
        "27","50"
    ],
    "height":[
        "28","50"
    ],
    "width":[
        "29","50"
    ],

    "recipient_house_number":"23",
    "recipient_address_1":"test 5-6",
    "recipient_company_name":"SIA GT",

    "recipient_city":"AMPASS",
    "recipient_state_or_province":"TILON",

    "zip_code":"4690d",
    "country_code":"at",
    "recipient_name":"Petter",
    "recipient_phone":"29878473829",
    "recipient_email":"petterparker@gmail.com",

    "package_type":"1",
    "service_code":"ups_express_saver"
}

Status code 422 - Validation error

{
    "type": "error",
    "message": "Исключение было вызвано данными клиента",
    "errors": {
        "zip_code": [
            "Доступный формат (-ы) почтового индекса:####"
        ]
    }
}


=============================== Austria 4690 1 envelope ===============================

    0.5 kg

Request data

{
    "send_adr":"1",
    "parcel_currency":"1",
    "parcel_description":"Books",
    "parcel_sender":"Petter Parker",
    "parcel_pickup_address":"Marupes 56",
    "parcel_pickup_date":"2019-01-31 17:26:24",
    "reason_for_export":"sold",

    "weight":[
        "0.5"
    ],

    "recipient_house_number":"23",
    "recipient_address_1":"test 5-6",

    "recipient_city":"AMPASS",
    "recipient_state_or_province":"TILON",

    "zip_code":"4690",
    "recipient_name":"Petter",

    "package_type":"2",
    "service_code":"ups_express_saver"
}

Status code 422 - Validation error

{
    "type": "error",
    "message": "Исключение было вызвано данными клиента",
    "errors": {
        "recipient_phone": [
            "A recipient Phone number is required, Please add it!"
        ],
        "country_code": [
            "A recipient Country is required, Please add it!"
        ],
        "parcel_price": [
            "A parcel price is required, Please add it!"
        ]
    }
}


=============================== Austria 4690 2 envelopes ===============================

    2 kg
    3 kg

Request data

{
    "send_adr":"1",
    "parcel_currency":"1",
    "parcel_description":"Books",
    "parcel_sender":"Petter Parker",
    "parcel_pickup_address":"Marupes 56",
    "parcel_pickup_date":"2019-01-31 17:26:24",
    "reason_for_export":"sold",

    "weight":[
        "2.0", "3.0"
    ],

    "recipient_house_number":"23",
    "recipient_address_1":"test 5-6",

    "recipient_city":"AMPASS",
    "recipient_state_or_province":"TILON",

    "zip_code":"4690",
    "recipient_name":"Petter",

    "package_type":"2",
    "service_code":"ups_express_saver"
}

Status code 422 - Validation error

{
    "type": "error",
    "message": "Исключение было вызвано данными клиента",
    "errors": {
        "recipient_phone": [
            "A recipient Phone number is required, Please add it!"
        ],
        "country_code": [
            "A recipient Country is required, Please add it!"
        ],
        "parcel_price": [
            "A parcel price is required, Please add it!"
        ]
    }
}


=============================== empty data ===============================

Request data

{

}

Status code 422 - Validation error

{
    "type": "error",
    "message": "Исключение было вызвано данными клиента",
    "errors": {
        "send_adr": [
            "Поле ADR обязательно для заполнения."
        ],
        "recipient_name": [
            "A recipient name is required, Please add it!"
        ],
        "recipient_phone": [
            "A recipient Phone number is required, Please add it!"
        ],
        "recipient_address_1": [
            "A recipient delivery address is required, Please add it!"
        ],
        "recipient_city": [
            "A recipient City is required, Please add it!"
        ],
        "country_code": [
            "A recipient Country is required, Please add it!"
        ],
        "zip_code": [
            "Поле почтовый индекс обязательно для заполнения."
        ],
        "parcel_price": [
            "A parcel price is required, Please add it!"
        ],
        "service_code": [
            "Поле код сервиса обязательно для заполнения."
        ],
        "parcel_currency": [
            "Please select a currency type!"
        ],
        "parcel_pickup_date": [
            "A pickup date is required, Please add it!"
        ],
        "parcel_description": [
            "A parcel description is required, Please add it!"
        ],
        "parcel_pickup_address": [
            "A parcel pickup address is required, Please add it!"
        ]
    }
}


=============================== Austria 4690d 2 packages ===============================

    2 kg [27 x 28 x 29]
    3 kg [50 x 50 x 50]

Request data

{
    "send_adr":"1",
    "parcel_price":"8.99",
    "parcel_currency":"1",
    "parcel_description":"Books",
    "parcel_sender":"Petter Parker",
    "parcel_pickup_address":"Marupes 56",
    "parcel_pickup_date":"2019-01-31 17:26:24",
    "reason_for_export":"sold",

    "weight":[
        "2","3"
    ],
    "length":[
        "27"
    ],
    "height":[
        "28"
    ],
    "width":[
        "29","50"
    ],

    "recipient_house_number":"23",
    "recipient_address_1":"test 5-6",
    "recipient_company_name":"SIA GT",

    "recipient_city":"AMPASS",
    "recipient_state_or_province":"TILON",

    "zip_code":"4690d",
    "country_code":"at",
    "recipient_name":"Petter",
    "recipient_phone":"29878473829",
    "recipient_email":"petterparker@gmail.com",

    "package_type":"1",
    "service_code":"ups_express_saver"
}

Status code 422 - Validation error

{
    "type": "error",
    "message": "Исключение было вызвано данными клиента",
    "errors": {
        "dimensions": [
            "Недопустимые размеры"
        ]
    }
}