Welcome to the Oculos Integration Platform (OIP) API documentation, a resource for better understanding of our integration platform.

This documentation is designed to be accessible and informative for both technical and sales professionals, ensuring that you can fully explore the capabilities and benefits of our API.

For technical experts, this documentation provides in-depth insights into the API endpoints, data structures, and integration possibilities. You'll find detailed explanations, code examples, and best practices to help you integrate our API into your applications and systems.

For sales persons and other non-technical stakeholders, this documentation offers a overview of the API's features, use cases, and potential business advantages.

As the configuration of OIP allows for a flexible request/reponse, only the standard data structures are displayed in this documentation.

If you have a customized configuration and need examples, please contact our support team or your sales person.

The API has two base URL's, one for production and one for testing.

Production: https://api.oculos.no/v4

Staging: https://api.staging.oculos.no/v4

Our API is designed to be secure and efficient, and it requires an API key to authenticate your requests. In this short documentation, we'll guide you on how to use our API with the x-api-key header to ensure successful integration.

Step 1: Obtain Your API Key

Before you can start using our API, you'll need to obtain an API key. This key acts as your access pass and is typically provided to you by your contact person. If you haven't received your API key, please reach out to our support team or your sales person.

Step 2: Include the x-api-key Header

To make authenticated requests to our API, you must include the API key in the header of your HTTP requests. Specifically, you should add the "x-api-key" header with your API key as its value.

x-api-key : <API KEY>

Step 3 [OPTIONAL]: White list your IP address(es) for your production environment

Although this step is optional, we strongly encourage you to send us an list of your IP addresses that are in use in your production environment.

This lets us configure OIP to only allow access to your API account from those IP's.

OIP returns a standarized detailed error message where it's possible. The structure of the error message looks like this:

{
  "code" : "409",
  "message" : "Conflict",
  "detailedErrorMessage" : {

  }
}

The detailedErrorMessage is fully dynamic and can contain a simple string aswell as a list of errors'.

By accessing or using our API (the "Service"), you agree to comply with these Terms of Use. Please read them carefully, as they govern your usage of our API.

API Usage

You are granted a non-exclusive, non-transferable, limited license to access and use our API in accordance with these terms. You may only use the API for its intended purpose and in compliance with our guidelines and documentation.

API Key

Access to the API requires an API key. Keep your API key secure and do not share it with unauthorized parties. You are responsible for all actions performed using your API key. Ensure that the API key is not visible in any way in your application.

Prohibited Actions

You may not use the API to engage in any illegal, harmful, or abusive activities. You may not decompile, reverse engineer, or attempt to gain unauthorized access to the API or our systems. You may not use the API in a way that could harm or interfere with our services, infrastructure, or other users.

Data Privacy

When using our API, you may have access to user data. Ensure you handle such data in compliance with applicable data protection laws and our privacy policy.

By using our API, you acknowledge that you have read, understood, and agreed to these Terms of Use. Failure to comply with these terms may result in the suspension or termination of your API access.

Functionality in preview

Methods marked with Preview in this API documentation are subject to change.

These methods are provided for early access to new features but may have limited support, and their behavior, parameters, or responses can be modified or deprecated without prior notice.

Use these methods with caution in production environments, as changes may impact integration stability. It is recommended to regularly check the documentation for updates when utilizing preview features.

We reserve the right to update these terms, so it is recommended to review them periodically for any changes.

Coming soon

OIP API does not have any rate limits, but some external systems integrated with OIP may have.

Exceeding these limits may result in temporary access restrictions.

We strongly recommend implementing a back-off strategy to handle rate limit exceeded responses. This strategy helps you avoid overloading our/external servers and ensures a smoother user experience.

If you are receving one of the following errors it's an indication of an issue with an external system.

{
  "code" : "429",
  "message" : "Too Many Requests",
  "detailedErrorMessage" : {
  }
}

{
  "code" : "502",
  "message" : "Bad Gateway",
  "detailedErrorMessage" : {
    "gateway" : "Connection to backend system failed. System: [system_name]",
    "gatewayMessage" : "Detailed error message here"
  }
}

Coming soon.

A webhook is a way for two different software applications to communicate with each other in real-time. It's like a notification system that triggers actions automatically when certain events occur.

Oculos can configure webhooks on request, please contact our support team for more information.

November 2024

2024-11-19

• Added endpoints for enabling/disabling of promotions (in preview)
• Added endpoint for transfering clips on loyalty cards between two existing customers (in preview)
• Minor bugfixes
• Minor bugfixes in documentation

June 2024

2024-06-18

• Added endpoint for deleting a customer by external id
• Minor bugfixes in documentation

May 2024

2024-05-22

• Added an endpoint for returning all transactions resulting in a bonus reward (https://dev.oip.oculos.no/v4#operation/getBonusTransactions)
• Added a list of promotions on the customer object when applicable. Please note that this list only will contain active promotions.
• Added information to the documentation on how to mark a transaction as a return (https://dev.oip.oculos.no/v4#operation/addTransactions)
• Minor bugfixes
• Improved performance

2024-05-14

Added new methods

• Get customer by externalId
• Update customer by externalId
• Minor bugfixes
• Improved performance

April 2024

2024-04-17

Introduced dynamic methods on the customers and promotions endpoints

March 2024

2024-03-19

Release of v4

Endpoints for managing abandoned carts

An abandoned cart function helps businesses track when online shoppers add items to their virtual shopping carts but leave the website or app without completing their purchase.

It captures data about these abandoned carts, including the specific products left behind and, when available, the customer's contact information.

The customers endpoint allows you to create, update or search for customers through various parameters depending on your configuration.

Depending on your configuration, the API may take or return additional fields in the extendedProperties object.

To get an example of your specific integration, please contact our support team.

Endpoint that lists all available consents for a client.

Depending on your configuration, the API may take or return additional fields in the extendedProperties object.

To get an example of your specific integration, please contact our support team.

Endpoint that lets you enrich member data .

Endpoint for checking OIP health status.

With these endpoint(s) you can make a request to OIP to get a quick system status.

Endpoint that provides methods for importing data, typically in batchers into OIP.

In this endpoint we can receive many formats and types, such as JSON and XML requests.

To get an example of your specific integration, please contact our support team.