Optify's application programming interface (API) allows your organization to expand upon the core functionality provided by Optify's Real Time marketing software. In particular, it allows external applications to retrieve data from Optify data interfaces, making integration with other software applications simple. This document is a reference for the Optify API. It includes information about:

• Prerequisites
• Protocol and Access
• A description of our API including methods, and supported fields in our data schema

Prerequisites

Optify's API is only accessible to customers of Optify. In addition to an Optify account, API authentication token is required for access. Please send an email to info@optify.net to request your token.

Protocol

The Optify API is built with standard REST conventions. Data is transferred in either Xml or Json over HTTPS.

Root Url

The Optify API is located at https://api.optify.net

Authentication

You must pass your API token with all requests. You can pass this in the URL or in a HTTP header. To include the token in a URL, use a query string parameter of the form “access_token=<your token>”. The HTTP header is the standard Authorization HTTP header. The full header is “Authorization: OAuth <your token>”. To confirm that an access token is valid you can use the “whoami” endpoint at the following URL:

• https://api.optify.net/whoami?access_token=<your token>

This endpoint returns the name of the user associated with the access token or “nobody” if authentication is missing or invalid.

Data Types

• string – text values
• boolean – “true” or “false”
• number – IEEE floating point numbers
• date – date/time values encoded as “yyyy-mm-dd hh:mm:ss”. All dates are in UTC time. Times are encoded using 24-hour time. The time component is generally optional; if omitted the time “00:00:00” is assumed for the start of date ranges, "23:59:59" for the end of date ranges
• sequences – an enumerated sequence of one or more nested elements
• object – a compound object comprised of named fields

Content Types

Optify returns objects as Xml or Json. The MIME type for responses depends on standard content negotiation techniques. The simplest method of requesting a specific content type is to provide an extension in the file segment of the request URL. For example, the URL https://api.optify.net/v1/sites.xml returns Xml. The URL https://api.optify.net/sites.json returns the same object encoded as Json. Alternately you can specify the MIME type using the “Accept” HTTP header. To request Xml specify use “Accept: text/xml”. For Json, “Accept: application/json”. The default MIME type if you do not request a specific type is Xml. If you include both an extension and an Accept header, the extension overrides the Accept header. This documentation generally details the Xml version of response payloads. The content in the Json embodiment of objects generally mirrors the Xml embodiment. Differences follow a specific set of conventions:

• Object properties are encoded as fields in Json objects, elements in the Xml form
• Sequences of objects are encoded as arrays in Json. The Xml version of root objects an element with the plural name of the encoded object type. The Xml form of multi-valued fields is a set of elements with a tag matching the name of the field
• Escaping follows standard rules for the format (backslashed strings in Json, Xml entities in Xml)

Character Encoding

All input and output to Optify’s API is UTF-8. No other character encodings are supported. International characters in URLs should be encoded as URL escaped UTF-8.

Throttling

To protect Optify’s servers, some API calls are metered. Very high volumes of calls associated with an account may trigger throttling. If you receive an HTTP 503 status code your request has been throttled. Throttling applies to a single IP address and, if applicable, to the account associated with the access token. If your application depends on a high volume of API requests and you are being throttled, please contact Optify support to request a higher limit.

Supported API Requests

• Sites
• Visitor Summary
• Visitor Detail