# Getting started

To be able to do anything, you need a Iteras account with an API key. From there on, it's a standard HTTPS protocol.

GET is used for requests that simply return data. GET parameters are encoded as query parameters, like ?parameter1=value1&parameter2=value2. For instance:

GET /api/customers/?id=12345 HTTP/1.1
Host: app.iteras.dk

Note that you need to URL encode the values, you can't just append them, for instance extrafield=delivered_to:address:postcode becomes extrafield=delivered_to%3Apostcode. If you use an HTTP library to handle the GET parameters, it should do this automatically for you.

Endpoints using POST are supposed to be posted to just like a browser posts a form, e.g. with the parameters application/x-www-form-urlencoded. Simple example:

POST /api/authenticatecustomer/ HTTP/1.1
Host: app.iteras.dk
Content-Type: application/x-www-form-urlencoded

email=someone%40example.com&password=secret

POST parameters must also be encoded, as you can see. If you use an HTTP library, it will do it for you automatically.

Example with JSON:

POST /api/customers/update/ HTTP/1.1
Host: app.iteras.dk
Content-Type: application/x-www-form-urlencoded

operations=%5B%7B%22operation%22%3A%22updatecustomer%22%2C%22id%22%3A%22123456
%22%2C%22data%22%3A%7B%22name%22%3A%22Customer%20Name%22%2C%22email%22%3A%22fo
o%40example.com%22%2C%22%3ACustomfield%22%3A%22Some%20value%22%2C%22%3ACustomd
atefield%22%3A%222001-12-31%22%7D%7D%5D

Some endpoints also support posting a JSON document directly with the content type application/json. This is currently the case for the /api/customers/update/ endpoint. You should POST an object where each parameter is an attribute of that object. Here's the above example posted as a JSON document:

POST /api/customers/update/ HTTP/1.1
Host: app.iteras.dk
Content-Type: application/json

{
  "operations": [{
    "operation":"updatecustomer",
    "id":"123456",
    "data":{"name":"Customer Name","email":"foo@example.com",":Customfield":"Some value",":Customdatefield":"2001-12-31"}
  }]
}

# Authentication

The authentication mechanism is currently a pre-shared API access key. You can create API accesses in the account settings in Iteras and set up what they can do.

The preferred way to provide the key is by inserting an HTTP header X-Iteras-Key with the key as the value, e.g.

X-Iteras-Key: 00aabbccddff112233445566778899

If this proves difficult, you can also provide the key as the GET parameter iteras-key, e.g.

https://app.iteras.dk/api/customers/?id=12345&iteras-key=00aabbccddff112233445566778899

This also works for the POST endpoints.

We recommend using the header if at all possible as there is a greater risk of having the key leaked in a log somewhere if it is part of the URL.

# Results and error codes

Results are returned as JSON.

Generally, errors are handled in two separate ways for convenience. Errors from user input are returned in the JSON as documented in each call with an HTTP 200 status code. Programming errors in the way the request is submitted or server authentication errors results in a plain text error response with a 40x HTTP status code, e.g. 400, 403 or 404.

# Trying out your access

The easiest way to try out your API access is to call the API access detail endpoint /api/access/ with an HTTP GET request and the API key supplied in the X-Iteras-Key HTTP header:

GET /api/access/
{
  "name": "Key for BI integration",
  "allowed_apis": [
    "customer_data",
  ],
  "allowed_ips": [
    "192.168.0.1",
    "127.0.0.0/24"
  ]
}

This will return information about how the requesting API key is configured.

# A brief note on terminology

The most basic entity in Iteras is a customer. Each customer can have one or more subscriptions to one or more products. Each subscription is cut into consecutive periods that are billed and kept track of separately.

The billing information, price etc., and the products received in the periods are configured in campaigns with each period having one campaign associated. When a subscription period runs out, the associated campaign determines if the subscription is renewed into a new period or stopped.

Some subscription products are based on giving access to something. These are typically based on time, e.g. you buy access to the subscription one year at the time.

Other subscription products are associated with concrete products, e.g. issues of a magazine through a year. The concrete products are automatically assigned to the currently active subscription periods.

It's also possible to assign individual concrete products directly to the customer, e.g. when selling a book or an event, or directly to the subscription (and not its periods) to allow customizing the subscription content beyond what can be setup with a campaign.

# Available fields

Note that you can set up what fields are available on customers, subscriptions, product assignments and campaigns inside Iteras.

Hence, to figure out what attributes are available for a certain API call, try creating a test object, say a customer, and retrieve the data for that customer through the API. If a field does not show up that way, you may need to fill it in on the object first using the Iteras UI.

# Sent and returned IDs

Campaign IDs, paywall and product names/external IDs are configured inside Iteras. Customer IDs and invoice and credit note numbers are stable.

# Language

Some parts of the API returns text intended for an end-user. The default language used is the language of the first business entity inside Iteras.

If you need to override this, you can provide a "language" query parameter, with "da" for Danish, "en" for English, "sv" for Swedish, etc., for instance: ?language=da. This query parameter also works for the POST endpoints.