API

This part of the documentation describes how to communicate directly with the MyParcel.com REST API. For convenience, it is advised that you use the MyParcel.com PHP-SDK whenever possible. If you think you are ready to dive right in, but just want to see all the available resources in more detail you can look at the API resources. For more structural details and examples of the endpoints see the MyParcel.com OpenAPI specification.

Getting Started

This section is devoted to give you a little introduction to the JSON API specification. This specification defines how resources should be requested and responses should be formatted. In case you are not familiar with this specification, you will find a reference with some pointers as a quick crash course below.

MIME type

The JSON API specification describes its own media type: application/vnd.api+json. This should be used whenever you include the Content-Type or Accept headers. These headers are not mandatory, since the MyParcel.com API will default to application/vnd.api+json when no headers are specified.

Some endpoints offer exceptions where you are deliberately requesting other file formats. For example when requesting label files, you could use Accept: application/pdf.

Document Structure

Requests to and responses from the API always have the following structure:

  • A root JSON object with at least 1 of the following:

    • data: the documents “primary data”, always either an object, array or null

    • errors: an array of error objects

    • meta: a meta object that contains non-standard meta-information

For example, the response from the API root:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
    "meta": {
        "title": "MyParcel.com API",
        "status": "OK"
    },
    "links": {
        "docs": "https://docs.myparcel.com",
        "specification": "https://api-specification.myparcel.com"
    }
}

Note

The data and errors top-level attributes cannot coexist in the same document.

Pagination query parameters

These are the query parameters used for pagination:

Parameter

Description

Value

Default

page[size]

Determines how many records to retrieve per page

Any number higher than 0 and lower than or equal to the max record size

100

page[number]

Indicates from which page the records should be retrieved

Any number higher than 0

1

Together, these parameters will cause the API to return a specific range of resources based on your input. For example, a combination of page[size]=8 and page[number]=3 will retrieve 8 records: number 17 to 24.

When an unsupported value (-1 for example) is used for one of the parameters the default value will be used instead. If a positive page number is used that is higher than the amount of existing pages, the API won’t be able to find any records and will simply return an empty array.

Max record size

The default max record size is 100.

Errors

If the top-level errors attribute exists, it can contain one of the following errors:

Error code

Error number

Description

NOT_FOUND

10000

The requested endpoint could not be found.

INTERNAL_SERVER_ERROR

10001

An internal server error has occurred, this is usually a problem on the MyParcel.com end. Please contact support if it persists.

RESOURCE_NOT_FOUND

10002

The resource you are trying to get the data of could not be found.

INVALID_JSON_SCHEMA

10003

The request does not conform to the MyParcel.com API specification.

INVALID_REQUEST_HEADER

10004

One or more of your request headers is invalid.

RESOURCE_CANNOT_BE_MODIFIED

10005

Either this resource can’t be modified or you do not have permission to modify this resource.

INVALID_ERROR_SCHEMA

10006

An error was thrown during the request to an external source. No more information can be provided since the returned error was improperly formatted.

RESOURCE_CONFLICT

10007

The type or id of one of the resources was not computable or the resource id is not valid.

UNPROCESSABLE_ENTITY

10008

The server understands the content type and the syntax is correct, but the server was unable to process the contained instructions.

MISSING_BILLING_INFORMATION

11000

In order to complete this request, some missing billing information should be provided first.

EXTERNAL_REQUEST_ERROR

13001

An error occurred while making a request to an external service. When available, details can be found in the meta of the response.

CARRIER_API_ERROR

13002

There was a problem with the request to the carrier. The original response can be found in the meta under carrier_response.

AUTH_INVALID_CLIENT

14000

The supplied client credentials are invalid or the client does not have access to this grant type.

AUTH_INVALID_SCOPE

14001

The requested scope is not available for your client.

AUTH_INVALID_TOKEN

14002

The provided access token does not seem to be valid.

AUTH_MISSING_TOKEN

14003

An access token is required but no access token was provided.

AUTH_MISSING_SCOPE

14004

The used access token does not contain the required scope(s).

AUTH_SERVER_EXCEPTION

14050

Unable to process the OAuth request. This is a generic OAuth error with no direct known cause. Please contact support if the problem persists.

The error responses conform to the JSON API standard. For more information about what they might contain, visit the errors section of the specification.

Further Reading

If you would like to dive deep into the fundamentals of the JSON API specification or the MyParcel.com API specification, you can do so following the links below.