Developers ยท APIs

Follow parcels and sync addresses from your own software

The API of Ultineo Logistics, on api.logistic.ultineo.com, lets your own software add the parcels you want to follow, keep your address book in step with your other tools and read the carrier catalogue. Each call carries an API key of your project, limited to its scopes.

What your software can do with these routes

Follow parcels

Your software adds the parcels you want to follow, each with its tracking number and its carrier. Ultineo then registers the number with the carrier in the background and writes the result on the parcel: its status, its last location, its delivery dates and one event per checkpoint.

Sync the address book

The address book keeps the sender and recipient addresses you reuse, the ones you pick when you add a parcel or record a shipping label. The address routes add, list, change and delete its entries, so that it stays in step with your other tools.

Read the carrier catalogue

Read the catalogue to find the carrier of a parcel, by part of its name, by its tracking code or by its country. You pass its id as carrier_id, or its tracking code as carrier_code, when you create the parcel.

The routes, family by family

A key reads and writes the address book and the parcels of the account it belongs to, and nothing else; the carrier catalogue is shared and read-only. Reads need the carrier:read, parcel:read or address:read scope, and creating, changing or deleting a parcel or an address needs parcel:write or address:write.

Carriers

GET /v1/carrier/list lists the catalogue with the filters q, code, country and source, and GET /v1/carrier/detail/carr_โ€ฆ reads one carrier. A carrier comes back with its id, its name, its short code, its tracking code, its country, its website and its public tracking page.

Follow a parcel

POST /v1/parcel/create sends a tracking number of 5 to 50 characters and the carrier, with an optional label, an address of your book as recipient and a dispatch. One call adds one parcel, or up to 100 under items: more than 100 answers 413.

The parcel object

GET /v1/parcel/detail/parc_โ€ฆ returns the parcel: its status, pending at first and then the status of the carrier, the state of its tracking, its carrier, recipient and shipment, and its progress with the last location and the delivery dates. It also returns events, the checkpoints of the parcel, newest first.

List and sync parcels

GET /v1/parcel/list filters by status, tracking number, carrier, recipient or shipment, searches with q, and takes limit (50 by default, 100 at most) and offset. The same route syncs the list with updated_since and a cursor.

Change or delete a parcel

PATCH /v1/parcel/detail/parc_โ€ฆ changes the fields the body names and leaves the others as they are; changing the tracking number or the carrier registers the parcel again, and its status goes back to pending; an archived parcel can no longer be changed. DELETE on the same path removes the parcel from your lists.

Add an address

POST /v1/address/create sends a role, sender or recipient, with a phone number, the first address line, the postal code, the city and a two-letter country code, and answers 201. The phone number, and the e-mail address when there is one, are checked before anything is stored, and the entry keeps their normalized form.

List, change or delete an address

GET /v1/address/list filters by role, status, country, default entry or q; PATCH and DELETE on /v1/address/detail/addr_โ€ฆ change the fields the body names, status included, or remove the entry from your book. There is at most one default entry per role and only an activated entry can be it: marking one clears the others.

Follow one parcel, or several

The first sample is the request that adds one parcel and answers 201 with the parcel. The second is the body that adds several parcels in one call.

Creation request

curl -X POST https://api.logistic.ultineo.com/v1/parcel/create \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_number": "1Z999AA10123456784",
    "carrier_code": "100002",
    "label": "Order 1042"
  }'

The carrier is named here by carrier_code, its tracking code, and label is your own name for the parcel.

Body for several parcels

{
  "items": [
    { "tracking_number": "1Z999AA10123456784", "carrier_code": "100002" },
    { "tracking_number": "LX123456789FR", "carrier_id": "carr_4f1c2a9d8e7b6a5c4d3e" }
  ]
}

Each item names its carrier by carrier_code or carrier_id, and the answer lists one entry per item, in order: created or existing with its id, or the code and reason of its refusal; the status is 422 only when every item was refused.

What to watch for

Tracking arrives later

A parcel starts with the status pending, and the create call itself returns nothing of what the carrier reports. Read the parcel again, or sync the list.

Nothing is stored twice

A tracking number already followed in your book, or the same contact name at the same postal code, is not stored a second time: the answer is 409 and carries the id of the parcel or of the entry that already holds it. In a call with items, a number already followed comes back as an entry marked existing, with its id.

A check that cannot run

If the check of the phone number or of the e-mail address of an entry cannot be made, the answer is 503 and nothing is stored. Send the request again later.

The articles behind this page

This page restates the following articles of the help center. They hold every field, every value and every answer.

Ultineo Logistics help center

Shipments

Parcels, carriers and delivery progress

Open the page

Continue in this section

E-commerce API

Create API access and exchange your shop data

Open the page

Catalogue, orders and vouchers

What a program sends and reads back for each catalogue, sales history and voucher resource.

Open the page

Ultineo Reasoning API

Run your reasoning from your software.

Open the page

Ultineo SaaS project API

Review an API scope for an eligible project and distinguish planned routes from the endpoints already built.

Open the page

Developer overview

Start with one parcel and its carrier

The Ultineo Logistics help center gives every field of the parcel, address and carrier routes; an API key holding their scopes is created for your project in Ultineo Logistics.

Questions

Sync the list. Call GET /v1/parcel/list once with updated_since set to a Unix timestamp and store the cursor of the answer, then call the list with that cursor next time and store the new one. While next_cursor is not null, more rows are waiting: call again with it at once. A sync takes no offset.

Yes. These routes work on the same records as the screens of Ultineo Logistics. A parcel created by the API appears in your parcel list, and an address added on screen can be read through the API.

Yes. A PATCH with tracking set to paused stops following the parcel, and active resumes. In Ultineo Logistics, the page of the parcel has a pause too, and the information already collected stays available. To ask the carrier again at the next pass, send refresh set to true.

DELETE removes the parcel from your lists and answers its id with deleted set to true. In Ultineo Logistics, a parcel deleted on screen leaves your lists while its information and tracking history are kept, and no request is sent to the carrier.