Carriers
========

A carrier resource represents one of the many postal carriers that MyParcel.com works with to provide you with a broad range of :doc:`contracts </api/resources/contracts>`. This endpoint can be used to get a list of the postal carriers we support that the client can access.
Carriers are included as relationships of :doc:`services </api/resources/services>`, :doc:`contracts </api/resources/contracts>` and :doc:`pickup dropoff locations </api/resources/carrier-pudo-locations>`.

Carrier
-------

.. seealso::
    https://api-specification.myparcel.com/#tag/Carriers

==================  =======  ======================================================================================
Attribute           Type     Description
==================  =======  ======================================================================================
name                string   Carrier name, useful for displaying to users.
code                string   Unique slugified version of the carrier name.
logo_url            string   Url pointing to the carrier's logo.
credentials_format  object   The format of credentials for this carrier's contracts described using `JSON Schema <https://json-schema.org>`_.
label_formats       array    The label mime-type and size combinations this carrier offers for shipments.
collections         object   Information about the carrier's collection services.
==================  =======  ======================================================================================

The ``collections`` attribute
-----------------------------

The ``collections`` attribute is an object containing two properties:

==================================================  =======  ===================================================================================
Property                                            Type     Description
==================================================  =======  ===================================================================================
offers_collections                                  boolean  Indicates whether this carrier offers collections.
voids_registered_collections                        boolean  Indicates whether the carrier supports voiding of registered collections.
allows_adding_registered_shipments_to_collection    boolean  Indicates whether the carrier supports adding registered shipments to a collection.
==================================================  =======  ===================================================================================

.. _carrier-endpoints:

Endpoints
---------

.. raw:: html

    <details>
        <summary><a>GET /carriers</a></summary>

Retrieving a list of carriers.

**Scope**

No scopes are required to retrieve carriers.

**Request**

.. code-block:: http

    GET /carriers HTTP/1.1
    Accept: application/vnd.api+json
    Example: https://api.sandbox.myparcel.com/carriers

**Response**

.. code-block:: json

    {
      "data": [
        {
          "type": "carriers",
          "id": "be7f6752-34e0-49a1-a832-bcc209450ea9",
          "attributes": {
            "name": "MyParcel.com",
            "code": "my-parcel-com",
            "logo_url": "https://cdn.myparcel.com/images/myparcelcom-black.svg",
            "credentials_format": {
              "additionalProperties": false,
              "required": [
                "api_user",
                "api_password"
              ],
              "properties": {
                "api_user": {
                  "type": "string"
                },
                "api_password": {
                  "type": "string"
                }
              }
            },
            "label_formats": [
              {
                "mime_type": "application/pdf",
                "size": "A6"
              }
            ],
            "collections": {
              "offers_collections": true,
              "voids_registered_collections": true,
              "allows_adding_registered_shipments_to_collection": true
            }
          },
          "links": {
            "self": "https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9"
          }
        }
      ],
      "meta": {
        "total_pages": 13,
        "total_records": 373
      },
      "links": {
        "self": "https://api.sandbox.myparcel.com/carriers?page[number]=3&page[size]=30",
        "first": "https://api.sandbox.myparcel.com/carriers?page[number]=1&page[size]=30",
        "prev": "https://api.sandbox.myparcel.com/carriers?page[number]=2&page[size]=30",
        "next": "https://api.sandbox.myparcel.com/carriers?page[number]=4&page[size]=30",
        "last": "https://api.sandbox.myparcel.com/carriers?page[number]=13&page[size]=30"
      }
    }

.. raw:: html

    </details>
    <details>
        <summary><a>GET /carriers/{carrier_id}</a></summary>

Retrieve a specific carrier.

**Scope**

No scopes are required to retrieve carriers.

**Request**

.. code-block:: http

    GET /carriers/{carrier_id} HTTP/1.1
    Accept: application/vnd.api+json
    Example: https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9

**Response**

.. code-block:: json

    {
      "data": {
        "type": "carriers",
        "id": "be7f6752-34e0-49a1-a832-bcc209450ea9",
        "attributes": {
          "name": "MyParcel.com",
          "code": "my-parcel-com",
          "logo_url": "https://cdn.myparcel.com/images/myparcelcom-black.svg",
          "credentials_format": {
            "additionalProperties": false,
            "required": [
              "api_user",
              "api_password"
            ],
            "properties": {
              "api_user": {
                "type": "string"
              },
              "api_password": {
                "type": "string"
              }
            }
          },
          "label_formats": [
            {
              "mime_type": "application/pdf",
              "size": "A6"
            }
          ],
          "collections": {
            "offers_collections": true,
            "voids_registered_collections": true,
            "allows_adding_registered_shipments_to_collection": true
          }
        },
        "links": {
          "self": "https://api.sandbox.myparcel.com/carriers/be7f6752-34e0-49a1-a832-bcc209450ea9"
        }
      }
    }

.. raw:: html

    </details>