Skip to main content

Plan an API Integration - Article

Define a reliable custom integration around business records, permissions, ownership and observable outcomes before creating API credentials.
Updated: 12 Nov 2026
5 min read

Summary

The Eurekos API lets a connected system work with supported platform records and services. A useful integration begins with a clear business flow: which records are exchanged, which system owns them, who is allowed to access them and what result the learner or administrator should see. Plan these decisions before choosing credentials or implementing requests.

Use this article to:

  • Choose an API workflow and distinguish adjacent integration routes
  • Agree record identity, direction and permissions
  • Plan a pilot, operating ownership and evidence

Describe the outcome in business terms

An equipment manufacturer might need its customer system to supply partner learners, its learning platform to manage their training and its service portal to display qualification evidence. Divide that requirement into explicit exchanges. A user account, a Training Activity enrollment and a certificate are different records; do not assume creating the first creates the others.

Write a small working agreement for each exchange: the source record, the intended destination, the matching identifier, the triggering event, the expected result and the person responsible when it fails. This makes the work reviewable by the business owner as well as the developer.

Choose API, connector, provisioning or import

Use a supported connector when it already implements the required flow. Use SCIM for the supported Microsoft Entra ID account-provisioning lifecycle. Use OIDC or SAML for authentication. A controlled file import can suit an initial migration; the API can suit a continuing exchange or a custom application.

The API is not a reason to duplicate every platform setting in another system. Decide which records must be available elsewhere and which work should remain in Eurekos. For example, a CRM may need the fact that a qualification was earned, while the full learning interaction stays in the learning platform.

Use the reference for your own platform

Open Settings → Third party integrations → API, then See documentation. The instance reference describes the current supported endpoints, authentication, request and response fields, pagination and errors. Use it when implementing the exchange rather than copying an old endpoint list from a document or another platform.

The reference documents multiple OAuth flows, including client credentials, authorization code and user credentials. Their presence is a technical contract, not a recommendation to select a flow without considering the application. Agree the appropriate flow with the integration developer and Eurekos, particularly where a user signs in through an external identity provider or the integration runs without an interactive user.

Do not put a client secret or bearer token into a browser page, a public link or an article. These are integration credentials, not the dynamic placeholders used in an email or certificate template.

Agree identity and data ownership

Design decisionWhat to agreeExample consequence
Matching identifiersStable identifiers and how the connected system stores Eurekos IDsAn email change should not accidentally create a second person
DirectionWhich system supplies each supported changeA CRM update should not overwrite a field owned by the learning team
Organization scopeWhich organizations and suborganizations belong to the exchangeA partner-specific integration should not assume platform-wide access
LifecycleCreation, update, blocking, cancellation and deletion as separate operationsLeaving an organization may require a different action from deleting a learning record
TimingExpected processing, polling and error follow-upA queued exchange should not be presented as immediate confirmation

Keep optional data truly optional in the integration. A missing profile field should not be silently converted into an invented value. Review mappings for language, dates, timezones and identifiers before using them in a customer-facing process.

Plan access and operating ownership

Client scopes define permitted API operations. The account, organization filter and relevant object permissions also matter. Selecting a scope is not a general grant to all records in every organization. Establish the intended boundaries with a permitted case and a denied case.

Use a named integration owner and an accessible operational contact. Decide who receives expiry notices, who can replace credentials and who can diagnose provider errors. A connection maintained only by one person’s memory is difficult to recover when that person is absent.

Plan request volumes and pagination with the developer. The API reference uses a default page size of 50 and zero-based page numbering. A default page is not a complete result set. Use the supported pagination to retrieve every intended record, and agree appropriate limits rather than repeatedly requesting all data unnecessarily.

Verify the integration plan

Scenario or checkExpected result or evidence
A new partner learner is exchangedOne correct identity is created or matched; profile data and organization are as intended
The same record is processed againThe implemented workflow avoids unintended duplicate business records
An update occurs in the authoritative systemOnly the intended fields change in the other system
An out-of-scope record is requestedAccess follows the agreed permission and organization boundary
A credential approaches expiryA named owner can replace it before the connection stops
A request fails midway through a larger operationThe developer can identify completed work and recover without blindly repeating business effects

Related guidance: Create and Govern an API Client; Operate and Troubleshoot an API Integration.

Troubleshooting

ProblemWhat to check
The project assumes sign-in also maintains accountsSeparate OIDC/SAML authentication from provisioning and enrollment requirements
The integration creates duplicate recordsReview matching identifiers, stored destination IDs and retry behavior in the custom implementation
Only part of a list arrivesCheck pagination, page numbering and the applicable filters
The connection can access too much or too littleReview scopes, account permissions and organization boundaries together
Nobody knows who owns a failureAssign the operating owner, technical owner and escalation evidence before expanding the rollout

Third Party Integrations

FAQ