Plan an API Integration - Article
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 decision | What to agree | Example consequence |
|---|---|---|
| Matching identifiers | Stable identifiers and how the connected system stores Eurekos IDs | An email change should not accidentally create a second person |
| Direction | Which system supplies each supported change | A CRM update should not overwrite a field owned by the learning team |
| Organization scope | Which organizations and suborganizations belong to the exchange | A partner-specific integration should not assume platform-wide access |
| Lifecycle | Creation, update, blocking, cancellation and deletion as separate operations | Leaving an organization may require a different action from deleting a learning record |
| Timing | Expected processing, polling and error follow-up | A 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 check | Expected result or evidence |
|---|---|
| A new partner learner is exchanged | One correct identity is created or matched; profile data and organization are as intended |
| The same record is processed again | The implemented workflow avoids unintended duplicate business records |
| An update occurs in the authoritative system | Only the intended fields change in the other system |
| An out-of-scope record is requested | Access follows the agreed permission and organization boundary |
| A credential approaches expiry | A named owner can replace it before the connection stops |
| A request fails midway through a larger operation | The 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
| Problem | What to check |
|---|---|
| The project assumes sign-in also maintains accounts | Separate OIDC/SAML authentication from provisioning and enrollment requirements |
| The integration creates duplicate records | Review matching identifiers, stored destination IDs and retry behavior in the custom implementation |
| Only part of a list arrives | Check pagination, page numbering and the applicable filters |
| The connection can access too much or too little | Review scopes, account permissions and organization boundaries together |
| Nobody knows who owns a failure | Assign the operating owner, technical owner and escalation evidence before expanding the rollout |
FAQ
-
Should I use the API instead of a built-in connector?
Use the built-in connector when its supported objects and workflow fit the requirement. Use the API for a custom exchange that needs implementation and operational ownership.
-
Is the first API response the complete list?
Not necessarily. The API uses pagination, with a default limit of 50 and zero-based page numbering. Implement the complete supported paging workflow.