Developer API

The Developer API is an interface for integrating third-party applications with our unique image processing service.

The API can be used to:

Getting Started

When connecting to Pixelz™ you need an API Key. If you don’t already have an API Key, please sign up for an account (the API Key can be found under Account Settings --> Affiliate).

The API Key is used to identify both a direct customer of Pixelz (ContactAPIkey) and a developer or partner for Pixelz (DeveloperAPIkey). For testing purposes you can use your API Key as both ContactAPIkey and DeveloperAPIkey.
The DeveloperAPIkey is used for Resellers and Developer Partners.

The Application Secret Code is used to encode/decode the information that we send to you. You can find it right below your API key in the backend.
If you create a new contact account, this new account will have its own API Key and Application Secret Code.

Request Header: We require header “Content-Type: application/json; charset=UTF-8” for the RESTful API.

The API can return XML or JSON results. The base URL for the XML response is https://api.pixelz.com/REST.svc/ and for JSON results the base URL is https://api.pixelz.com/REST.svc/JSON/.

SOAP API

This API is also available in a SOAP version at https://api.pixelz.com/soap.asmx?WSDL .

Click here to go to SOAP service description.

POST Template - Deprecated

Create new template. A template is a set of instructions on how the images should be processed.
POST payload has the parameters as JSON collection.

URL: https://api.pixelz.com/REST.svc/Template/
OR JSON: https://api.pixelz.com/REST.svc/JSON/Template/
Method: POST

Parameter Required Details
contactEmail true The email address of the customer
contactAPIkey true The API key of the customer
templateName true Template name. Accept values: A-Z, a-z, 0-9, () and space
templateOutputFormat true Image output format. Accept values: JPG, JPEG, TIF, TIFF, PNG, PSD
deliveryTimeInHour true Delivery time. Accept values: 168, 72, 24
backgroundType true Background type
0: No background removal
1: Background filled with color; backgroundColor will be required.
2: Transparent background; fileType cannot be JPG/JPEG.
3: Vertical gradient filled background; backgroundColor and backgroundVerticalGradientColor will be required.
backgroundColor false Hexadecimal number in [000000, FFFFFF]
backgroundVerticalGradientColor false Hexadecimal number in [000000, FFFFFF]
resizeType false Resize type
0: Keep original canvas size (Default)
1: Canvas aspect ratio
2: Fixed width / height
3: Min max only
resizeUnit false Resize unit, will be ignore if Resize type is ‘Canvas aspect ratio’
0: pixel (Default)
1: milimet
2: inch
resizeHeight false Image height after resize
resizeWidth false Image width after resize
resizeMinSize false Image minimum size for both dimensions
resizeMaxSize false Image maximum size for both dimensions
marginType false Margin type
0: Margins not set (Default)
1: Margins in percent
2: Margins in pixels
marginTop false Top margin
marginBottom false Bottom margin
marginLeft false Left margin
marginRight false Right margin
marginVerticalAlignment false How to vertically align if object does not fill canvas
1: Top
2: Center (Default)
3: Bottom
shadowType false Shadow type
0: No shadow (default)
1: Keep original shadow
2: Drop shadow
isKeptMannequin false Keep the Mannequin or not, accept values: “true”, “false”
isKeptModel false Keep the Model or not, accept values: “true”, “false”

Example of payload POST:

{
    "contactEmail": "john @ pixelz.com",
    "contactAPIkey": "44979dfe-5aa7-44ea-b3dd-7fae33bc37e9",
    "templateName":"My_First_Template",
    "templateOutputFormat":"JPG",
    "deliveryTimeInHour":"72",
    "backgroundType":"1",
    "backgroundColor":"FFFFFF",
    "backgroundVerticalGradientColor":"",
    "resizeType":"1",
    "resizeUnit":"",
    "resizeHeight":"4",
    "resizeWidth":"3",
    "resizeMinSize":"",
    "resizeMaxSize":"",
    "marginType":"2",
    "marginTop":"10",
    "marginBottom":"10",
    "marginLeft":"15",
    "marginRight":"15",
    "marginVerticalAlignment":"",
    "shadowType":"",
    "isKeptMannequin":"false",
    "isKeptModel":"false"
}

XML Response:

<NewTemplateResponse>
    <Message>Success</Message>
    <ErrorCode>NoError</ErrorCode>
    <TemplateId>2017982</TemplateId>
    <Price>
        <Amount>0.95</Amount>
        <Currency>USD</Currency>
        <CurrencyId>1</CurrencyId>
    </Price>
</NewTemplateResponse>

GET Template

Retrieves a templates details.

URL: https://api.pixelz.com/REST.svc/Template/{templateId}/
OR JSON: https://api.pixelz.com/REST.svc/JSON/Template/{templateId}/
Method: GET

Parameter Required
contactEmail true
contactAPIkey true
templateId true

XML Response:


  <TemplateSpecResponse>
  	<ErrorCode>NoError</ErrorCode>
  	<Message>Success</Message>
  	<Template>
  		<BackgroundColor i:nil="true"/>
  		<BackgroundType>2</BackgroundType>
  		<BackgroundVerticalGradientColor i:nil="true"/>
  		<CallbackFtp i:nil="true"/>
  		<CallbackUrl i:nil="true"/>
  		<ColorAdjustment>false</ColorAdjustment>
  		<ColorAdjustmentComment/>
  		<ColorAdjustmentSetting/>
  		<ColorMatchComment/>
  		<ColorMatching>true</ColorMatching>
  		<ColorMatchingSetting>Follow reference</ColorMatchingSetting>
  		<Comment></Comment>
  		<CreatedDate>2020-06-26</CreatedDate>
  		<DeliveryTimeInHours>24</DeliveryTimeInHours>
  		<Id>20668</Id>
  		<IsCombinedImages>false</IsCombinedImages>
  		<IsDeleted>false</IsDeleted>
  		<IsKeptMannequin>false</IsKeptMannequin>
  		<IsKeptModel>true</IsKeptModel>
  		<MarginBottom>0</MarginBottom>
  		<MarginLeft>0</MarginLeft>
  		<MarginRight>0</MarginRight>
  		<MarginTop>0</MarginTop>
  		<MarginType>1</MarginType>
  		<ModifiedDate>2020-08-22</ModifiedDate>
  		<Name>PNG</Name>
  		<OutputFormat>PNG</OutputFormat>
  		<Price>
  			<Amount>2.25</Amount>
  			<Currency>USD</Currency>
  			<CurrencyId>1</CurrencyId>
  		</Price>
  		<ResizeHeight i:nil="true"/>
  		<ResizeMaxSize i:nil="true"/>
  		<ResizeMinSize i:nil="true"/>
  		<ResizeType>6</ResizeType>
  		<ResizeUnit>0</ResizeUnit>
  		<ResizeWidth i:nil="true"/>
  		<ShadowType>0</ShadowType>
  		<VerticalAlignment>2</VerticalAlignment>
  	</Template>
  </TemplateSpecResponse>

JSON Response:


{
   "ErrorCode":"NoError",
   "Message":"Success",
   "Template":{
      "BackgroundColor":null,
      "BackgroundType":2,
      "BackgroundVerticalGradientColor":null,
      "CallbackFtp":null,
      "CallbackUrl":null,
      "ColorAdjustment":false,
      "ColorAdjustmentComment":"",
      "ColorAdjustmentSetting":"",
      "ColorMatchComment":"",
      "ColorMatching":true,
      "ColorMatchingSetting":"Follow reference",
      "Comment":"",
      "CreatedDate":"2020-06-26",
      "DeliveryTimeInHours":24,
      "Id":2066863,
      "IsCombinedImages":false,
      "IsDeleted":false,
      "IsKeptMannequin":false,
      "IsKeptModel":true,
      "MarginBottom":0,
      "MarginLeft":0,
      "MarginRight":0,
      "MarginTop":0,
      "MarginType":1,
      "ModifiedDate":"2020-08-22",
      "Name":"PNG",
      "OutputFormat":"PNG",
      "Price":{
         "Amount":2.25,
         "Currency":"USD",
         "CurrencyId":1
      },
      "ResizeHeight":null,
      "ResizeMaxSize":null,
      "ResizeMinSize":null,
      "ResizeType":6,
      "ResizeUnit":0,
      "ResizeWidth":null,
      "ShadowType":0,
      "VerticalAlignment":2
   }
}

Test Form: GET Template

Enter your information in the form below and get the server response.

contactEmail:
contactAPIkey:
templateId:

GET Templates

Retrieves a list of templates.

URL: https://api.pixelz.com/REST.svc/Templates/
OR JSON: https://api.pixelz.com/REST.svc/JSON/Templates/
Method: GET

Parameter Required
contactEmail true
contactAPIkey true

XML Response:


  <TemplatesResponse>
  	<ErrorCode>NoError</ErrorCode>
  	<Message/>
  	<Template>
  		<Template>
  		<ColorAdjustment>false</ColorAdjustment>
  		<ColorAdjustmentComment/>
  		<ColorAdjustmentSetting/>
  		<ColorMatchComment/>
  		<ColorMatching>True</ColorMatching>
  		<ColorMatchingSetting>Follow reference</ColorMatchingSetting>
  		<ContactId>4667360</ContactId>
  		<IsCombinedImages>false</IsCombinedImages>
  		<IsRecreateDetail>false</IsRecreateDetail>
  		<Prices>
  		<Price>
  		<Amount>2.00</Amount>
  		<Currency>USD</Currency>
  		<CurrencyId>1</CurrencyId>
  		</Price>
  		</Prices>
  		<TemplateId>21076</TemplateId>
  		<TemplateLabelId>10</TemplateLabelId>
  		<TemplateName>JPEG MANNEQUIN</TemplateName>
  	</Template>
  	<Template>
  		<ColorAdjustment>false</ColorAdjustment>
  		<ColorAdjustmentComment/>
  		<ColorAdjustmentSetting/>
  		<ColorMatchComment/>
  		<ColorMatching>false</ColorMatching>
  		<ColorMatchingSetting/>
  		<ContactId>4667360</ContactId>
  		<IsCombinedImages>false</IsCombinedImages>
  		<IsRecreateDetail>false</IsRecreateDetail>
  		<Prices>
  		<Price>
  		<Amount>1.50</Amount>
  		<Currency>USD</Currency>
  		<CurrencyId>1</CurrencyId>
  		</Price>
  		</Prices>
  		<TemplateId>20326863</TemplateId>
  		<TemplateLabelId>10</TemplateLabelId>
  		<TemplateName>PNG</TemplateName>
  	</Template>
  	<Template>
  		<ColorAdjustment>false</ColorAdjustment>
  		<ColorAdjustmentComment/>
  		<ColorAdjustmentSetting/>
  		<ColorMatchComment/>
  		<ColorMatching>false</ColorMatching>
  		<ColorMatchingSetting/>
  		<ContactId>4667360</ContactId>
  		<IsCombinedImages>false</IsCombinedImages>
  		<IsRecreateDetail>false</IsRecreateDetail>
  		<Prices>
  		<Price>
  		<Amount>1.00</Amount>
  		<Currency>USD</Currency>
  		<CurrencyId>1</CurrencyId>
  		</Price>
  		</Prices>
  		<TemplateId>2066295</TemplateId>
  		<TemplateLabelId>10</TemplateLabelId>
  		<TemplateName>Flats</TemplateName>
  		</Template>
  	</Templates>
  </TemplatesResponse>

JSON Response:


  {
     "ErrorCode":"NoError",
     "Message":"",
     "Templates":[
        {
           "ColorAdjustment":false,
           "ColorAdjustmentComment":"",
           "ColorAdjustmentSetting":"",
           "ColorMatchComment":"",
           "ColorMatching":true,
           "ColorMatchingSetting":"Follow reference",
           "ContactId":4667360,
           "IsCombinedImages":false,
           "IsRecreateDetail":false,
           "Prices":[
              {
                 "Amount":2.00,
                 "Currency":"USD",
                 "CurrencyId":1
              }
           ],
           "TemplateId":21032576,
           "TemplateLabelId":10,
           "TemplateName":"JPEG MANNEQUIN"
        },
        {
           "ColorAdjustment":false,
           "ColorAdjustmentComment":"",
           "ColorAdjustmentSetting":"",
           "ColorMatchComment":"",
           "ColorMatching":false,
           "ColorMatchingSetting":"",
           "ContactId":4667360,
           "IsCombinedImages":false,
           "IsRecreateDetail":false,
           "Prices":[
              {
                 "Amount":1.50,
                 "Currency":"USD",
                 "CurrencyId":1
              }
           ],
           "TemplateId":203863,
           "TemplateLabelId":10,
           "TemplateName":"PNG"
        },
        {
           "ContactId":4667360,
           "IsCombinedImages":false,
           "IsRecreateDetail":false,
           "Prices":[
              {
                 "Amount":1.00,
                 "Currency":"USD",
                 "CurrencyId":1
              }
           ],
           "TemplateId":20635295,
           "TemplateLabelId":10,
           "TemplateName":"Flats"
        }
     ]
  }

Test Form: GET Templates

Enter your information in the form below and get the server response.

contactEmail:
contactAPIkey:

POST Image

POST payload has the parameters as JSON collection.

URL: https://api.pixelz.com/REST.svc/Image/
OR JSON: https://api.pixelz.com/REST.svc/JSON/Image/
Method: POST

Parameter Required Details
contactEmail true The email address of the customer
contactAPIkey true The API key of the customer
developerAPIkey false The API key of the developer/partner. Can be the same as contactAPIkey
templateId false Use GetTemplates to find templateID
imageURL true The source URL of image
imageURL2 false The source URL of 2nd image (combining images)
imageURL3 false The source URL of 3rd image (combining images)
imageURL4 false The source URL of 4th image (combining images)
imageURL5 false The source URL of 5th image (combining images)
colorReferenceFileURL false The source URL of the reference image or swatch used for color matching
imageRequestedDeliveryTimeInHours false Deprecated
imageCallbackURL false Webhook callback URL when image is processed
customerImageId false ImageID at the customer side. You can use it as image identity
productId false All images with the same ProductID will be collected into a single package, and we can take care the consistent quality of all images in this package.
imageDeadlineDateTimeUTC false The deadline of this image, in UTC time. Format “yyyy-MM-dd HH:mm:ss”. This deadline should not shorter than the minimum deadline setting in your account, default 24 hours. To adjust the minimum deadline, contact us.

Example of payload POST:


  {
      "contactEmail": "john @ pixelz.com",
      "contactAPIkey": "44979dfe-5aa7-44ea-b3dd-7fae33bc37e9",
      "developerAPIkey": "44979dfe-5aa7-44ea-b3dd-7fae33bc37e9",
      "templateId": "2000045",
      "imageURL": "http://www.mydomain.com/myimage.jpg",
      "imageURL2": "",
      "imageURL3": "",
      "imageURL4": "",
      "imageURL5": "",
      "colorReferenceFileURL": "",
      "imageRequestedDeliveryTimeInHours": "24",
      "imageCallbackURL": "http://www.mydomain.com/callback-url.php",
      "customerImageId": "12345",
      "productId": "Crying Baby Tee 066"
  }

XML Response:


  <AddImageResponse>
    <ErrorCode>NoError</ErrorCode>
    <Message/>
    <ImageTicket>a37a1f55-7cd4-4474-db19-ac03e85538a7</ImageTicket>
    <IsTrial>false</IsTrial>
    <CustomerImageId>12345</CustomerImageId>
  </AddImageResponse>

JSON Response:


  {
      "ErrorCode":"NoError",
      "Message": "",
      "ImageTicket": "a37a1f55-7cd4-4474-db19-ac03e85538a7",
      "IsTrial": "false",
      "CustomerImageId": 12345
  }

Test Form: POST Image

Enter your information in the form below and get the server response.

contactEmail:
contactAPIkey:
developerAPIkey:
templateId:
imageURL:
imageURL2:
imageURL3:
imageURL4:
imageURL5:
colorReferenceFileURL:
imageRequestedDeliveryTimeInHours:
imageCallbackURL:
customerImageId:
productId:
JSON Data:
Server response:

POST WhiteGloveService

White Glove Service is a special service from Pixelz: If you don’t know, or don’t have time to select the right template for your images, we will help. Just send your images to us and we will take care the rest.
Usage of this method is quite similar to POST Image.

URL: https://api.pixelz.com/REST.svc/WhiteGloveService/
OR JSON: https://api.pixelz.com/REST.svc/JSON/WhiteGloveService/
Method: POST

Parameter Required Details
contactEmail true The email address of the customer
contactAPIkey true The API key of the customer
developerAPIkey false The API key of the developer/partner. Can be the same as contactAPIkey
imageURL true The source URL of image
imageURL2 false The source URL of 2nd image (combining images)
imageURL3 false The source URL of 3rd image (combining images)
imageURL4 false The source URL of 4th image (combining images)
imageURL5 false The source URL of 5th image (combining images)
colorReferenceFileURL false The source URL of the reference image or swatch used for color matching
imageCallbackURL false Webhook callback URL when image is processed
customerImageId false ImageID at the customer side. You can use it as image identity
productId false All images with the same ProductID will be collected into a single package, and we can take care the consistent quality of all images in this package.

Example of payload POST:


  {
      "contactEmail": "john @ pixelz.com",
      "contactAPIkey": "44979dfe-5aa7-44ea-b3dd-7fae33bc37e9",
      "developerAPIkey": "44979dfe-5aa7-44ea-b3dd-7fae33bc37e9",
      "imageURL": "http://www.mydomain.com/myimage.jpg",
      "imageURL2": "",
      "imageURL3": "",
      "imageURL4": "",
      "imageURL5": "",
      "colorReferenceFileURL": "",
      "imageCallbackURL": "http://www.mydomain.com/callback-url.php",
      "customerImageId": "12345",
      "productId": "Crying Baby Tee 066"
  }

XML Response:


  <AddImageResponse>
    <ErrorCode>NoError</ErrorCode>
    <Message/>
    <ImageTicket>a37a1f55-7cd4-4474-db19-ac03e85538a7</ImageTicket>
    <IsTrial>false</IsTrial>
    <CustomerImageId>12345</CustomerImageId>
  </AddImageResponse>

JSON Response:


  {
      "ErrorCode":"NoError",
      "Message": "",
      "ImageTicket": "a37a1f55-7cd4-4474-db19-ac03e85538a7",
      "IsTrial": "false",
      "CustomerImageId": 12345
  }

 

Test Form: POST White Glove Service

Enter your information in the form below and get the server response.

contactEmail:
contactAPIkey:
developerAPIkey:
imageURL:
imageURL2:
imageURL3:
imageURL4:
imageURL5:
colorReferenceFileURL:
imageCallbackURL:
customerImageId:
productId:
JSON Data:
Server response:


DELETE Image

DELETE payload has the parameters as JSON collection. Cannot delete an in-production image.

URL: https://api.pixelz.com/REST.svc/Image/{imageTicket}/
OR JSON: https://api.pixelz.com/REST.svc/JSON/Image/{imageTicket}/
Method: DELETE

Parameter Required
contactEmail true
contactAPIkey true
imageTicket true. If you gonna using customerImageId, set it is “nonticket”
customerImageId false

Example of payload DELETE:


  {
    "contactEmail": "john @ pixelz.com",
    "contactAPIkey": "44979dfe-5aa7-44ea-b3dd-7fae33bc37e9",
    "imageTicket": "8de624ab-593b-409d-8324-eb4890c4b867"
  }

Or:


  {
    "contactEmail": "john @ pixelz.com",
    "contactAPIkey": "44979dfe-5aa7-44ea-b3dd-7fae33bc37e9",
    "imageTicket": "nonticket",
    "customerImageId": "12345"
  }

XML Response:


<DeleteImageResponse>
  <ErrorCode>NoError</ErrorCode>
  <Message>Image was deleted</Message>
</DeleteImageResponse>

JSON Response:


  {
    "ErrorCode": 0,
    "Message": "Image was deleted"
  }

Test Form: DELETE Image

Enter your information in the form below and get the server response.

contactEmail:
contactAPIkey:
imageTicket:
customerImageId:
JSON Data:
Server response:

GET Status

Get the status of image production.

URL: https://api.pixelz.com/REST.svc/Image/{imageTicket}/
OR JSON: https://api.pixelz.com/REST.svc/JSON/Image/{imageTicket}/
Method: GET

Parameter Required
contactEmail true
contactAPIkey true
imageTicket true. If you gonna using customerImageId, set it is “nonticket”
customerImageId false

XML Response:


  <ImageStatusResponse>
    <ErrorCode>NoError</ErrorCode>
    <Message/>
    <ImageStatus>
      <FinalImagesURL>
        <string>1000003/2000000/final/myimage.jpg</string>
      </FinalImagesURL>
      <ImageTicket>33979dfe-5ea7-44ea-b3dd-7fde33bc37e9</ImageTicket>
      <StatusId>80</StatusId>
      <StatusName>Delivered</StatusName>
      <IsPaid>false</IsPaid>
      <ThumbnailImageURL>1000003/2000000/thumbnail/myimage.jpg</ThumbnailImageURL>
      <CustomerImageId />
      <ProductId />
    </ImageStatus>
  </ImageStatusResponse>

JSON Response:


{
   "ErrorCode":"NoError",
   "Message":"",
   "ImageStatus":{
      "CustomerImageId":"1234",
      "FinalImagesURL":[
         "/1000003/2000000/final/myimage.jpg"
      ],
      "ImageTicket":"33979dfe-5ea7-44ea-b3dd-7fde33bc37e9",
      "IsPaid":false,
      "ProductId":"",
      "StatusId":80,
      "StatusName":"Delivered",
      "ThumbnailImageURL":"/1000003/2000000/thumbnail/myimage.jpg"
   }
}

Test Form: GET Status

Enter your information in the form below and get the server response.

contactEmail:
contactAPIkey:
imageTicket:
customerImageId:

GET Images List

Get a list of images.

URL: https://api.pixelz.com/REST.svc/Images/
OR JSON: https://api.pixelz.com/REST.svc/JSON/Images/
Method: GET

Parameter Required Detail
contactEmail true The email address of the customer
contactAPIkey true The API key of the customer
imageStatus false The image status. Refer to table “Image status explanation” for more detailed.
excludeImageStatus false The image status to exclude. Refer to table “Image status explanation” for more detailed.
productId false The ProductID. See POST Image for more detailed.
fromDate false Image created date, lower bound included.
toDate false Image created date, upper bound included.
page false The page number. Default value is 1.
imagesPerPage false Number of images per page. Default value is 10, maximum value is 100.
sortBy false The field name that result will be sort by. Accept values: “id”, “date”, “status”.
isDescending false The sort order is descending or not, accept values: “true”, “false”.

Image status explanation:

Image status Detail
0 Deleted by user
10 New images
12 New images – download failed
20 Deprecated! New images – waiting for payment
30 Ready for production
40 Returned for production (by you)
60 In production
62 Assigned to editor
64 Downloaded by editor
66 Quality Assurance
70 Production finished – ready for download
72 Production finished – 1st delivery attempt failed
74 Production finished – 2nd delivery attempt failed
76 Production finished – 3rd delivery attempt failed
78 Production finished – Delivery failed
80 Delivered
90 Rejected by Pixelz
95 Awaiting your reply
100 Closed
999 Deleted by cleanup service

XML Response:


  <ImagesListResponse>
    <ErrorCode>NoError</ErrorCode>
    <Message/>
    <Images>
      <ImageStatus>
        <FinalImagesURL>
          <string>1000003/2000000/final/myimage1.jpg</string>
        </FinalImagesURL>
        <ImageTicket>0da2bbe9-4cf4-4c16-8e46-52048836a01b</ImageTicket>
        <StatusId>70</StatusId>
        <StatusName>Production Finished</StatusName>
        <IsPaid>false</IsPaid>
        <ThumbnailImageURL>1000003/2000000/thumbnail/myimage1.jpg</ThumbnailImageURL>
        <CustomerImageId />
        <ProductId />
      </ImageStatus>
      <ImageStatus>
        <FinalImagesURL>
          <string>1000003/2000000/final/myimage2.jpg</string>
        </FinalImagesURL>
        <ImageTicket>fb4751e1-4475-4bf8-a21f-1c0d8b1bb52d</ImageTicket>
        <StatusId>80</StatusId>
        <StatusName>Delivered</StatusName>
        <IsPaid>false</IsPaid>
        <ThumbnailImageURL>1000003/2000000/thumbnail/myimage2.jpg</ThumbnailImageURL>
        <CustomerImageId />
        <ProductId />
      </ImageStatus>
    </Images>
  </ImagesListResponse>

JSON Response:


{
   "ErrorCode":"NoError",
   "Message":"",
   "Images":[
      {
         "CustomerImageId":"",
         "FinalImagesURL":[
            "1000003/2000000/final/myimage1.jpg"
         ],
         "ImageTicket":"0da2bbe9-4cf4-4c16-8e46-52048836a01b",
         "IsPaid":false,
         "ProductId":"",
         "StatusId":70,
         "StatusName":"Production Finished",
         "ThumbnailImageURL":"/1000003/2000000/thumbnail/myimage1.jpg"
      },
      {
         "CustomerImageId":"",
         "FinalImagesURL":[
            "1000003/2000000/final/myimage2.jpg"
         ],
         "ImageTicket":"fb4751e1-4475-4bf8-a21f-1c0d8b1bb52d",
         "IsPaid":false,
         "ProductId":"",
         "StatusId":80,
         "StatusName":"Delivered",
         "ThumbnailImageURL":"/1000003/2000000/thumbnail/myimage2.jpg"
      }
   ]
}

Test Form: GET Images List

Enter your information in the form below and get the server response.

contactEmail:
contactAPIkey:
imageStatus:
fromDate:
toDate:
page:
imagesPerPage:
excludeImageStatus:
sortBy:
isDescending:

GET Count Images

Count number of images.

URL: https://api.pixelz.com/REST.svc/Images/Count/
OR JSON: https://api.pixelz.com/REST.svc/JSON/Images/Count/
Method: GET

Parameter Required Detail
contactEmail true The email address of the customer
contactAPIkey true The API key of the customer
imageStatus false The image status. Refer to table “Image status explanation” for more detailed.
fromDate false Image created date, lower bound included.
toDate false Image created date, upper bound included.

XML Response:


  <ImagesCountResponse>
    <ErrorCode>NoError</ErrorCode>
    <Message/>
    <ImagesCount>315</ImagesCount>
  </ImagesCountResponse>

JSON Response:


  {
     "ErrorCode":"NoError",
     "Message":"",
     "ImagesCount":315
  }

Test Form: COUNT Images

Enter your information in the form below and get the server response.

contactEmail:
contactAPIkey:
imageStatus:
fromDate:
toDate:

GET ProductId-s List

Get a list of ProductIds.

URL: https://api.pixelz.com/REST.svc/ProductIds/
OR JSON: https://api.pixelz.com/REST.svc/JSON/ProductIds/
Method: GET

Parameter Required Detail
contactEmail true The email address of the customer
contactAPIkey true The API key of the customer
page false The page number. Default value is 1.
productIdsPerPage false Number of productId-s per page. Default value is 10, maximum value is 100.

XML Response:


  <ProductIdsListResponse>
      <Message/>
      <ErrorCode>NoError</ErrorCode>
      <ProductIds>
          <ProductIdStatistic>
              <ProductId>test product 01</ProductId>
              <DoneCount>3</DoneCount>
              <TodoCount>5</TodoCount>
          </ProductIdStatistic>
          <ProductIdStatistic>
              <ProductId>test product 02</ProductId>
              <DoneCount>2</DoneCount>
              <TodoCount>0</TodoCount>
          </ProductIdStatistic>
      </ProductIds>
  </ProductIdsListResponse>

JSON Response:


  {
     "ErrorCode":"NoError",
     "Message":"",
     "ProductIds":[
        {
           "DoneCount":3,
           "ProductId":"test product 01",
           "TodoCount":5
        },
        {
           "DoneCount":2,
           "ProductId":"test product 02",
           "TodoCount":0
        }
     ]
  }

Test Form: GET ProductId-s List

Enter your information in the form below and get the server response.

contactEmail:
contactAPIkey:
page:
productIdsPerPage:

REJECT Image - Deprecated

REJECT payload has the parameters as JSON collection. Cannot reject a not yet finished image.

URL: https://api.pixelz.com/REST.svc/Image/Reject/{imageTicket}/
OR JSON: https://api.pixelz.com/REST.svc/JSON/Image/Reject/{imageTicket}/
Method: PUT

Parameter Required
contactEmail true
contactAPIkey true
imageTicket true. If you gonna using customerImageId, set it is “nonticket”
customerImageId false
comment false

Example of payload REJECT:


  {
    "contactEmail": "john @ pixelz.com",
    "contactAPIkey": "44979dfe-5aa7-44ea-b3dd-7fae33bc37e9",
    "imageTicket": "8de624ab-593b-409d-8324-eb4890c4b867",
    "comment": "Free text comment"
  }

Or:


  {
    "contactEmail": "john @ pixelz.com",
    "contactAPIkey": "44979dfe-5aa7-44ea-b3dd-7fae33bc37e9",
    "imageTicket": "nonticket",
    "customerImageId": "12345"
    "comment": "Free text comment"
  }

XML Response:


  <RejectImageResponse>
    <ErrorCode>NoError</ErrorCode>
    <Message>Image was rejected.</Message>
  </RejectImageResponse>

Test Form: REJECT Image

Enter your information in the form below and get the server response.

contactEmail:
contactAPIkey:
imageTicket:
customerImageId:
comment:
JSON Data:
Server response:

POST Contact - Deprecated

POST payload has the parameters as JSON collection.

URL: https://api.pixelz.com/REST.svc/Contact/
OR JSON: https://api.pixelz.com/REST.svc/JSON/Contact/
Method: POST

Parameter Required Details
developerEmail true The email address of the developer/partner
developerAPIkey true The API key of the developer/partner
contactEmail true Email of the new contact
contactName true Name of the new contact
countryCode true The ISO 3166-1 alpha-2 two-letter country code
contactAddress1 false
contactAddress2 false
contactPhone false
contactCity false
contactState false
contactZipCode false

Example of payload POST:


  {
      "developerEmail":"john @ pixelz.com",
      "developerAPIkey":"44979dfe-5aa7-44ea-b3dd-7fae33bc37e9",
      "contactEmail":"my_new_customer @ domain.com",
      "contactName":"My First Customer",
      "countryCode":"US",
      "contactAddress1":"",
      "contactAddress2":"",
      "contactPhone":"",
      "contactCity":"",
      "contactState":"",
      "contactZipCode":""
  }

XML Response:


  <NewContactResponse>
      <ErrorCode>NoError</ErrorCode>
      <Message>Success</Message>
      <ContactAPIkey>5ea1a104-f31f-4de1-b7f8-e4444e38e32a</ContactAPIkey>
      <ContactEmail>my_new_customer @ domain.com</ContactEmail>
  </NewContactResponse>

GET Contact

Retrieves your contact information, include email, contact person, credit line and account balance.

URL: https://api.pixelz.com/REST.svc/Contact/
OR JSON: https://api.pixelz.com/REST.svc/JSON/Contact/
Method: GET

Parameter Required
contactEmail true
contactAPIkey true

XML Response:


  <ContactResponse>
    <ErrorCode>NoError</ErrorCode>
    <Message/>
    <Contact>
      <ContactAccountBalance>
        <Amount>81.05</Amount>
        <Currency>USD</Currency>
        <CurrencyId>1</CurrencyId>
      </ContactAccountBalance>
      <ContactCompany>Pixelz</ContactCompany>
      <ContactDaysOfCredit>15</ContactDaysOfCredit>
      <ContactEmail>john @ pixelz.com</ContactEmail>
      <ContactPerson>John</ContactPerson>
      <NumberOfTrialImages>3</NumberOfTrialImages>
    </Contact>
  </ContactResponse>

JSON Response:


  {
     "ErrorCode":"NoError",
     "Message":"",
     "Contact":{
        "ContactAccountBalance":{
           "Amount":81.05,
           "Currency":"USD",
           "CurrencyId":1
        },
        "ContactCompany":"Pixelz",
        "ContactDaysOfCredit":15,
        "ContactEmail":"john @ pixelz.com",
        "ContactPerson":"John",
        "NumberOfTrialImages":3
     }
  }

Test Form: GET Contact

Enter your information in the form below and get the server response.

contactEmail:
contactAPIkey:

GET Invoices

Retrieves your invoices list.

URL: https://api.pixelz.com/REST.svc/Invoices/
OR JSON: https://api.pixelz.com/REST.svc/JSON/Invoices/
Method: GET

Parameter Required Detail
contactEmail true The email address of the customer
contactAPIkey true The API key of the customer
fromDate false Invoice created date, lower bound included.
toDate false Invoice created date, upper bound included.
page false The page number. Default value is 1. Max 50 invoices per page.
returnUrl false The URL where customer will be redirected after finish payment

XML Response:


  <InvoiceListResponse>
    <Message/>
    <ErrorCode>NoError</ErrorCode>
    <Invoices>
      <Invoice>
        <InvoiceId>INV-1315</InvoiceId>
        <CreatedDate>2012-12-31</CreatedDate>
        <AmountDue>0.00</AmountDue>
        <IsPaid>true</IsPaid>
        <PaymentUrl />
        <InvoiceUrl>/DownloadInvoice?invoiceNumber=INV-1315</InvoiceUrl>
      </Invoice>
      <Invoice>
        <InvoiceId>INV-1289</InvoiceId>
        <CreatedDate>2012-12-26</CreatedDate>
        <AmountDue>105.00</AmountDue>
        <IsPaid>false</IsPaid>
        <PaymentUrl>/Transactions?key=1234567890&returnUrl=http://test.com/testurl</PaymentUrl>
        <InvoiceUrl>/DownloadInvoice?invoiceNumber=INV-1289</InvoiceUrl>
      </Invoice>
    </Invoices>
  </InvoiceListResponse>

JSON Response:


{
   "ErrorCode":"NoError",
   "Message":"",
   "Invoices":[
      {
         "AmountDue":"0.0",
         "CreatedDate":"2012-12-31",
         "InvoiceId":"INV-1315",
         "InvoiceUrl":"/DownloadInvoice?invoiceNumber=INV-1315",
         "IsPaid":true,
         "PaymentUrl":""
      },
      {
         "AmountDue":"105.00",
         "CreatedDate":"2012-12-26",
         "InvoiceId":"INV-1289",
         "InvoiceUrl":"/Transactions?key=1234567890&returnUrl=http://test.com/testurl</PaymentUrl",
         "IsPaid":false,
         "PaymentUrl":"/DownloadInvoice?invoiceNumber=INV-1289"
      }
   ]
}

Test Form: GET Invoices

Enter your information in the form below and get the server response.

contactEmail:
contactAPIkey:
fromDate:
toDate:
page:
returnUrl:

Webhook

When you add images to the processing queue you can define a URL for the Webhook. The Webhook is a simple ”image-has-been-processed”-notification via HTTP POST containing the URL to download image. The Pixelz Webhook will notify you when the image has been processed. The Webhook will POST data to the Image Callback URL specified and expects a 200 HTTP status code. The Webhook will try to deliver the image 4 times with different time intervals:

First try: Right after the image finished
Second try: +5 minutes later
Third try: +1 hour later
Fourth try: +5 hours later

The ImageCallbackURL has higher priority than TemplateCallbackURL. If image has no ImageCallbackURL then we will use TemplateCallbackURL.

URL: As specified
Method: POST

Parameter Required Details
imageTicket true The ticketID of the processed image
processedImageURL true The URL to download image from remote server
templateId true Identify the templateId that the finished image version belong to. Useful if your images has more than one output versions. (NEW)
customerImageId false If you POST an image with a customerImageId, the webhook will return it back as an additional parameter. This will help you to identify the image using your customerImageId. Of course you still can use the imageTicket as usual. (NEW)

Test form: Webhook

Here you can make a test request to your call back page.

contactAPIkey:
Call Back URL:

Verify Webhook

Our webhooks can be verified as comming from Pixelz by calculating a digital signature.
Along with the data sent in the request, the Webhook request includes one or two headers to achieve this verification.

  • A HTTP_X_PXZ_CUSTOMER_HMAC_SHA256 header, which can be validated using the application secret code matching the contactAPIkey used to POST images. This header always available.
  • A HTTP_X_PXZ_PARTNER_HMAC_SHA256 header, which can be validated using developer/partner application secret code matching the optional developerAPIkey used to POST images.
    This header is only available if you used POST image with a developerAPIkey.

Log in into our backend to get your application secret code, right below your API key

To verify that the request came from Pixelz, compute the HMAC digest using the full Request Body and the application secret code and compare it to the value in the header (Code examples can be found below).
If they match, you can be sure that the Webhook was sent from Pixelz and the data has not been compromised.

Below is a example in C# using .NET framework (MVC) of how one might verify a webhook request.


  public class CallbackController : ApiController
  {
  	private const string appCode = "MY_APPLICATION_SECRET_CODE";

  	// POST api/callback
  	public async Task<string> Post()
  	{
  		if (Request.Headers.TryGetValues("HTTP_X_PXZ_CUSTOMER_HMAC_SHA256", out IEnumerable<string> hmacHeaders))
  		{
  			string hmacHeader = hmacHeaders.First();
  			byte[] data = await Request.Content.ReadAsByteArrayAsync();
  			if (VerifyWebhook(appCode, data, hmacHeader))
  			{
  				// Verification success
  			}
  			else
  			{
  				// Verification failed
  			}
  		}
  		return "OK";
  	}

  	private bool VerifyWebhook(string key, byte[] data, string hmacHeader)
  	{
  		using (HMACSHA256 hmac = new HMACSHA256(System.Text.Encoding.UTF8.GetBytes(key)))
  		{
  			string calculatedHmac = Convert.ToBase64String(hmac.ComputeHash(data));
  			return hmacHeader == calculatedHmac;
  		}
  	}
  }

And here’s a C# using .NET framework (Webform):


  public partial class CallBack : System.Web.UI.Page
  {
  	private const string appCode = "MY_APPLICATION_SECRET_CODE";
  	protected void Page_Load(object sender, EventArgs e)
  	{
  		string hmacHeader = Request.Headers["HTTP_X_PXZ_CUSTOMER_HMAC_SHA256"];
  		byte[] data = Request.BinaryRead(Request.ContentLength);
  		if (VerifyWebhook(appCode, data, hmacHeader))
  		{
  			// Verification success
  		}
  		else
  		{
  			// Verification fail
  		}
  	}

  	private bool VerifyWebhook(string key, byte[] data, string hmacHeader)
  	{
  		using (HMACSHA256 hmac = new HMACSHA256(System.Text.Encoding.UTF8.GetBytes(key)))
  		{
  			string calculatedHmac = Convert.ToBase64String(hmac.ComputeHash(data));
  			return hmacHeader == calculatedHmac;
  		}
  	}
  }

And here’s a Node.js version:


  const crypto = require('crypto');
  const express = require('express');
  const app = express();
  const port = 3000;

  function verifyWebhook(body, hmacHeader){
      let calculatedHmac = crypto
          .createHmac('sha256', process.env.MY_APPLICATION_SECRET_CODE)
          .update(body)
          .digest('base64');
      return calculatedHmac === hmacHeader;
  }

  app.post('/callback', express.text(), (req, res) => {
      var hmacHeader = req.header("HTTP_X_PXZ_CUSTOMER_HMAC_SHA256");
      if (verifyWebhook(req.body, hmacHeader)){
          // verification success
      }else{
          // verification fail
      }
      res.send('OK')
  })

  app.listen(port, () => {
    console.log('Example app listening at http://localhost:${port}')
  })

And here’s a PHP version:


  <?php
  define('APP_CODE', 'MY_APPLICATION_SECRET_CODE');
  function verify_webhook($data, $hmac_header)
  {
  	$calculated_hmac = base64_encode(hash_hmac('sha256', $data, APP_CODE, true));

  	return ($hmac_header == $calculated_hmac);
  }

  $hmac_header = $_SERVER['HTTP_HTTP_X_PXZ_CUSTOMER_HMAC_SHA256'];
  $data = file_get_contents('php://input');
  $verified = verify_webhook($data, $hmac_header);
  error_log('Webhook verified: '.var_export($verified, true)); //check error.log to see the result

  if ($verified == true){
  	// verification success
  }else{
  	// verification fail
  }
  ?>