Methods

All Methods

Pack Methods

Template Methods

Image Methods

  • moo.image.uploadImage - Upload an image from the application into the MOO image system for use in a Pack
  • moo.image.importImage - Imports an image into the MOO image system for use in a Pack from either a given HTTP URI or by directly sending a Base64 encoded stream of bytes

Text Methods

  • moo.text.measure - Returns the measurements (width, height, number of lines) that the supplied text will have once rendered in the given font

Common parameters

All methods support the following additional optional parameters:
  • errorsAsOK: boolean (default false) - If true then a 200 OK will be returned on errors, if false then a 500 will be returned.

Pack Methods

moo.pack.createPack

The moo.pack.createPack method creates a pack and returns an id that can be used in subsequent moo.pack.updatePack and moo.pack.getPack calls. If the product is invalid, an error is returned.

HTTP Method
  • POST
Authentication
  • "create" permission required - This permission is granted to all MOO API keys
  • OAuth authentication required - This call requires a signed 2-legged call
Parameters
  • method: string - moo.pack.createPack
  • product: string - The code of the product to be created. See Product Codes for a list of available products
  • pack: URI encoded Pack JSON - Optionally, the pack object data. See the Pack Object Model for more information on this object
  • trackingId: string - An optional API client provided string used to track API calls which result in order placement - max 255 characters. This will be stored in our DB if the customer places an order with this pack, and will be sent to you in an AJAX call from the MOO confirmation page if you have configured an Order Confirmation Callback URL. For more details, please see the Order Tracking documentation
  • friendlyName: string - An optional API client provided string as the default "name" of the pack, used to name the Pack if the user wishes to save it, to identify it when they add it to the cart, and in their order history. The user can rename their pack.
  • startAgainUrl: string - An optional API client provided absolute URL which will be used if the customer wishes to start their pack all over again from our Design Canvas page. Typically this should lead them back to the appropriate page in your application
  • physicalSpec: URI encoded Physical Specification JSON - Optionally, the physical specification of the pack. See the Physical Specification for more information on this object
  • includePhysicalSpec: boolean - If set to true then the response will include details of the physical specification of the Pack. This parameter is optional and defaults to false to preserve backward compatibility
  • designCode: string - If you have been given a design code, it can be provided here. Optional, defaults to null.

Example Request

POST /api/service/

method=moo.pack.createPack&product=businesscard

Example Response. For more information, see the Pack Object Model specification.

{
    "packId": "4f1d6939-546f-aa9aec3b-4f5e41f0-e093",  //The newly created Pack ID.
    "pack":{
        ... /* Pack data object */
    },
    "warnings": [
        ... /* Warnings array */
    ],
    "dropIns":{
        ... /* Available Drop-in string -> string map */
    },
    "physicalSpec": {
        ... /* Physical Specification object */
    }
}

moo.pack.createTrialPartnerPack

The moo.pack.createTrialPartnerPack method creates a partner trial pack and returns an id that can be used in subsequent moo.pack.updatePack and moo.pack.getPack calls. If the product is invalid, an error is returned. Partner trial packs require a partner ID, which you will be issued with if you are a MOO partner making use of trial packs.

Trial packs are limited to one per customer, and customers will recieve an error if they attempt to order more than one. If you intend to allow returning customers to order non-trial packs, you will need to call createPack method for those users, rather than createTrialPartnerPack. This means that your application will need to record which of your users have already requested a trial pack. Since this restriction applies only to users who have successfully purchased the trial pack, we recommend using an order confirmation callback to recieve notification of successful purchases.

The parameters and behaviour of createTrialPartnerPack are identical to those of moo.pack.createPack with the addition of a trialPartner parameter.

Authentication
  • "create_trial_pack" permission required - This permissions is granted to MOO partners
  • OAuth authentication required - This call requires a signed 2-legged call
Parameters
  • method: string - moo.pack.createTrialPartnerPack
  • product: string - The code of the product to be created. See Product Codes for a list of available products. Only businesscard and minicard are valid for trial partner packs.
  • pack: URI encoded Pack JSON - Optionally, the pack object data. See the Pack Object Model for more information on this object
  • trackingId: string - An optional API client provided string used to track API calls which result in order placement - max 255 characters. This will be stored in our DB if the customer places an order with this pack, and will be sent to you in an AJAX call from the MOO confirmation page if you have configured an Order Confirmation Callback URL. For more details, please see the Order Tracking documentation
  • friendlyName: string - An optional API client provided string as the default "name" of the pack, used to name the Pack if the user wishes to save it, to identify it when they add it to the cart, and in their order history. The user can rename their pack.
  • startAgainUrl: string - An optional API client provided absolute URL which will be used if the customer wishes to start their pack all over again from our Design Canvas page. Typically this should lead them back to the appropriate page in your application
  • physicalSpec: URI encoded Physical Specification JSON - Optionally, the physical specification of the pack. See the Physical Specification for more information on this object
  • includePhysicalSpec: boolean - If set to true then the response will include details of the physical specification of the Pack. This parameter is optional and defaults to false to preserve backward compatibility
  • trialPartner: string - Your trial partner ID.
  • designCode: string - If you have been given a design code, it can be provided here. Optional, defaults to null.

moo.pack.getPack

The moo.pack.getPack method returns the pack object for the specified id. If the id does not exist, an error is returned.

HTTP Method
  • GET
Authentication
  • "read" permission required - All API users have the ability to read packs created with their key, until the customer takes ownership of the pack using one of the drop-in URLs
  • OAuth authentication required - This call requires a signed 2-legged call
Parameters
  • method: string - moo.pack.getPack
  • packId: string - The id of the required pack
  • includePhysicalSpec: boolean - If set to true then the response will include details of the physical specification of the Pack. This parameter is optional and defaults to false to preserve backward compatibility

Example Request

GET /api/service/?method=moo.pack.getPack&packId=4f1d6939-546f-aa9aec3b-4f5e41f0-e093

Example Response. For more information, see the Pack Object Model specification.

{
    "packId": "4f1d6939-546f-aa9aec3b-4f5e41f0-e093",  //The Pack ID requested.
    "pack":{
        ... /* Pack data object */
    },
    "warnings": [
        ... /* Warnings array */
    ],
    "dropIns":{
        ... /* Available Drop-in string -> string map */
    },
    "physicalSpec": {
        ... /* Physical Specification object */
    }
}

moo.pack.getPhysicalSpec

The moo.pack.getPhysicalSpec method returns the physical specification object for the specified id. If the id does not exist, an error is returned.

HTTP Method
  • GET
Authentication
  • "read" permission required - All API users have the ability to read packs created with their key, until the customer takes ownership of the pack using one of the drop-in URLs
  • OAuth authentication required - This call requires a signed 2-legged call
Parameters
  • method: string - moo.pack.getPhysicalSpec
  • packId: string - The id of the required pack

Example Request

GET /api/service/?method=moo.pack.getPhysicalSpec&packId=4f1d6939-546f-aa9aec3b-4f5e41f0-e093

Example Response. For more information, see the Physical Specification.

{
    "packId": "4f1d6939-546f-aa9aec3b-4f5e41f0-e093",  //The Pack ID requested.
    "physicalSpec": {
        ... /* Physical Specification object */
    }
}

moo.pack.updatePack

The moo.pack.updatePack method updates a pack with the supplied pack. If the id does not exist, or the pack is invalid, an error is returned.

HTTP Method
  • POST
Authentication
  • "update" permission required - All API users have the ability to update packs created with their key, until the customer takes ownership of the pack using one of the drop-in URLs
  • OAuth authentication required - This call requires a signed 2-legged call
Parameters
  • method: string - moo.pack.updatePack
  • packId: string - The ID of the Pack to be updated
  • pack: URI encoded Pack JSON - The pack object data. See the Pack Object Model for more information on this object
  • friendlyName: string - An optional API client provided string as the default "name" of the pack, used to name the Pack if the user wishes to save it, to identify it when they add it to the cart, and in their order history. The user can rename their pack.
  • includePhysicalSpec: boolean - If set to true then the response will include details of the physical specification of the Pack. This parameter is optional and defaults to false to preserve backward compatibility

Example Request

POST /api/service/

method=moo.pack.updatePack&packId=4f1d6939-546f-aa9aec3b-4f5e41f0-e093&pack={}

Example Response. For more information, see the Pack Object Model specification.

{
    "packId": "4f1d6939-546f-aa9aec3b-4f5e41f0-e093",  //The Pack ID requested for the update
    "pack":{
        ... /* Pack data object */
    },
    "warnings": [
        ... /* Warnings array */
    ],
    "dropIns":{
        ... /* Available Drop-in string -> string map */
    },
    "physicalSpec": {
        ... /* Physical Specification object */
    }
}

moo.pack.updatePhysicalSpec

The moo.pack.updatePhysicalSpec method updates a pack with the supplied physical specification. If the id does not exist, or the pack is invalid, an error is returned.

HTTP Method
  • POST
Authentication
  • "update" permission required - All API users have the ability to update packs created with their key, until the customer takes ownership of the pack using one of the drop-in URLs
  • OAuth authentication required - This call requires a signed 2-legged call
Parameters
  • method: string - moo.pack.updatePhysicalSpec
  • packId: string - The ID of the Pack to be updated
  • physicalSpec: URI encoded Physical Specification JSON - The physical specification object. See the Physical Specification for more information on this object

Example Request

POST /api/service/

method=moo.pack.updatePhysicalSpec&packId=4f1d6939-546f-aa9aec3b-4f5e41f0-e093&physicalSpec={}

Example Response. For more information, see the Physical Specification specification.

{
    "packId": "4f1d6939-546f-aa9aec3b-4f5e41f0-e093",  //The Pack ID requested for the update
    "physicalSpec": {
        ... /* Physical Specification object */
    }
}

moo.pack.renderSide

The moo.pack.renderSide API call renders the data for a single side to a PNG and returns the PNG. If the side is invalid an error is returned.

HTTP Method
  • POST
Authentication
  • "render_side" permission required - Contact MOO if you would like to have this permission added to your account.
  • OAuth authentication required - This call requires a signed 2-legged call
Parameters
  • method: string - moo.pack.renderSide
  • side: URI encoded Side JSON. See the Pack Object Model for more information on this object.
  • imageBasket: URI encoded Image Basket JSON containing image basket items for at least all of the images in the side to be rendered. See the Pack Object Model for more information on this object.
  • boxType: string - What area of the side should be drawn. One of "bleed", "print" (default), "cut", or "safe".
  • maxSide: int - The size of the resulting image in pixels along its longest side. Defaults to 1024.
  • partial: boolean - If set to true, render only the supplied side data i.e. do not render default content from the associated template.
  • overlays: URI encoded array of sides to overlay on top of the rendered side. Useful for watermarks. Optional.

Example Request

POST /api/service/

method=moo.pack.renderSide&side={}&imageBasket={}

moo.pack.renderSideUrl

The moo.pack.renderSideUrl API call renders the data for a single side to a PNG and returns a URL to the image. The URL will be retrieveable with an HTTP GET request for up to 3 hours, and can be passed to the client. If the side is invalid an error is returned.

HTTP Method
  • POST
Authentication
  • "render_side" permission required - Contact MOO if you would like to have this permission added to your account.
  • OAuth authentication required - This call requires a signed 2-legged call
Parameters
  • method: string - moo.pack.renderSideUrl
  • side: URI encoded Side JSON. See the Pack Object Model for more information on this object.
  • imageBasket: URI encoded Image Basket JSON containing image basket items for at least all of the images in the side to be rendered. See the Pack Object Model for more information on this object.
  • boxType: string - What area of the side should be drawn. One of "bleed", "print" (default), "cut", or "safe".
  • maxSide: int - The size of the resulting image in pixels along its longest side. Defaults to 1024.
  • partial: boolean - If set to true, render only the supplied side data i.e. do not render default content from the associated template.
  • overlays: URI encoded array of sides to overlay on top of the rendered side. Useful for watermarks. Optional.

Example Request

POST /api/service/

method=moo.pack.renderSideUrl&side={}&imageBasket={}

Example Response..

http://www.moo.com/api/service/?method=moo.pack.getRenderedSide&id=4bfa807a624001df974c850f1ec9f748%7Cb99834bc19bbad24580b3adfa04fb947

Template Service Methods

moo.template.getTemplate

The moo.template.getTemplate method returns the template for the specified id. If the id does not exist, an error is returned.

HTTP Method
  • GET
Authentication
  • "get_template" permission required - All API accounts are granted this permission
  • OAuth authentication OPTIONAL - This call will succeed with or without a signed call
Parameters
  • method: string - moo.template.getTemplate
  • templateCode: string - The code of the Template to be returned as XML

Example Request

GET /api/service/?method=moo.template.getTemplate&templateCode=businesscard_front_variable_full

Example Response. For more information, see the Template Object Model specification.

<?xml version="1.0" encoding="UTF-8"?>

   ...

Image Service Methods

The methods moo.image.importImage and moo.image.uploadImage can be used to create images in the MOO filestore for later use in other API methods such as moo.pack.createPack, moo.pack.updatePack and moo.pack.addToBasket. Importing and uploading images are useful when use of static public URLs to reference images is not possible or is undesirable. The right image method to use depends upon how the source images is stored and/or generated.

Images must be one of the following types:

  • PNG - Unfortunately, we don't currently support the PNG-24 format at the moment I'm afraid. We also don't support image transparency within PNGs. For transparency, use PDFs (or embed the PNG within a PDF document)
  • JPEG - The higher compression quality the better for JPEGs.
  • PDF - We support PDFs as "images". Note that not all features of the PDF standard are supported. Contact MOO if you have any questions about the use of a PDF in your application
  • GIF - while we accept GIF images, we strongly discourage them as the quality will likely be poor when printed in most cases

moo.image.uploadImage

The moo.image.uploadImage method uploads and adds the image data to the MOO image store and returns an Image Item Basket Item object. This should be used for most images being supplied by your application. The rights on the images uploaded to MOO are unaffected - we will only use the images for the purposes of producing the printed product you order.

HTTP Method
  • multipart form POST
Authentication
  • NOT ALLOWED - "upload_image" permission is granted to all requests.- OAuth is often rather vague about how to sign multipart forms, and Flash applications have some issues in certain browsers with maintaining cookies and the like for multipart form posts. As a result, this call an be unauthenticated.
Parameters
  • method: string - moo.image.uploadImage
  • imageType: string (optional, default "unknown") - the type of image, used to decide if image enhancement should be used by default. Valid values are "unknown", "photo", "lineart" or "detect". Detect will enable our photo detection system to establish the type of image, photo will enable enhancement by default, and unknown will disable enhancement by default. Currently lineart is equivalent to unknown, but this may change in the future.
  • name: string (optional) the name of the image
  • source: string (optional) the source of the image
  • imageFile: multipart file upload - the binary data should be passed as a multipart field called "imageFile"

Example Request

POST /api/service/

method=moo.image.uploadImage

Example Response. For more information, see the Pack Object Model specification.

{
    "imageBasketItem":{
        ...
        "items":[
            ...
        ]
    },
    "uploadImageError": null,
    "warnings": [
    	...
    ]
}
  • The uploadImageError property will be provided if there was a problem with the image which caused us to reject it outright.
  • The warnings property will be provided if we successfully uploaded the image, but with some caveats (such as small resolution). The warning structure is of the form:
    		{
    		    "code":"EXAMPLE_001", //Code
    		    "message": "Image is low resolution", //Message associated with the code
    		    "reason": "Image is only 932x132px" //A more detailed reason specific to this particular case, where possible
    		}
    		

moo.image.importImage

The moo.image.importImage method uploads and adds the image data to the MOO image store and returns an Image Item Basket Item object.

HTTP Method
  • POST
Authentication
  • "import_image" permission is required.- Contact MOO if you would like to have this permission added to your account
  • OAuth authentication required - This call requires a signed 2-legged call
Parameters
  • method: string - moo.image.uploadImage
  • imageType: string (optional, default "unknown") - the type of image, used to decide if image enhancement should be used by default. Valid values are "unknown", "photo", "lineart" or "detect". Detect will enable our photo detection system to establish the type of image, photo will enable enhancement by default, and unknown will disable enhancement by default. Currently lineart is equivalent to unknown, but this may change in the future.
  • name: string (optional) the name of the image
  • source: string (optional) the source of the image
  • imageUrl: string - HTTP accessible URI to get the image
  • bytes: string - Base64 encoded string of image data to be imported into the MOO system. If supplied, this will override any value provided in the imageUrl parameter.

Example Request

POST /api/service/

method=moo.image.importImage&imageUrl=http://example.com/image1.jpeg

Example Response. For more information, see the Pack Object Model specification.

{
    "imageBasketItem":{
        ...
        "items":[
            ...
        ]
    }
}

Text Service Methods

moo.text.measure

The moo.text.measure method returns the measurements (width, height, number of lines) that the supplied text will have once rendered in the given font.

HTTP Method
  • GET
Authentication
  • No authentication required.
Parameters
  • method: string - moo.text.measure
  • text: string - the text to measure
  • fontSize: float - the font size of the text
  • fontSizeUnits: string - the units of the font size being provided. One of "mm" or "pt"
  • font: string - the font spec (in JSON format), which specifies the font family and whether the text is bold/italic. Example font spec: {"fontFamily":"avantgarde","bold":false,"italic":false}
  • wrappingWidth: float - the width in mm after which the text should wrap to a new line.
  • leading: float - required if and only if the wrappingWidth parameter is provided. The line spacing as a factor of the default line spacing (for example a value of 2.0 will increase the line spacing to double the default).

Example Request

GET /api/service/?method=moo.text.measure&text=exampleText&fontSize=15&fontSizeUnits=pt&font={"fontFamily":"avantgarde","bold":false,"italic":false}&wrappingWidth=40.0&leading=1.0

Example Response.

{
    "textWidth": 40.77,
    "textHeight": 20.69,
    "numberOfLines": 2,
    "fontSubstituted": false,  //Whether or not the requested font was substituted for Arial (this occurs when a character cannot be rendered in the requested font)
}