PostNL Timeframes API

Retrieve available delivery timeframes for an address (v2_1).

GitHub OpenAPI

Operations 1

GET /shipment/v2_1/calculate/timeframes Retrieve expected delivery timeframes #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/postnl:timeframes-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

postnl-timeframes-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Timeframes API
  description: Calculate expected delivery timeframes based on selected delivery options
  version: v2_1
servers:
- url: https://api-sandbox.postnl.nl
  description: Non-Production server
- url: https://api.postnl.nl
  description: Production server
security:
- APIKeyHeader: []
tags:
- name: Timeframes
paths:
  /shipment/v2_1/calculate/timeframes:
    get:
      tags:
      - Timeframes
      summary: Retrieve expected delivery timeframes
      description: 'Request example:

        ```

        curl -X GET "https://api-sandbox.postnl.nl/shipment/v2_1/calculate/timeframes?AllowSundaySorting=false&StartDate=30-06-2022&EndDate=02-07-2022&CountryCode=NL&PostalCode=2132WT&HouseNumber=42&HouseNrExt=A&City=Hoofddorp&Street=Siriusdreef&Options=Daytime%2CEvening" \

        -H "Accept: application/json" \

        -H "apikey: APIKEY-HERE" \

        ```'
      operationId: RetrieveDeliveryTimeframes
      security:
      - APIKeyHeader: []
      parameters:
      - name: AllowSundaySorting
        in: query
        description: Whether or not the requesting party allows for Sunday sorting (which leads to delivery on Monday).
        required: true
        schema:
          type: boolean
          example: false
      - name: StartDate
        in: query
        description: 'Date of the beginning of the timeframe. Format: dd-MM-yyyy'
        required: true
        schema:
          pattern: ^([0-3]\d-[0-1]\d-[1-2]\d{3})$
          type: string
          example: 30-06-2022
      - name: EndDate
        in: query
        description: Date of the enddate of the timeframe. Format:dd-MM-yyyy. Enddate may not be before StartDate.
        required: true
        schema:
          pattern: ^([0-3]\d-[0-1]\d-[1-2]\d{3})$
          type: string
          example: 02-07-2022
      - name: CountryCode
        in: query
        description: The ISO2 country code of the delivery address
        required: true
        schema:
          type: string
          example: NL
          enum:
          - NL
          - BE
      - name: PostalCode
        in: query
        description: Zipcode of the delivery address
        required: true
        schema:
          pattern: ^[0-9]{4}([A-Z]{2})?$
          type: string
          example: 2132WT
      - name: HouseNumber
        in: query
        description: The house number of the delivery address
        required: true
        schema:
          type: integer
          example: 42
      - name: HouseNrExt
        in: query
        description: House number extension of the delivery address
        schema:
          type: string
          example: A
      - name: City
        in: query
        description: City of the delivery address
        schema:
          type: string
          example: Hoofddorp
      - name: Street
        in: query
        description: The street name of the delivery address
        schema:
          type: string
          example: Siriusdreef
      - name: Options
        in: query
        description: The delivery options for which expected timeframes should be calculated. At least one delivery option must be specified. Multiple values should be comma-separated.
        required: true
        style: form
        explode: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/timeframeOptions'
          example:
          - Daytime
          - Evening
          - Sunday
      responses:
        '200':
          description: Calculated delivery timeframes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/timeframeResponse'
              example:
                Timeframes:
                  Timeframe:
                  - Date: 02-07-2022
                    Timeframes:
                      TimeframeTimeframe:
                      - From: '12:30:00'
                        Options:
                          string: Daytime
                        To: '14:30:00'
                        Sustainability:
                          Code: '02'
                          Description: Sustainable option
                ReasonNoTimeframes:
                  ReasonNoTimeframe:
                  - Code: '1'
                    Date: 02-07-2022
                    Description: Delivery date not allowed
                    Options:
                      string: Evening
                    Sustainability:
                      Code: '02'
                      Description: Sustainable option
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequest'
              example:
                Date: '2024-06-18T13:25:02.711Z'
                Error:
                  ErrorCode: '3000'
                  ErrorDescription: Request format is invalid
                RequestId: 09fd61fe-0099-4349-b71d-dce5c2472be9
        '401':
          description: Invalid apikey
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
              example:
                message: Failed to resolve API Key variable 'request.header.apikey'
                http_status_code: 401
        '405':
          description: Method not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowedOnlyGetPost'
              example:
                message: Only GET & POST requests allowed
                http_status_code: 405
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests'
              example:
                message: Too many requests. Rate limit exceeded!
                http_status_code: 429
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
              example:
                fault:
                  faultstring: Unexpected token in object literal
                  detail:
                    errorcode: Validation Fault
components:
  schemas:
    timeframesResponseObject:
      type: object
      properties:
        TimeframeTimeframe:
          type: array
          items:
            type: object
            properties:
              From:
                type: string
                description: The start time of the expected delivery window
                example: '12:30:00'
              Options:
                type: object
                description: The delivery option for which the timeframe is calculated. See [Delivery Options](https://developer.postnl.nl/docs/#/http/reference-data/reference-codes/delivery-options) for possible values.
                properties:
                  string:
                    type: string
                    enum:
                    - Daytime
                    - Today
                    - Sameday
                    - Evening
                    - Morning
                    - Noon
                    - Sunday
                    - Afternoon
                    example: Daytime
              To:
                type: string
                description: The end time of the expected delivery window
                example: '14:30:00'
              Sustainability:
                type: object
                description: Sustainability score; see [Sustainability codes](https://developer.postnl.nl/docs/#/http/reference-data/reference-codes/sustainability-codes) for possible values.
                properties:
                  Code:
                    type: string
                    description: Sustainability score code
                    example: '02'
                    enum:
                    - '00'
                    - '01'
                    - '02'
                    - '03'
                  Description:
                    type: string
                    description: Sustainability score code description
                    example: Sustainable option
    InvalidRequest:
      type: object
      properties:
        Date:
          type: string
          format: date-time
        Error:
          type: object
          properties:
            ErrorCode:
              type: string
              example: '3000'
            ErrorDescription:
              type: string
              example: Request format is invalid
        RequestId:
          type: string
          example: 09fd61fe-0099-4349-b71d-dce5c2472be9
    timeframeResponse:
      type: object
      properties:
        Timeframes:
          type: object
          properties:
            Timeframe:
              type: array
              description: A calculated delivery timeframe
              items:
                type: object
                properties:
                  Date:
                    type: string
                    description: The expected date of delivery
                    example: 02-07-2022
                  Timeframes:
                    $ref: '#/components/schemas/timeframesResponseObject'
        ReasonNoTimeframes:
          type: object
          properties:
            ReasonNoTimeframe:
              type: array
              description: The reason why no timeframe was returned
              items:
                type: object
                properties:
                  Code:
                    type: string
                    description: The reason code
                    example: '1'
                  Date:
                    type: string
                    description: The date associated with the reason no timeframe was calculated
                    example: 02-07-2022
                  Description:
                    type: string
                    description: The description associated with the reason no timeframe was calculated
                    example: Delivery date not allowed
                  Options:
                    $ref: '#/components/schemas/NoTimeframesOptions'
                  Sustainability:
                    type: object
                    description: Sustainability score; see [Sustainability codes](https://developer.postnl.nl/docs/#/http/reference-data/reference-codes/sustainability-codes) for possible values.
                    properties:
                      Code:
                        type: string
                        description: Sustainability score code
                        example: '02'
                        enum:
                        - '00'
                        - '01'
                        - '02'
                        - '03'
                      Description:
                        type: string
                        description: Sustainability score code description
                        example: Sustainable option
    Unauthorized:
      type: object
      properties:
        message:
          type: string
          example: Failed to resolve API Key variable 'request.header.apikey'
        http_status_code:
          type: number
          example: 401
    InternalServerError:
      type: object
      properties:
        fault:
          type: object
          properties:
            faultstring:
              type: string
              example: Unexpected token in object literal
            detail:
              type: object
              properties:
                errorcode:
                  type: string
                  example: Validation Fault
    timeframeOptions:
      type: string
      enum:
      - Daytime
      - Today
      - Sameday
      - Evening
      - Morning
      - Noon
      - Sunday
      - Afternoon
    NoTimeframesOptions:
      type: object
      description: The option for which no timeframe was calculated for a specific date
      properties:
        string:
          type: string
          enum:
          - Daytime
          - Today
          - Sameday
          - Evening
          - Morning
          - Noon
          - Sunday
          - Afternoon
          example: Evening
    TooManyRequests:
      type: object
      properties:
        message:
          type: string
          example: Too many requests. Rate limit exceeded!
        http_status_code:
          type: number
          example: 429
    MethodNotAllowedOnlyGetPost:
      type: object
      properties:
        message:
          type: string
          example: Only Get & POST requests allowed
        http_status_code:
          type: number
          example: 405
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      name: apikey
      in: header