print-one Address API

openapi: 3.2.0
info:
  title: Print.one Address API
  description: 'This documentation belongs to Print.one''s API. # Introduction

    This API is documented in **OpenAPI format**. In addition to standard

    OpenAPI syntax we use a few vendor extensions


    For technical information about our API, please consult our help center or request support. # Cross-Origin Resource Sharing

    This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with W3C spec. And that allows cross-domain communication from the browser. All responses have a wildcard same-origin which makes them completely public and accessible to everyone, including any code on any site. # Authentication


    # Early Access

    Some features are marked as ''Early Access''. This means only a small portion of users have access to these features. We do this to conduct thorough testing before a major release. Would you like to gain access to one of our Early Access features? Please raise a >">support ticket here, specifying which feature you would like access to. # Premium Access

    Some features are marked as ''Premium''. This means this feature is only included on paid plans. Would you like to gain access to one of our Premium features? Have a look at the Subscriptions page. # API Errors

    Below is a list with all known errors returned by our API, identified by a unique `code`. These codes will also show in the error response of specific API responses. Unique code

    Error name

    Error type

    Example message


    10001

    InvalidInputData

    Combined

    Invalid input data


    10002

    OrderPropertyRequired

    Default

    The property recipient is required


    10003

    OrderCreationError

    Combined

    Could not create order


    10004

    RecipientAddressInvalid

    Default

    Recipient''s address is invalid


    10005

    AddressValidation

    Validation

    Address validation failed


    10006

    ResourceNotFound

    Default

    Campaign ''cmp_123456789'' does not exist


    10007

    BatchWrongMode

    Default

    Batch is ''live'', but received a ''live'' request


    10008

    BatchNotAcceptingOrders

    Default

    Batch ''batch_123456789'' is not in a state to accept orders


    10009

    BatchIsFull

    Default

    Batch ''batch_123456789'' is full and does not accept any more orders (max 10000 orders per batch)


    10010

    ArchivedCampaignNotAcceptingOrders

    Default

    Campaign ''My Campaign'' is archived and no longer accepts orders


    10011

    ProductFeatureNotAllowed

    Default

    The product ''GREETINGCARD_SQ15'' does not support batch


    10012

    ObjectMissingRequiredFields

    Default

    The recipient is missing required fields


    10013

    CannotRetrieveObject

    Default

    An error occurred while retrieving the design ''tmpl_123456798''


    10014

    DesignContentUnparsable

    Combined

    Could not parse the design content


    10015

    FormatPageRequirement

    Default

    The format ''POSTCARD_A5'' requires 2 pages, but 1 was provided


    10016

    DuplicateDesignPage

    Default

    Found page ''1'' multiple times in the design


    10017

    CountryNotSupported

    Default

    The country ''BE'' is not supported


    10018

    ProductDestinationNotAllowed

    Default

    The product ''GREETINGCARD_SQ15'' does not support GERMANY


    10019

    UnknownCreationError

    Default

    An unknown error occurred while creating the campaign


    10020

    UnknownPublishError

    Default

    An unknown error occurred while publishing the order


    10021

    SendDateInPast

    Default

    The send date must be in the future


    10022

    SendDateBeyondYear

    Default

    The send date must be within one year


    10023

    InstallNotAllowed

    Default

    You are not allowed to install this integration


    10024

    BatchRecipientCountryRestriction

    Default

    Only addresses shipped to ''NL'' are allowed for this batch


    10025

    PostalStampCountryUnavailable

    Default

    Postal stamp ''stmp_123456789'' is not available for the country ''BE''


    10026

    EarlyAccessRestricted

    Default

    Sorry, some-early-access-feature is in early access.'
  version: v3
  contact:
    name: Print.one
    url: https://support.print.one
    email: info@print.one
servers:
- url: https://api.print.one
tags:
- name: Address
  x-premiumAccess: true
paths:
  /v3/address/validate:
    post:
      operationId: Address/validateAddress
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateAddressRequestDto'
      responses:
        '200':
          description: Address validation result
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/V3ResponseDto'
                - properties:
                    data:
                      type: object
                      $ref: '#/components/schemas/ValidateAddressResponseDto'
        '403':
          description: Request has invalid grant scope, missing one of (<code>global.address.validate.read</code>)
        '404':
          description: Country 'Unknown' does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ErrorResponse76cc3d5ebeeb68a27b1721e4134e7ee183c275ce20ac85352496bf60a3da0978'
      security:
      - API Key: []
      - Oauth2:
        - live.orders.write
        - live.api.key
      tags:
      - Address
      summary: Address/validate address
      x-summary-source: derived
  /v3/address/auto-complete:
    post:
      operationId: Address/autoCompleteAddress
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoCompleteAddressRequestDto'
      responses:
        '403':
          description: Request has invalid grant scope, missing one of (<code>global.address.validate.read</code>)
      security:
      - API Key: []
      - Oauth2:
        - live.orders.write
        - live.api.key
      tags:
      - Address
      summary: Address/auto complete address
      x-summary-source: derived
components:
  schemas:
    ValidAddressDto:
      type: object
      properties:
        address:
          type: string
          description: The validated address
          example: Eekwal 3b
        postalCode:
          type: string
          description: The postal code of the address
          example: 8011LD
        city:
          type: string
          description: The city of the address
          example: Zwolle
        country:
          type: string
          description: The country of the address
          example: NL
        destination:
          type: string
          description: The calculated destination of the address
          example: INTERNATIONAL
          enum:
          - NETHERLANDS
          - GERMANY
          - INTERNATIONAL
      required:
      - address
      - postalCode
      - city
      - country
      - destination
    ValidateAddressRequestDto:
      type: object
      properties:
        country:
          type: string
          description: The country ISO code the address is in
          example: NL
        postalCode:
          type: string
          description: The postal code of the address
          example: 8011LD
        address:
          type: string
          description: The address to validate
          example: Eekwal 3b
        city:
          type: string
          description: The city of the address
          example: Zwolle
      required:
      - country
      - postalCode
      - address
      - city
    V3ErrorResponse76cc3d5ebeeb68a27b1721e4134e7ee183c275ce20ac85352496bf60a3da0978:
      type: object
      properties:
        status:
          type: number
          description: HTTP status code associated with the error message
          example: 404
        message:
          type: string
          description: Message describing the error
          example: Country 'Unknown' does not exist
        code:
          type: number
          description: Unique code to backtrace the type of error
          example: 10006
        uri:
          type: string
          description: The requested URL
          example: https://api.print.one/v3/some-url?filter.query=$eq:value
      required:
      - status
      - message
      - code
      - uri
    V3ResponseDto:
      type: object
      properties:
        data:
          type: object
      required:
      - data
    ValidateAddressResponseDto:
      type: object
      properties:
        valid:
          type: boolean
          description: Whether the address is valid
          example: true
        address:
          description: The validated address
          allOf:
          - $ref: '#/components/schemas/ValidAddressDto'
        error:
          type: object
          description: If the address is not valid, this will contain the error message
          nullable: true
      required:
      - valid
      - address
      - error
    AutoCompleteAddressRequestDto:
      type: object
      properties:
        country:
          type: string
          description: The country ISO code the address is in
          example: NL
        postalCode:
          type: string
          description: The postal code of the address
          example: 8011LD
        street:
          type: string
          description: The street name of the address
          example: Eekwal
        houseNumber:
          type: string
          description: The house number of the address
          example: '3'
        houseNumberAddition:
          type: string
          description: The addition to the house number of the address
          example: A
        city:
          type: string
          description: The city of the address
          example: Zwolle
      required:
      - country
  securitySchemes:
    API_Key:
      type: apiKey
      in: header
      name: x-api-key
    Oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://api.print.one/v2/oauth/authorize
          refreshUrl: https://api.print.one/v2/oauth/token
          scopes:
            coupons.read: coupons.read
            coupons.write: coupons.write
            shorten.urls.read: shorten.urls.read
            shorten.urls.write: shorten.urls.write
            campaign.read: campaign.read
            campaign.write: campaign.write
            campaign.delete: campaign.delete
            company.read: company.read
            customfile.read: customfile.read
            customfile.write: customfile.write
            live.orders.read: live.orders.read
            live.orders.write: live.orders.write
            test.orders.read: test.orders.read
            test.orders.write: test.orders.write
            draft.orders.read: draft.orders.read
            draft.orders.write: draft.orders.write
            template.read: template.read
            template.write: template.write
            webhooks.read: webhooks.read
            webhooks.write: webhooks.write
            integrations.read: integrations.read
            tracking.event.read: tracking.event.read
            tracking.event.write: tracking.event.write
            live.batches.read: live.batches.read
            live.batches.write: live.batches.write
            test.batches.read: test.batches.read
            test.batches.write: test.batches.write
            tenant.admin: tenant.admin
            live.api.key: live.api.key
            test.api.key: test.api.key
          tokenUrl: https://api.print.one/v2/oauth/token
      name: Oauth2 Bearer Token