FotoZap API Documentation

Last updated 2016–08–28

General Information

• All requests must be sent over HTTPS.
• Supply credentials using HTTP Basic authentication.
• Provide an informative User-Agent header with all requests.
• Responses are provided in JSON.

Media Uploaders

Get Campaign List

Endpoint:

GET https://zap-rest.fotozap.com/campaigns

Query Parameters:

• version: can be 1, 2, or 3

Example Request:

curl -u user@domain:password -A 'cURL Example API Client' https://zap-rest.fotozap.com/campaigns?version=3

Example Responses:

Version 1

[
    {
        "title": "Spring Sales Event",
        "id": 123
    },
    {
        "title": "Mother's Day Special Event",
        "id": 456
    }
]

Version 2

[
    {
        "id": 123,
        "title": "Spring Sales Event",
        "overlay": {
            "position": "southeast",
            "targetWidth": 1280,
            "url": "https://zap-rest.fotozap.com/rest/campaignoverlay/123",
            "etag": "9471e6e94c86faece4c2503f45673cae19289031"
        },
        "microsite": {
            "qrUrl": "HTTP://EVENTS.FOTOZAP.COM/Q/",
            "simpleUrl": "fotozap.com"
        }
    }
]

Comments:

The response is a list of campaign titles and their numeric IDs, for version 1. Versions 2 and 3 include additional information to provide a richer application experience. The titles are intended to be displayed for a user to choose. The selected campaign’s ID will be used when uploading media.

Upload Media to Campaign

Endpoint:

POST https://zap-rest.fotozap.com/campaigns/{id}/media

Path Parameter:

• id: the numeric campaign ID (required)

Query Parameters:

• deviceSerial: a unique identifier for the hardware device or software installation making the request (required)
• barcodes: a comma delimited list of barcodes to attach to the media object; all list items must have 6 or more characters, non-alphanumeric characters will be ignored
• emails: a comma delimited list of email addresses where the processed media will be delivered; all list items must be well-formed email addresses
• mobiles: a comma delimited list of mobile numbers where the processed media will be delivered; all list items must have 10 or more digits, non-numeric characters will be ignored
• attribute[key]: a multi-valued map of key-value pairs. keys may be repeated. keys can only contain upper and lowercase letters, and must be between six and 24 characters long. values can contain any text up to 255 characters. max number of attributes allowed is 10.
• dateTaken: local time on location when photo/video was captured. UNIX time in milliseconds (number of ms since 1970/01/01 00:00:00). must identify a time between Jan 1 2012 and present.
• media: a URL from which the upload content can be fetched. the upload content can be passed directly via form data or by reference to a URL here.

At least one barcode, email, or mobile number is required.

Form Data Parameter:

• media: the media object to upload to the campaign. (required, unless a URL is given in the media query parameter)

Allowed File Types:

The media can be uploaded directly as a form data parameter, or it can be retrieved from a URL given in a query parameter. In either case the content will be validated.

The following formats are accepted for all campaigns:

• JPEG & PNG images
• GIF animations
• MOV & MP4 videos
• ZIP archives of JPEG images. Images must be in a top level directory called main. (Available by request; only for specific campaigns.)

Example Request:

curl -u photographer@domain:password -A 'cURL Example API Client' -F media=@picture.jpg \
'https://zap-rest.fotozap.com/campaigns/2/media?emails=customer@abc.def&deviceSerial=cURLex12345&attribute[Layout]=photostrip'

Example Response:

eba45209-3627-4fd3-ac04-1cd68849826b

Comments:

A successful upload will yield a UUID which identifies the uploaded media object in the FotoZap system. Possible errors for an authorized request are:

• HTTP 400: See response body for details. Common causes include:
  • An invalid or incomplete barcode, email, or mobile number was provided
  • An attribute was malformed
  • The media parameter was missing, or both the form data parameter and query parameter were present.
• HTTP 415: file type not supported