Integration agreement

Security

When you are given access to our services, you are assigned a set of credentials. These credentials must be kept safe at all times, and must not be transferred or stored in an unsafe way.

• Certificate credentials: In most cases we will ask you to generate a private/public-key, and send us the public key (which is not secret). You must ensure that the private key never leaves a secure context, and never send it to anyone, including us.
  • If the private key is lost, or compromised, generate a new private key and send us the new public key as soon as possible. We will lock access using the old credentials.
  • It is your responsibility to renew credentials before they expire, and give us at least two weeks to update the public key. Make sure you have a system to get notifications in due time.
  • Credentials should never last more than 2 years. This makes sure renewals is part of the normal working process, and that any lost credentials are eventually removed.
• Token credentials: Tokens are issued once certificate credentials are presented to our token service.
  • Tokens expire very fast, usually within 60 minutes. They must be automatically renewed using certificate credentials before they expire.
  • You must cache tokens for at least 70% of the token lifetime (At least 42 minutes for a 60 minute expiry). You are not allowed to request a new token for every request to our APIs.
  • Any temporary connection strings or other secrets must also be kept as long as possible.

By integrating, you agree to:

• Keep credentials safe and never store them insecurely
• Renew credentials (tokens/certificates) before they expire
• Cache tokens for at least 70% of their lifetime
• Keep any temporary connection strings or other secrets for as much of their valid lifetime as possible, and not renew them unnecessarily often

Forwards compatibility

Our services evolve continuously. We regularly add new fields, endpoints, headers, enum values, and other extensions. These additions are not considered breaking changes, and your implementation must tolerate them gracefully.

Specifically, your implementation must:

• Ignore unknown fields in responses — do not use strict deserialization that rejects new properties
• Not rely on field ordering in JSON responses
• Tolerate new enum values — if a field gains a new value, handle it gracefully (e.g. treat it as unknown) rather than crash
• Not match on error message text — use HTTP status codes and error codes only, as message wording may change at any time
• Not hardcode URLs — obtain the service host and base path from configuration rather than embedding full URLs in code
• Tolerate new HTTP headers — do not reject responses with unexpected headers
• Not depend on undocumented behavior — only rely on what is explicitly documented. Response timing, internal headers, specific error formats, or any behavior that happens to work but is not part of the documented contract may change without notice

By integrating, you agree to:

• Build your integration to be tolerant of service extensions
• Only depend on explicitly documented behavior

Deprecation

Our services are in general backwards compatible, but sometimes functionality is changed or removed. Once you are notified that functionality is deprecated, you have minimum 6 months to change your implementation (at your own cost) to use a newer version. If this is not done, your implementation might stop working. Note: When we implement changes in our APIs that are not backwards compatible, we release this as a new version of the API. The old and new version will work in parallel. In practice, any 3rd party will most likely have at least 12 months to plan and implement support for a new version.

By integrating, you agree to:

• Update your implementation when functionality is deprecated

Release cadence

Updates to the APIs are released continuously, without specific notification to 3rd parties​, but with no downtime.

By integrating, you agree to:

• Accept that updates are continuously released without specific notification

Error handling

We cannot guarantee 100% uptime, so you should expect and handle errors at any time. This includes errors in the network between you and us, internally in our services or services we depend on.

• Retries: Most errors are transient, so the operation should be retried at least 2 times (3 total attempts including the initial request) with an appropriate back-off policy (retry after 10 seconds, then 30, then 60 etc.). We do not consider it an error until you have retried at least 2 times.
• Idempotent operations: Some operations are idempotent, and thus can be retried without any side effect. This means that if you are unsure if your request was received and handled (you did not get a response), please retry your request.
• Circuit breaking: After repeated consecutive failures, your implementation must stop retrying for a cooldown period (e.g. 1–5 minutes) before attempting again. A flood of retries during an outage puts additional strain on our services and delays recovery for all consumers.
• Timeouts: Set reasonable client-side timeouts (e.g. 30 seconds) on all requests. Do not hold connections open indefinitely waiting for a response.

By integrating, you agree to:

• Handle errors gracefully and retry with appropriate back-off
• Implement circuit-breaker logic to stop retrying after repeated failures
• Set reasonable client-side timeouts on all requests

Traffic volume

Before you start using our services, you must let us know the expected:

• Average number of requests (per hour / day / month)
• Average size of requests (in kB)
• Any expected spikes in usage (weekly campaigns, Black Friday, Christmas etc.)

You must also notify us before any significant changes in traffic patterns, such as new marketing campaigns, load tests, or onboarding of new end-users that will substantially increase volume.

We reserve the right to throttle or reject traffic that significantly exceeds agreed-upon volumes, or that threatens the stability of our services.

By integrating, you agree to:

• Provide estimated traffic volumes before starting to use our services
• Notify us before significant changes in traffic patterns
• Accept that traffic may be throttled if it exceeds agreed-upon volumes

Incorrect usage

It is important that you use our services in the expected and agreed way, this will ensure we can deliver the best possible service for all our customers/users.

• Do not send traffic to endpoints that do not exist, or to retrieve data you know does not exist
• Do not send unneeded traffic, for example when results can be cached
• Do not enumerate over all the data in the service to store it locally, unless this is explicitly agreed.
• Most services are simple request/response for single entities, if you want to synchronize all changes to data, we have separate endpoints for that.

By integrating, you agree to:

• Use services only as intended and agreed upon

Monitoring

You are responsible for monitoring the health of your own integration. This includes tracking error rates, response times, and failed requests on your side. If you detect elevated error rates, check your own implementation first before contacting us.

By integrating, you agree to:

• Monitor your own integration health (error rates, response times)
• Investigate issues on your side before escalating to us