API docs by Redocly

Tiramizoo Courier API (1.0)

Download OpenAPI specification:

Tiramizoo Support: support@tiramizoo.com License: Proprietary

Overview

The Courier API is used by the Tiramizoo driver app and therefore exposes all of the functionality available in the app. It provides the courier with their tours and offers and enables them to change the status of a stop (delivered, picked up, upload signature, error, and so on).

You only need to implement this API if your couriers are using your own app and not the Tiramizoo driver app.

Tiramizoo has two APIs:

  1. Order creation API https://dev.tiramizoo.com/delivery-openapi/ This API can be used to create and upload new orders (either for a tour or for point-to-point delivery) and to check the status of orders. It can also be used to display all service areas and time windows of the relevant process.

  2. Courier API (this document) The Courier API is used by our app and therefore exposes all of the functionality of the app.

Getting Started

You can easily connect Tiramizoo to your platform by programming against the corresponding REST/JSON API.

Please use sandbox.tiramizoo.com for testing purposes. It's a full copy of the production environment.

The tiramizoo.com API uses the HTTPS protocol for communication and JSON for serialization of request and response bodies. All URLs start with https://app.tiramizoo.com/courier_api/v1. SSL is mandatory.

Text payloads are supported only as UTF-8-encoded.

If you encounter a problem when using the API, please let us know.

Versioning

All API URLs have to be prefixed with the API mount path, e.g. /courier_api/v1/tours.

Authentication

Every Courier API endpoint is protected and requires authentication via an auth_token query parameter:

GET /courier_api/v1/tours?auth_token=YOUR_AUTH_TOKEN

The auth_token is obtained by calling the authorization endpoint (POST /courier_api/v1/auth, or the SSO variants POST /courier_api/v1/google_auth and POST /courier_api/v1/microsoft_auth) with the courier's credentials. The returned token is then passed as the auth_token query parameter on every subsequent request.

A missing or invalid auth_token results in a 401 Unauthorized response.

Error Codes & Responses

200 OK

The request succeeded. The resource was retrieved successfully.

201 Created

The resource was created successfully.

204 No Content

The request has been processed successfully and no content was returned.

400 Bad Request

The request was not valid. The request may be incorrect, or the data in the request is not in the correct format. Check the message details for more information concerning the bad request, correct the request data, and try the invocation again.

401 Unauthorized

The user is not authorized to access the requested resource. The auth_token is missing or invalid.

403 Forbidden

The user is not granted access to the requested resource.

404 Not Found

The requested resource was not found or no corresponding data is available.

405 Method Not Allowed

The HTTP method used is not supported for this resource.

406 Not Acceptable

The requested response format is not currently supported.

422 Unprocessable Entity

Data supplied is not valid. See detailed errors in the response.

500 Internal Server Error

The server encountered an unexpected condition that prevented it from processing the request.

503 Service Unavailable

The application is offline for maintenance.

504 Gateway Timeout

The request couldn't complete in time. Tiramizoo waits up to 25 seconds for a response. Try breaking it down into multiple smaller requests.

Data Formats

Dates and Times

All dates and times are in ISO 8601 format with timezone information.

Example: 2024-01-15T14:30:00+01:00

Phone Numbers

Phone numbers should be in international format with country code.

Example: +4930123456

Country Codes

Country codes follow ISO 3166-1 alpha-2 standard.

Examples: de, at, ch

Geographic Coordinates

Locations are represented as latitude/longitude pairs in decimal degrees.

Support

For API support, please contact support@tiramizoo.com

Authorization

Obtain, refresh, and revoke the courier auth_token.

Resetting the auth_token requires the courier's email and password and optionally sets the push_token, push_device, and app_version. Single sign-on is also supported via Google and Microsoft authorization endpoints.

Authenticate a courier

Authenticates a password-based (non-SSO) courier with email and password and resets the courier's auth_token, returning a fresh one to use for all subsequent requests.

Only active, confirmed, non-suspended couriers with sso: false can authenticate here. Optionally registers a push-notification device for the courier. If a different device with another push token was previously registered for the account, the previous device is logged out (a "someone else logged in" notification is sent to it) before the new device is registered.

Request Body schema: application/json
required
email
required
string <email>

Email address of the courier.

password
required
string <password>

Password of the courier.

push_token
string

Push-notification device token to register for the courier. Optional.

push_device
string

Push device platform. Optional. The value "android" is stored as the "google" platform; "ios" is stored as the "apple" platform.

Responses

Request samples

Content type
application/json
{
  • "email": "test_courier_1@tiramizoo.com",
  • "password": "secret123",
  • "push_token": "123432323456767678988765--kodfkdorhfudhrh",
  • "push_device": "android"
}

Response samples

Content type
application/json
{
  • "auth_token": "1896a3e968896fd07801c1e729da22d7",
  • "push_token": "123432323456767678988765--kodfkdorhfudhrh",
  • "name": "Erminia Hackett",
  • "timezone": "Europe/Berlin",
  • "available_vehicle_types": [
    ],
  • "home_address": null,
  • "home_address_lat": null,
  • "home_address_lng": null,
  • "packages_by_tour_access": false
}

Update the device push token

Updates the push-notification device token of the authenticated courier's registered device. Requires a valid auth_token. Returns the courier representation.

Authorizations:
auth_token
query Parameters
auth_token
required
string
Example: auth_token=bf545b8e453536ee431648d86711243b

Authentication token of the courier.

Request Body schema: application/json
required
push_token
required
string

New push-notification device token to store on the courier's device.

Responses

Request samples

Content type
application/json
{
  • "push_token": "fd208a7e27f440968b1d08a3f1800600"
}

Response samples

Content type
application/json
{
  • "auth_token": "c89ac7623c1b20a1939bb6d030df1712",
  • "push_token": null,
  • "name": "Sandy Gerhold",
  • "timezone": "Europe/Berlin",
  • "available_vehicle_types": [
    ],
  • "home_address": null,
  • "home_address_lat": null,
  • "home_address_lng": null,
  • "packages_by_tour_access": false
}

Log out the courier

Logs the courier out by clearing the auth_token and destroying the registered device. Requires a valid auth_token. Returns an empty body.

Authorizations:
auth_token
query Parameters
auth_token
required
string
Example: auth_token=bf545b8e453536ee431648d86711243b

Authentication token of the courier.

Responses

Response samples

Content type
application/json
{
  • "error": "Invalid auth_token"
}

Authenticate a courier via Google SSO

Authenticates an SSO courier using a Google identity-provider token. The token is verified via Firebase and its email must match an active SSO courier (sso: true) in the organization. On success the courier's auth_token is reset and a fresh one is returned.

Optionally registers a push-notification device for the courier. If a different device with another push token was previously registered for the account, the previous device is logged out (a "someone else logged in" notification is sent to it) before the new device is registered.

Request Body schema: application/json
required
access_token
required
string

Identity-provider ID token to verify. For Google it is verified via Firebase; for Microsoft it is validated against the configured sign-in client. The verified token's email must match an active SSO courier in the organization.

push_token
string

Push-notification device token to register for the courier. Optional.

push_device
string

Push device platform. Optional. The value "android" is stored as the "google" platform; "ios" is stored as the "apple" platform.

Responses

Request samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  • "push_token": "123432323456767678988765--kodfkdorhfudhrh",
  • "push_device": "android"
}

Response samples

Content type
application/json
{
  • "auth_token": "1896a3e968896fd07801c1e729da22d7",
  • "push_token": "123432323456767678988765--kodfkdorhfudhrh",
  • "name": "Erminia Hackett",
  • "timezone": "Europe/Berlin",
  • "available_vehicle_types": [
    ],
  • "home_address": null,
  • "home_address_lat": null,
  • "home_address_lng": null,
  • "packages_by_tour_access": false
}

Authenticate a courier via Microsoft SSO

Authenticates an SSO courier using a Microsoft identity-provider token. The token is validated against the configured Microsoft sign-in client and its email must match an active SSO courier (sso: true) in the organization. On success the courier's auth_token is reset and a fresh one is returned.

Optionally registers a push-notification device for the courier. If a different device with another push token was previously registered for the account, the previous device is logged out (a "someone else logged in" notification is sent to it) before the new device is registered.

Request Body schema: application/json
required
access_token
required
string

Identity-provider ID token to verify. For Google it is verified via Firebase; for Microsoft it is validated against the configured sign-in client. The verified token's email must match an active SSO courier in the organization.

push_token
string

Push-notification device token to register for the courier. Optional.

push_device
string

Push device platform. Optional. The value "android" is stored as the "google" platform; "ios" is stored as the "apple" platform.

Responses

Request samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  • "push_token": "123432323456767678988765--kodfkdorhfudhrh",
  • "push_device": "android"
}

Response samples

Content type
application/json
{
  • "auth_token": "1896a3e968896fd07801c1e729da22d7",
  • "push_token": "123432323456767678988765--kodfkdorhfudhrh",
  • "name": "Erminia Hackett",
  • "timezone": "Europe/Berlin",
  • "available_vehicle_types": [
    ],
  • "home_address": null,
  • "home_address_lat": null,
  • "home_address_lng": null,
  • "packages_by_tour_access": false
}

Couriers

Update the authenticated courier's profile.

Protected resource. Authorization is required via auth_token.

Update the current courier

Updates the authenticated courier's own account. Only the courier's home address and its coordinates may be changed; all other account fields are read-only and are managed elsewhere.

This is a protected resource: authorization is required via the auth_token query parameter. A missing, invalid, or inactive token results in a 401 response.

Authorizations:
auth_token
query Parameters
auth_token
required
string
Example: auth_token=bf545b8e453536ee431648d86711243b

Authentication token identifying the courier.

Request Body schema: application/json
required
home_address
string

Free-text home address of the courier.

home_address_lat
number <double>

Latitude of the courier's home address.

home_address_lng
number <double>

Longitude of the courier's home address.

Responses

Request samples

Content type
application/json
{
  • "home_address": "Wilhelm-Hale-Str. 50, 80639 Munich, Germany",
  • "home_address_lat": 48.14903,
  • "home_address_lng": 11.5408497
}

Response samples

Content type
application/json
{
  • "auth_token": "72922fc983ecd846e2415d4c6fca5f1f",
  • "push_token": null,
  • "name": "Ileen Jacobs",
  • "timezone": "Europe/Berlin",
  • "available_vehicle_types": [
    ],
  • "home_address": "Stefana Batorego 25/2, 43-200 Pszczyna, Poland",
  • "home_address_lat": 49.9749989,
  • "home_address_lng": 18.9463873,
  • "packages_by_tour_access": false
}

Tours

Manage the courier's tours.

Obtain all recent courier stops grouped into tours. There are three types of tour: tour, adhoc, and placeholder.

  • tour represents a real tour that was calculated by the system. It contains a list of stops ordered in an optimized manner. A map can (and should) be drawn from consecutive_stops_locations.
  • adhoc is a list of point-to-point deliveries; each stop in this group represents a separate "tour", which means that a map drawn from consecutive_stops_locations does not make much sense, because each stop can belong to a different day. For the same reason the time_window comes back empty.
  • placeholder represents a tour that might happen for the courier, because the courier told us they will be available if needed. The time_window is broad, to indicate when the courier might be occupied; stops and consecutive_stops_locations come back empty, as it is only a placeholder.

Protected resource. Authorization is required via auth_token.

List the courier's recent tours

Returns the authenticated courier's unfinished stops from the last week, grouped into tours and sorted by their start time.

Tours are distinguished by the type field:

  • tour - a real tour calculated by the system. It contains a list of stops ordered in an optimized manner. A map can (and should) be drawn from consecutive_stops_locations.
  • adhoc - a list of point-to-point deliveries. Each stop in this group represents a separate "tour", so a map drawn from consecutive_stops_locations does not make much sense because each stop may belong to a different day. For the same reason the tour's time window comes back broad/empty.

Note: protected resource. Authorization is required via auth_token.

The endpoint supports conditional requests: it sends Last-Modified and a strong ETag derived from the tours, and responds with 304 Not Modified when the client's cached copy is still current.

Authorizations:
auth_token
query Parameters
auth_token
required
string

Courier authentication token.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Stops

Manage stops in the scope of a tour.

Update an individual stop's status (for example mark it delivered or picked up), submit package status batches for a stop, and send delivery confirmation (handover) codes to the recipients at a stop.

Protected resource. Authorization is required via auth_token.

Update a stop

Completes (or partially completes) the jobs of a stop on the courier's current tour. For each job the server applies the corresponding order state event (pickup, partial pickup, delivery, partial delivery or return), records the real service time, and stores any signature, photo proof, recipient acknowledgement or "delivered to" details.

Only jobs in the created state whose UUID is supplied in the request are processed. Custom jobs are marked as done; the corresponding custom job in the underlying tour-plan tour, if any, is updated as well.

Protected resource. Authorization is required via auth_token.

Authorizations:
auth_token
path Parameters
uuid
required
string
Example: 67a58538-a5ce-4de7-9a57-825487a9ba63

UUID of the stop.

query Parameters
auth_token
required
string
Example: auth_token=bf545b8e453536ee431648d86711243b

Courier authentication token.

lang
string
Example: lang=de

Language code for localized messages. Falls back to English when omitted or unsupported.

Request Body schema: application/json
required
recorded_at
required
string

Date and time of the courier's action. Accepts an ISO 8601 timestamp or a "YYYY-MM-DD HH:MM" string.

service_time
required
integer

Real service time recorded for the stop, in minutes.

required
Array of objects

The jobs being completed at this stop.

delivered_to
string
Enum: "neighbour" "recipient" "housemate" "safe_place"

To whom the order was delivered.

delivered_to_extra_info
string

Additional detail about where the order was left. When delivered_to is safe_place, identifies the specific place.

signature_data_uri
string

Recipient signature image, encoded using the Data URI scheme. Supported formats: jpg, png, jpeg, gif. Maximum file size 100 KB.

acknowledged_by
string

Name of the recipient or sender who acknowledged the handover.

object

Photo proof of delivery. Required when a job's type has photo proof enabled.

additional_service_time_reason
string (AdditionalServiceTimeReasonEnum)
Enum: "goods_could_not_be_found" "handover_took_longer_as_planned" "place_was_not_specified_correctly" "contact_was_not_available" "contact_was_busy" "courier_was_ignored" "contact_could_not_be_found" "unloading_longer_than_expected_due_bulky_goods" "recipient_was_contacted_by_phone" "hotline_had_to_be_contacted_for_clarification" "reception_was_refused" "receiving_department_was_busy"

Reason justifying additional service time. Mandatory when service_time exceeds the service time included for the stop (the service_time returned by the tour/stop responses).

Responses

Request samples

Content type
application/json
{
  • "recorded_at": "2012-04-16 09:05",
  • "service_time": 10,
  • "jobs": [
    ],
  • "delivered_to": "safe_place",
  • "delivered_to_extra_info": "string",
  • "signature_data_uri": "string",
  • "acknowledged_by": "Otto Normalverbraucher",
  • "photo_proof": {
    },
  • "additional_service_time_reason": "goods_could_not_be_found"
}

Response samples

Content type
application/json
{
  • "uuid": "93585b4b-79e1-4758-bd3f-4a4ef418db42",
  • "address_line": "00816 Effertz Ridges",
  • "postal_code": "61402",
  • "city": "Melonyshire",
  • "starts_at": "2012-04-16T08:05:00+02:00",
  • "ends_at": "2012-04-16T08:10:00+02:00",
  • "name": "Schmidt LLC",
  • "lat": 52.7616,
  • "lng": 13.42,
  • "require_signature": false,
  • "pickups_require_signature": false,
  • "pickups_require_photo_proof": false,
  • "require_real_service_time": true,
  • "finishing_blocked": false,
  • "change": null,
  • "applicable_events": [ ],
  • "service_time": 5,
  • "jobs": [
    ],
  • "available_additional_service_time_reasons": [ ],
  • "service_time_options": [
    ],
  • "can_not_be_served_before": null,
  • "applicable_delivered_to_options": {
    },
  • "mandatory_recipient_name": false,
  • "allow_one_click_selection": false,
  • "information": null,
  • "deferred": false,
  • "lang": [
    ]
}

Submit a package status batch

Applies a batch of load, unload and reject actions to the packages of an unfinished stop while the courier is loading the vehicle. Each action is only applied when it is valid for the package's current state; otherwise it is silently skipped. Unknown package identifiers are ignored.

The endpoint is fire-and-forget: it returns 201 Created with an empty body regardless of how many packages were actually changed.

Protected resource. Authorization is required via auth_token.

Authorizations:
auth_token
path Parameters
stop_uuid
required
string
Example: 67a58538-a5ce-4de7-9a57-825487a9ba63

UUID of the unfinished stop being loaded.

query Parameters
auth_token
required
string
Example: auth_token=bf545b8e453536ee431648d86711243b

Courier authentication token.

Request Body schema: application/json
required
recorded_at
string

Date and time of the courier's action, as an ISO 8601 timestamp.

required
Array of objects

Package status changes to apply.

Responses

Request samples

Content type
application/json
{
  • "recorded_at": "2012-04-16T07:35:00+02:00",
  • "packages": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "Invalid auth_token"
}

Send handover code notifications

Sends the delivery confirmation (handover) code to the recipient of the drop-off orders at an unfinished stop. This is intended to be triggered by the courier once they are already with the recipient, so the recipient receives the code they need to confirm the handover.

For every order being dropped off at the stop that has a handover_code requirement, the recipient is notified by SMS (when the organization has SMS enabled and a valid mobile number is on file) and by email (when a valid recipient email is on file). Orders without a handover code are skipped.

The endpoint is fire-and-forget and asynchronous: it returns 202 Accepted with an empty body immediately and dispatches the notifications in the background. It takes no request body.

Protected resource. Authorization is required via auth_token.

Authorizations:
auth_token
path Parameters
stop_uuid
required
string
Example: 67a58538-a5ce-4de7-9a57-825487a9ba63

UUID of the unfinished stop the courier is delivering.

query Parameters
auth_token
required
string
Example: auth_token=bf545b8e453536ee431648d86711243b

Courier authentication token.

Responses

Response samples

Content type
application/json
{
  • "error": "Invalid auth_token"
}

Return Stop

Deliver packages to the return stop.

Protected resource. Authorization is required via auth_token.

Deliver packages to the return stop

Records the delivery of one or more packages to their return stop. The courier submits the returned packages together with the recorded time and service time; on success the affected orders are moved to the returned state and the updated return stop is returned.

All submitted packages must belong to the same return address. If the packages span multiple return addresses, are not yet ready to be returned, or no return stop exists for them, the request is rejected with an invalid_packages error. The action is idempotent: re-submitting packages that have already been returned succeeds without changing their original recorded time.

This is a singular resource, so the path carries no identifier.

Authorizations:
auth_token
query Parameters
auth_token
required
string

Authentication token of the courier.

Request Body schema: application/json
required
recorded_at
required
string <date-time>

Date and time of the courier's action, in ISO 8601 format.

service_time
required
integer

Real service time recorded at the return stop, in minutes.

required
Array of objects

Packages being delivered to the return stop.

signature_data_uri
string

Signature image encoded using the Data URI scheme. Supported formats: jpg, jpeg, png, gif. Maximum file size 100 kB.

delivered_to
string

To whom the packages were delivered (e.g. recipient, neighbour, housemate, safe_place).

delivered_to_extra_info
string

Additional detail about where the packages were left. When delivered_to is "safe_place" this should describe the specific place.

additional_service_time_reason
string

Reason justifying additional service time. Mandatory when the recorded service_time exceeds the service time included for the stop.

object

Photo proof of the return, required when the job type requires it.

Responses

Request samples

Content type
application/json
{
  • "recorded_at": "2019-08-24T14:15:22Z",
  • "service_time": 0,
  • "packages": [
    ],
  • "signature_data_uri": "string",
  • "delivered_to": "string",
  • "delivered_to_extra_info": "string",
  • "additional_service_time_reason": "string",
  • "photo_proof": {
    }
}

Response samples

Content type
application/json
{
  • "uuid": "cf74d03b-8f79-4c54-abd7-bc48a5d88f59",
  • "address_line": "41293 Kuhic Dale",
  • "postal_code": "79621-6607",
  • "city": "Lake Antonietta",
  • "starts_at": "2012-04-16T10:28:00+02:00",
  • "ends_at": "2012-04-16T10:33:00+02:00",
  • "name": "Larson-Gutkowski",
  • "lat": 10.231,
  • "lng": 43.001,
  • "require_signature": false,
  • "pickups_require_signature": false,
  • "pickups_require_photo_proof": false,
  • "require_real_service_time": true,
  • "finishing_blocked": false,
  • "change": null,
  • "applicable_events": [ ],
  • "service_time": 5,
  • "jobs": [
    ],
  • "available_additional_service_time_reasons": [ ],
  • "service_time_options": [
    ],
  • "can_not_be_served_before": null,
  • "applicable_delivered_to_options": {
    },
  • "mandatory_recipient_name": false,
  • "allow_one_click_selection": false,
  • "information": null,
  • "deferred": false,
  • "lang": [
    ]
}

Stops Updates

Review and accept pending offers (stops the courier has not yet taken on).

Obtain all stops with pending offers, count them, retrieve an individual pending offer, and accept it.

Protected resource. Authorization is required via auth_token.

List pending stops updates

Returns all of the courier's pending offers as stops updates, ordered by the offered order's stops. Each entry combines the offered order's masked contact, package, and time-window details for the pickup and delivery.

Sensitive contact and package fields (names, phone numbers, package identifiers and descriptions, free-text information) are masked until the offer is accepted, so they come back as a localized placeholder such as --- Hidden ---.

As a side effect, fetching this list marks every returned offer as seen.

Note: protected resource. Authorization is required via auth_token.

Authorizations:
auth_token
query Parameters
auth_token
required
string

Courier authentication token.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Count pending stops updates

Returns the number of pending offers (stops updates) available to the authenticated courier.

Note: protected resource. Authorization is required via auth_token.

Authorizations:
auth_token
query Parameters
auth_token
required
string

Courier authentication token.

Responses

Response samples

Content type
application/json
{
  • "count": 0
}

Show a stops update for an offer

Returns the stops update for a single pending offer, identified by the offer's UUID. The response previews how accepting the offer would change the courier's ad-hoc tour: it builds (or reuses) the courier's unfinished ad-hoc tour for the offered order's pickup date, mixes in the offered order, and returns the resulting list of stops with their jobs.

Each stop carries a change field indicating whether it would be created or otherwise modified by accepting the offer. Sensitive contact and package fields remain masked until the offer is accepted.

If no pending offer matches the given UUID (for example, because another courier already accepted it), the endpoint responds with 404 Not Found and an offer_no_longer_available error.

The endpoint supports conditional requests: it sends an ETag and responds with 304 Not Modified when the client's cached copy is still current.

Note: protected resource. Authorization is required via auth_token.

Authorizations:
auth_token
path Parameters
id
required
string <uuid>

UUID of the pending offer.

query Parameters
auth_token
required
string

Courier authentication token.

Responses

Response samples

Content type
application/json
{
  • "courier_company_name": "Company 2",
  • "courier_offer_uuid": "ddede62b-4e55-4b12-9f4c-d497d3cf22b0",
  • "stops": [
    ]
}

Accept a stops update offer

Accepts the pending offer identified by the given UUID. Accepting the offer adds the offered order to the courier's ad-hoc tour, creating a new stop (or reusing an existing one) on a new or existing mobile tour.

On success the endpoint responds with 204 No Content and an empty body.

If no pending offer matches the given UUID (for example, because another courier already accepted it), the endpoint responds with 404 Not Found and an offer_no_longer_available error. If the acceptance is rejected because of invalid state parameters, the endpoint responds with 422 Unprocessable Content.

This action does not read any request-body parameters; the offer is identified solely by the UUID in the path.

Note: protected resource. Authorization is required via auth_token.

Authorizations:
auth_token
path Parameters
id
required
string <uuid>

UUID of the pending offer to accept.

query Parameters
auth_token
required
string

Courier authentication token.

Responses

Response samples

Content type
application/json
{
  • "error": "Invalid auth_token"
}

Signatures

Retrieve a signature image captured at a stop. The endpoint responds with a PNG image file.

Show a signature image

Return the captured signature image for the given signature UUID as a PNG binary. The response is the raw image rendered inline (Content-Type: image/png), not a JSON document.

Unlike most courier endpoints, this action does not require courier authentication: the controller skips the require_courier filter, so the auth_token query parameter is not read or enforced. The signature is looked up solely by its UUID.

If no signature matches the given UUID, the endpoint responds with 404 Not Found and an empty body.

Authorizations:
auth_token
path Parameters
uuid
required
string <uuid>
Example: ed25b451-43d6-427f-845d-e0d5914e5965

The UUID of the signature to render.

Responses

Delivery Events

Create a delivery event for one or more jobs, for example to report a delivery or pickup failure with a specific reason.

Protected resource. Authorization is required via auth_token.

Create a delivery event

Record a delivery (failure) event for one or more jobs of a single stop. The courier uses this endpoint to report that a pickup or delivery could not be completed, attaching the relevant proof (signature and/or photo) and the real service time spent.

All supplied job_uuids must belong to the authenticated courier and resolve to exactly one stop; otherwise the request fails. If none of the supplied UUIDs match an unfinished job for the courier, the request is treated as a no-op and still returns 201.

Applying a failure event transitions the affected orders through the order state machine (for example to pickup_failed or delivery_failed). On a failed delivery this can create a return stop, either on an existing mobile tour or on a newly created one. When all jobs of the stop are finished, the stop is marked done.

Some events require proof:

  • A signature is required for events configured as signable (and is also validated whenever a signature_data_uri is supplied).

  • A photo proof is required for events configured as proofable, such as wrong_package_size and name_not_found_on_doorbell (and is also validated whenever a photo_proof is supplied).

Protected resource. Authorization is required via auth_token.

Authorizations:
auth_token
query Parameters
auth_token
required
string
Example: auth_token=bf545b8e453536ee431648d86711243b

Authentication token of the courier.

Request Body schema: application/json
required
job_uuids
required
Array of strings <uuid> [ items <uuid > ]

UUIDs of the jobs the event applies to. All jobs must belong to the authenticated courier and to the same stop. If none of the supplied UUIDs match an unfinished job for the courier, the request is a no-op and still returns 201.

type
required
string
Enum: "package_was_not_ready" "sender_wants_to_cancel" "sender_was_not_at_home" "wrong_package_size" "abort_delivery" "recipient_was_not_at_home" "not_enough_money_for_payment" "package_is_damaged" "package_was_delivered_too_late" "package_was_not_accepted" "package_was_not_ordered" "no_access_to_building" "name_not_found_on_doorbell" "no_attempt_due_to_being_late" "address_not_found" "failed_due_to_business_closed"

The failure event to apply. The set of valid values is the union of the pickup, delivery, and universal failure events. Applying a failure event may transition the order to pickup_failed or delivery_failed and, on a failed delivery, can create a return stop.

recorded_at
string <date-time>

When the event occurred. Required by the order state machine; omitting it produces a validation error on the recorded_at field.

service_time
number

Total real service time, in minutes, spent at the stop for the supplied jobs. The value is divided evenly across the jobs. When omitted, a default real service time is used.

additional_service_time_reason
string
Enum: "goods_could_not_be_found" "handover_took_longer_as_planned" "place_was_not_specified_correctly" "contact_was_not_available" "contact_was_busy" "courier_was_ignored" "contact_could_not_be_found" "unloading_longer_than_expected_due_bulky_goods" "recipient_was_contacted_by_phone" "hotline_had_to_be_contacted_for_clarification" "reception_was_refused" "receiving_department_was_busy"

Reason justifying additional service time. Mandatory when the reported service time exceeds the service time included for the stop (see the service_time field of the stops endpoint). The accepted values depend on the job type: pickup, delivery, and return jobs each have their own set of reasons.

acknowledged_by
string

Name of the recipient or sender who acknowledged the event.

signature_data_uri
string

Signature image encoded using the Data URI scheme. Required when the event requires a signature for any of the supplied jobs. Supported formats: jpg, jpeg, png, gif.

object

Photo proof of the failure. Required for events that mandate a photo proof (for example wrong_package_size and name_not_found_on_doorbell).

Responses

Request samples

Content type
application/json
{
  • "job_uuids": [
    ],
  • "type": "package_is_damaged",
  • "recorded_at": "2015-01-07T15:18:42Z",
  • "service_time": 30,
  • "additional_service_time_reason": "handover_took_longer_as_planned",
  • "acknowledged_by": "Otto Normalverbraucher",
  • "signature_data_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

Response samples

Content type
application/json
{
  • "error": "Invalid auth_token"
}

Statuses

Record courier GPS information by creating a single status.

Protected resource. Authorization is required via auth_token.

Record a courier status

Record the courier's current GPS information. The courier's device calls this endpoint periodically to report its position, optionally tagged with an event marker and the stop the update relates to.

Recording is asynchronous: a valid request enqueues a background job that stores the courier position and always returns 201 with an empty body. If the location is missing, empty, or lacks a latitude or longitude, the request is still accepted with 201 but no position is recorded.

Protected resource. Authorization is required via auth_token.

Authorizations:
auth_token
query Parameters
auth_token
required
string
Example: auth_token=bf545b8e453536ee431648d86711243b

Authentication token of the courier.

Request Body schema: application/json
required
recorded_at
string <date-time>

Time at which the status was recorded on the device.

event
string

Optional marker describing what the courier was doing when the status was recorded (for example delivery_failed or on_stop_finalisation). Stored verbatim on the recorded position.

stop_uuid
string <uuid>

UUID of the stop this status relates to, if any.

object

GPS position reported by the courier's device. When present, both latitude and longitude must be supplied for the position to be recorded.

Responses

Request samples

Content type
application/json
{
  • "recorded_at": "2014-05-03T17:00:00Z",
  • "event": "on_stop_finalisation",
  • "stop_uuid": "6b887f5e-7db3-45ec-badc-b32bacb88071",
  • "location": {
    }
}

Response samples

Content type
application/json
{
  • "error": "Invalid auth_token"
}

Status Batches

Record courier GPS information by creating multiple statuses in a single request.

Protected resource. Authorization is required via auth_token.

Record a batch of courier GPS positions

Stores a batch of GPS positions reported by the courier's device. Each location is persisted as a courier position record, with an expiry date derived from recorded_at and the organization's configured GPS data persistence period.

Both recorded_at and a non-empty locations array must be present for any positions to be stored; otherwise the request still succeeds with 201 but no positions are recorded. The endpoint always returns an empty 201 response body.

This is a protected resource: authorization is required via the auth_token query parameter. A missing or invalid token results in a 401 response.

Authorizations:
auth_token
query Parameters
auth_token
required
string
Example: auth_token=bf545b8e453536ee431648d86711243b

Authentication token identifying the courier.

Request Body schema: application/json
required
recorded_at
string <date-time>

Timestamp at which the batch was recorded on the device. Used to compute the expiry date of the stored positions. If omitted, no positions are stored.

Array of objects (StatusBatchLocation)

GPS locations to store. May be empty or omitted, in which case no positions are recorded.

Responses

Request samples

Content type
application/json
{
  • "recorded_at": "2014-05-03T17:00:00Z",
  • "locations": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "Invalid auth_token"
}

Activities

Record when the courier is navigating to a stop and when they have started fulfilling jobs at the stop location. Records the type of action the courier is performing.

Protected resource. Authorization is required via auth_token.

Record a courier activity

Records a courier activity against a stop, capturing when the courier starts navigating to the stop (navigation_start) and when the courier starts fulfilling the jobs at the stop location (task_start).

The activity is always attributed to the authenticated courier; the courier cannot be supplied in the request body.

This is a protected resource: authorization is required via the auth_token query parameter. A missing or invalid token results in a 401 response.

On success the endpoint responds with 201 Created and an empty body. If the stop_uuid does not reference an existing stop, or a required attribute is missing, the request is rejected with 422 and a list of validation errors.

Authorizations:
auth_token
query Parameters
auth_token
required
string
Example: auth_token=bf545b8e453536ee431648d86711243b

Authentication token identifying the courier.

Request Body schema: application/json
required
action
required
string
Enum: "navigation_start" "task_start"

The type of action the courier is performing. navigation_start marks the start of navigation towards the stop; task_start marks the start of job fulfillment at the stop location.

recorded_at
required
string <date-time>

When the action was recorded on the device. For online activities this is typically close to the server time; for offline activities it is the time the action originally occurred on the device.

stop_uuid
required
string <uuid>

UUID of the stop the activity belongs to. Must reference an existing stop, otherwise the request is rejected with 422.

offline
boolean
Default: false

Whether the action was recorded while the device was offline and is being submitted after the fact. Defaults to false.

Responses

Request samples

Content type
application/json
{
  • "action": "task_start",
  • "recorded_at": "2014-05-03T17:00:00Z",
  • "stop_uuid": "6b887f5e-7db3-45ec-badc-b32bacb88071",
  • "offline": true
}

Response samples

Content type
application/json
{
  • "error": "Invalid auth_token"
}

Performance

Show the performance of a courier. The API sends data in order: today, the current month, and the remaining eleven months. If a period has no data, its statistics are not sent.

Show the courier's performance

Returns the authenticated courier's performance statistics, aggregated per reporting period. The response is an array of period objects sent in a fixed order: today first, then current_month, then up to eleven preceding months (lowercased English month names). Periods with no qualifying orders are omitted from the array.

Only orders that belong to a tour and have reached a state with a pickup or delivery attempt (pickup_failed, delivered, delivery_failed, or returned) are counted. Ad-hoc orders and orders worked by another courier are not included.

Each period reports:

  • number_of_tours - the number of distinct tours worked.
  • pickups - the fraction of attempted pickups that were on time.
  • deliveries - the fraction of attempted deliveries that were on time.
  • hit_rate - the fraction of qualifying orders that were delivered.

Every metric carries a qualitative rating derived from its ratio: good when ratio >= 0.98, neutral when ratio >= 0.94, otherwise bad.

Note: protected resource. Authorization is required via auth_token.

Authorizations:
auth_token
query Parameters
auth_token
required
string

Courier authentication token.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Show the current courier's data consent

Returns the data-sharing and privacy consent flags for the authenticated courier.

This is a protected resource: authorization is required via the auth_token query parameter. A missing, invalid, or inactive token results in a 401 response.

Note: A 404 is returned when the courier has never given consent (no consent record exists yet).

Authorizations:
auth_token
query Parameters
auth_token
required
string
Example: auth_token=bf545b8e453536ee431648d86711243b

Authentication token identifying the courier.

Responses

Response samples

Content type
application/json
{
  • "share_with_receiver_sender": true,
  • "share_with_employer_client": true,
  • "share_with_tiramizoo_analytics": true,
  • "accept_data_and_privacy_policies": true
}

Update the current courier's data consent

Creates or updates the authenticated courier's data-sharing and privacy consent flags. If no consent record exists yet, one is created; otherwise the existing record is updated. All flags are optional and only the supplied ones are changed.

This is a protected resource: authorization is required via the auth_token query parameter. A missing, invalid, or inactive token results in a 401 response.

Note: A 422 is returned when the consent record is not valid (for example, when share_with_receiver_sender or accept_data_and_privacy_policies are not true).

Authorizations:
auth_token
query Parameters
auth_token
required
string
Example: auth_token=bf545b8e453536ee431648d86711243b

Authentication token identifying the courier.

Request Body schema: application/json
required
share_with_receiver_sender
boolean

Whether the courier consents to sharing data with the delivery's receiver and sender.

share_with_employer_client
boolean

Whether the courier consents to sharing data with their employer and client.

share_with_tiramizoo_analytics
boolean

Whether the courier consents to sharing data to improve the app (for example, better routes).

accept_data_and_privacy_policies
boolean

Whether the courier accepts the data and privacy policies.

Responses

Request samples

Content type
application/json
{
  • "share_with_receiver_sender": true,
  • "share_with_employer_client": true,
  • "share_with_tiramizoo_analytics": true,
  • "accept_data_and_privacy_policies": true
}

Response samples

Content type
application/json
{
  • "share_with_receiver_sender": true,
  • "share_with_employer_client": true,
  • "share_with_tiramizoo_analytics": true,
  • "accept_data_and_privacy_policies": true
}

Organization

Show details of the organization the courier belongs to, including contact information and enabled feature flags.

Show details of the organization

Returns public configuration of the courier's organization: support contact details and the state of the feature settings relevant to the courier app.

Note: this endpoint is public. Unlike most courier endpoints it does not require authentication, so the auth_token query parameter is optional. The organization is resolved from the request host.

The response is compacted, so keys whose underlying value is null are omitted from the body.

Authorizations:
auth_tokenNone
query Parameters
auth_token
string

Courier authentication token. Optional for this endpoint.

Responses

Response samples

Content type
application/json
{
  • "organization_email": "support@tiramizoo.com",
  • "organization_phone_number": "+49.89 21556870",
  • "organization_name": "Tiramizoo",
  • "organization_return_additional_service_time_reasons": [
    ],
  • "joinable_tours": false,
  • "code_joinable_tours": false,
  • "loading_without_tour_enabled": false,
  • "whatsapp_messaging_enabled": false,
  • "tracking_distance_enabled": false
}

Tour Plan Packages

Return the list of packages for each tour in the current tour plan. This allows packages to be sorted by courier, because when scanning a package the courier knows which tour plan it belongs to.

This resource is only enabled if the POST /courier_api/v1/auth response returns the flag packages_by_tour_access: true.

Protected resource. Authorization is required via auth_token.

List packages grouped by tour for a stop's tour plan

Returns the list of packages for each tour in the tour plan that the given stop belongs to. This lets couriers sort packages per tour while scanning, because each scanned package can be matched to the tour it belongs to.

The stop is identified by the stop_uuid query parameter and must be one of the authenticated courier's unfinished stops. If the stop does not originate from a tour plan (for example, an ad-hoc mobile tour), an empty array is returned.

Note: this resource is only available when the organization has the packages_by_tour_access setting enabled. When the setting is disabled the endpoint responds with 404 Not Found.

Note: protected resource. Authorization is required via auth_token.

Authorizations:
auth_token
query Parameters
auth_token
required
string

Courier authentication token.

stop_uuid
required
string

UUID of one of the courier's unfinished stops. Used to resolve the tour plan whose packages are returned.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]