Partner API Documentation


From Veer Development

Contents

[edit] Overview

Companies wishing to distribute Veer microstock images can use the Veer Partner API to incorporate search, preview, and download functionality into their own web sites.

Partner API provides searching, preview and purchasing capability at a Business-to-Business level. As a partner, you must bring or build your own e-Commerce system to provide purchasing and invoicing capability to your customers. Using Partner API, Corbis tracks all purchases and invoices you monthly for all of the downloads that have occurred.

Partner API incsludes the following services:

Search service

Can be used to search via Keyword, Artist or both. The search is performed on Corbis servers and currently allows a number of languages for searching:

  • Deutsch
  • English
  • United Kingdom English
  • Spanish
  • French, and
  • Italian

The information returned includes the list of image skus (unique identifiers) that satisfy the search, including the path to the image thumbnail located on the Corbis servers. You may choose to use this path for your thumbnails, or if you receive our thumbnail images and metadata on DVD, you may use your own path to the thumbnail image.

We provide an extensive mechanism to filter search results as well. Each search API method description will detail how that mechanism works.

Implementing Partner API search is optional. Your Partner contract may allow you to receive receive the product skus, keywords, metadata and thumbnails on DVD so that you may host them on your own servers and locate them with your own search engine.

Product service

This is the business to business portion of the Partner API and includes the following services:

Preview

Obtains detailed information about the sizes of image that are available (we call them versions) for a particular product and a path to the preview image located on Corbis servers.

Purchase

Allows purchasing a single size of a particular product. As a partner, you will be invoiced for this purchase at the end of the month. Using your own e-Commerce engine, you keep track of your own customer and this purchase through a purchase reference identifier that we provide to you as confimation of the purchase. The purchase confirmation will include a time-limited URL to the asset located on the Corbis servers. Your web site can use this URL to allow you customer to download the asset to their computer.

Return

You are free to implement a return policy. Should a customer return an image to you, you can return the image to Corbis and be credited the amount of the purchase that Corbis originally charged you, the Partner. The return service also includes the ability to report fraudulent purchases. Should you discover fraudulent activity on your web site, you can report that activity back to Corbis via the Partner API and be credited the cost of those images.

The return functionality should not be functionality that is visible to your customers to freely return images. It is a part of the API that should only be used by your organization to report returns that are required. Please note that contractually only returns over a specific dollar amount will be accepted. Therefore typically only fraudulent purchase returns will be accepted.

Redownload

You are free to implement a re-download policy as a convenience to your customer. With the original purchase reference identifier you recorded during purchase, you can request to allow the customer to re-download the exact same asset from Corbis servers for an amount of time defined by your Partner contract.

Activity service

Allows you to retrieve all purchases you have made for either a particular date range, or by the invoice number of the invoice we send you at the end of the month. You can use this information to reconcile your own e-Commerce records against Corbis records.

API background information

The business-to-business Partner API shares traits with our consumer-to-business public Web API. Before you continue reading about the Partner API methods, we recommend you read background information on how the Web API is constructed and intended to be used. Once familiar with that information, you will be able to understand the Partner API methods described below.

To use Partner API, you require a Partner Consumer Key. You will receive two such keys and their secrets when you have signed a Corbis Partner API agreement. One pair of key and secret are intended for use while you develop your web site. You can use that key to call any of the Partner API services as you develop and test your site, and you will not be invoiced for those purchases. Your Partner contract may impose limits to the number of purchases you allowed to make in a single day using the developer key and secret. The other key and secret is intended for use by your production web site. Purchases made using this key will be invoiced at the end of the month.

The developer key is still active once you start using the production key. That allows you to continue making improvements to your web site along side a running production site.

It should go without saying that both your Consumer keys and secrets identify you and should be treated as you would any valuable contractual document.The simplest way to protect that key is to not expose it in any web page of your site. Partner API is really meant for communication from your web-servers to Corbis web-servers and as such should only be present in code on your web servers and not injected into HTML pages you return to your customer's browser. If your web site is compromised, you must report that to Corbis immediately so that we may disable the key and prevent any purchases being made using that key. Furthermore, Corbis reserves the right to terminate a key if it is determined that fraudulent activity is taking place.

Partner API method documentation

Documentation for each Partner API method follows, broken out by service. There are currently two versions of some Partner API methods. You are free to choose to implement either, depending on your business requirements. Mixing versions of some Partner API methods is not recommended.

When developing against the Partner API, it is important that you properly handle all failure cases that Partner API reports back to you. These are all outlined at the bottom of each API call description.

In all the JSON and XML examples that appear in the Read more pages for each method, be aware that the Content-Length header has been dropped and the incoming and outgoing data has been word wrapped for clarity

Search service (version 1)

The Search service provides methods to search the Veer microstock product catalog. We also provide an extensive filtering mechanism that is described in greater detail in each method's Read More page.

https://api.veer.com/partner/search/v1/PRODUCT-TYPE/LOCALE/keywords/WORDS

Returns search results for the given product type that match the keywords. Read more...

https://api.veer.com/partner/search/v1/PRODUCT-TYPE/LOCALE/artist/ID

Obtains a search result for a particular artist within a specific product type. Read more...

https://api.veer.com/partner/search/v1/PRODUCT-TYPE/LOCALE/artist/ID/keywords/WORDS

Obtains a search result of all images with keywords for a particular artist within a specific product type. Read more...

Product service (version 1)

The Product service offers methods for finding out information about a product, purchasing the product, returning the product and re-downloading the product.

There are two versions of the Product Service API calls. Version 1 API calls show and allow purchasing only different sizes of images. Version 2 calls include showing and purchasing licensing. You are free to choose which ever set of calls suits your business better.

https://api.veer.com/partner/product/v1/preview/SKU

Obtains preview and version information about an image. Read more...

https://api.veer.com/partner/product/v1/purchase/

Purchases a single version of an image and returns a purchase reference identifier along with a time-limited URL that can be used to download the asset. Read more...

https://api.veer.com/partner/product/v1/return/

Allows a previously purchased version of an image to be returned or reported as a fraudulent purchase. Read more...

https://api.veer.com/partner/product/v1/redownload/

Allows a previously purchased version of an image to be re-downloaded from the Corbis servers without charge to you, the partner. Read more...

Product service (version 2)

The Version 2 Product service offers methods for finding out information about a product and its licenses, purchasing the product and/or its licenses and returning the product and/or its licenses.

Redownloading a product is not provided in the Version 2 Product Service as purchasing of licenses has created no new redownload functionality. Continue to use the Version 1 Product Service to offer redownload services to your customers.

https://api.veer.com/partner/product/v2/preview/SKU

Obtains preview and version information about an image including the licenses that are available for that image. Read more...

https://api.veer.com/partner/product/v2/purchase/

Purchases a single version of an image and/or one or more licenses for that image and returns a purchase reference identifier along with a time-limited URL that can be used to download the asset. Read more...

https://api.veer.com/partner/product/v2/return/

Allows a previously purchased version of an image and/or any of its licenses to be returned reported as a fraudulent purchase. Read more...

Activity service (version 1)

The Activity Service has methods that allow you to retrieve Corbis records of activity against your production Consumer Key. You can use these records to reconcile your e-commerce records against ours.

We track purchases of

  • image version from the Version 1 and Version 2 Product Service API calls
  • images licenses from the Version 2 Product Service API calls
  • returns of image versions from the Version 1 and Version 2 Product Service API calls
  • returns of licenses from the Version 2 Product Service API calls
  • redownloads of images from the Version 1 Product Service API calls

Version 1 of the Activity Service is unaware of licenses and will not report on any license transactions that may have occured with Version 2 Product Service calls. If you have only implemented Version 1 Product Service calls, you can implement either Version 1 or Version 2 Activity Service calls. Both are equivalent in that case.

https://api.veer.com/partner/activity/v1/dashboard/FROM-DATE/TO-DATE

Retrieve transaction history within a date range. Read more...

https://api.veer.com/partner/activity/v1/dashboard/INVOICE-NUMBER

Retrieve transaction history using an invoice number. Read more...

Activity service (version 2)

The Activity Service has methods that allow you to retrieve Corbis records of activity against your production Consumer Key. You can use these records to reconcile your e-commerce records against ours.

We track purchases of

  • image version from the Version 1 and Version 2 Product Service API calls
  • images licenses from the Version 2 Product Service API calls
  • returns of image versions from the Version 1 and Version 2 Product Service API calls
  • returns of licenses from the Version 2 Product Service API calls
  • redownloads of images from the Version 1 Product Service API calls

Version 2 of the Activity Service is aware of licenses and will report on any license transactions made with Version 2 Product Service API calls. If you have implemented any of the Version 2 Product Service API calls, you must implement Version 2 Activity Service calls.

https://api.veer.com/partner/activity/v2/dashboard/FROM-DATE/TO-DATE

Retrieve transaction history within a date range. Read more...

https://api.veer.com/partner/activity/v2/dashboard/INVOICE-NUMBER

Retrieve transaction history using an invoice number. Read more...

Partner API demonstration site

As a convenience, we provide, without support, a demonstration web site written in PHP. It illustrates how to call Partner API using PHP. The knowledge provided there can be transferred to many other languages as the underlying model of Partner API is standard HTTP request and response cycles.

There are two versions of the demo site implementing either version 1 or version 2 Partner API calls

We assume you are familiar with installing PHP on your own web servers. This site simply drops into a virtual folder on a PHP enabled server. We recommend the virtual folder name partner-v1 maps to the physical folder PartnerSiteV1 for the version that implements Version 1 API calls, Create a virtual folder partner-v2 that maps to the physcial folder PartnerSiteV2for the version that implements Version 2 API calls. The two virtual folder names names are also located in the security.php file of each of the sites.

In order to make the site functional, you must already have a Partner API Developer Consumer Key in your possession. Simply paste that key into the security.php file in place of the text --place-your-partner-development-key-here--. Your demonstration site should now be functional.

There are more instructions about the setup of the site are at the top of the security.php file.

The demonstration site also shows how to implement shopping cart functionality using the Partner API, even though the Partner API doesn't provide such functionality natively.

Partner API .NET Proxy

As a convenience, we provide, without support, a demonstration .NET Proxy written in C#. This sample code illustrates how we've written a proxy for the Partner API in Dot Net. You can see the usage of this proxy in the examples for each of the Partner API methods.

You may download the proxy. It supports both version 1 and version 2 Partner API calls.