Developer documentation

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 either like a browser posts a form, e.g. with the parameters application/x-www-form-urlencoded or as application/json as JSON. 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

Example with JSON:

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

{
  "id": "123456",
  "data": {
    "name": "Customer Name",
    "email": "foo@example.com",
    ":Custom field": "Some value",
    ":Custom date field": "2026-10-08"
  }
}

Authentication

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

Provide the key as a bearer token in the Authorization HTTP header, e.g. 

Authorization: Bearer 00aabbccddff112233445566778899

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

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

This also works for POST endpoints. But we strongly recommend using the header if at all possible as there is a risk of having the key inadvertently leaked in a log somewhere if it is part of the URL.

Note that you can either login or access this API documentation with the Bearer token to get examples customized to the data model of your account.

Results and error codes

Results are returned as JSON, except the CSV extracts.

Generally, errors are handled in two separate ways for convenience:

  • User input errors return an HTTP 422 status code with a JSON error object, as documented in each call (with a few exceptions that return 200).
  • Access key or incorrect requests return a plain text error response with a 40x HTTP status code, e.g. 400, 403 or 404.

Changes and events

Changes in Iteras, e.g. creating a subscription or changing a customer, are registered as events and show up inside Iteras in the history. Some of the events are internal to Iteras, but most are exposed and are useful for synchronizing data from Iteras. More on changes in the events API endpoint.

Changes through the API also result in events. If you regularly synchronize a constantly changing field, e.g. a statistic, where each update isn't interesting, you can disable event creation for a specific field in its field settings. Then changing that field does not register an event.

Trying out your access

The easiest way to try out your API access is to call the API access detail endpoint /api/access/, like this: 

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

This returns the configuration of the API key making the request.

A brief note on concepts and terminology

The most basic entity in Iteras is a customer. Each customer can have one or more subscriptions to one or more products. The subscriptions are 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. Usually subscriptions start on an introduction campaign, and then continue on to a standard campaign where they renew indefinitely.

More specifically the billing rules are set up in invoice line specifications, that are then instantiated when the subscriptions are invoiced. Note that the amount on the invoice lines is always stored and returned with tax (value-added tax, "moms").

Products

Some subscription products give access to something. These are typically based on time, e.g. you buy access to the content 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.

Group subscriptions

Subscriptions can be arranged in groups, with one subscription being the group subscription and the linked subscriptions being recipient subscriptions. The customer with the group subscription can control the recipients through it, and all invoices and payments, etc. go through the group subscription customer. This is configured through the campaign for the group subscription.

Add-on subscriptions

It's possible to have add-on subscriptions to a base subscription. The add-on subscriptions are linked to the base subscription, and stop automatically when it stops. This is configured through the campaign for the base subscription.

Available fields

You can set up what fields are available on many of the object types available in Iteras in the field settings, including customers, subscriptions and campaigns. So to figure out what attributes are available for a certain API call, try creating a test object inside Iteras, fill in the values and retrieve the data through the API.

The benefit of this setup is that if you need a field for an API integration, you can just add it and continue on. Make sure to give it a machine-readable ID.

Sent and returned IDs

Campaign IDs, paywall and product names/external IDs are configured inside Iteras and hence under your control. Customer IDs and invoice and credit note numbers are under the control of Iteras and 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.

Dates and timezones

Each Iteras account has a configured timezone. All datetime values exchanged through the API are in this timezone unless they explicitly carry an offset. Internally, Iteras stores the datetimes in UTC without an offset, reinterpreting them on the fly when displaying them.

Output format

Datetime fields are returned as ISO 8601 strings in the account's local wall-clock time, without an offset, e.g. "2026-04-20T10:30:00". Date fields (without a time component) are returned as "YYYY-MM-DD".

Input format

Datetime input is accepted in two forms:

  • With an offset, e.g. "2026-04-20T10:30:00+02:00" or "2026-04-20T08:30:00Z" — interpreted at the supplied offset.
  • Without an offset, e.g. "2026-04-20T10:30:00" — interpreted as wall-clock time in the account's configured timezone.

Date input (without a time component) is accepted as "YYYY-MM-DD".

Rate limiting

To keep the API reliable for everyone, we enforce limits on both the number of connections and the request rate per client.

Connection limits

  • Each client can have up to 5 active connections at a time.
  • Across all clients, the service supports up to 50 active connections in total.
  • If these limits are exceeded, new connections are rejected with HTTP 429 Too Many Requests.

Request rate limits

  • Each client can make up to 5 requests per second on average.
  • Short spikes are allowed — up to 20 extra requests may be accepted in quick succession, with 5 handled immediately and the rest queued briefly.
  • If the queue fills, any additional requests are rejected with HTTP 429 Too Many Requests.

In summary

Sustained traffic within the normal rate is always accepted. Short bursts are tolerated, but ongoing high-volume traffic will be throttled or temporarily rejected until the rate decreases.