Karibu ID

Developers

Connect and the reader API

Two ways in: the reader API for your own organisation’s work, and Connect for a platform acting under a company’s grant.

The reader API

A reader organisation (a bank, a buyer, an investor) works through the routes under /v1/reader/: the records companies share with it, its policies and statements, its alerts and webhooks, its invitations, tiering rules, relationships, decisions and exports.

Each call is made as a member of your organisation, with an access token (see Authentication) and X-Karibu-Organisation naming the organisation when the person belongs to more than one.

You read only what a company shares with you, while the share is live. A company that does not share with you, an unknown one and one whose share ended answer the same 404.

Connect

Connect lets a platform (a marketplace, a lender, a procurement tool) read a company’s record, run its own policy on it, hear of changes by webhook and ask for a verification, always under a grant the company agreed to: stated scopes, a stated purpose and a fixed term.

There is no lookup: a platform cannot ask whether a company exists. It starts a consent flow (POST /v1/connect/consent-sessions); the company decides, and the platform exchanges the code once for its grant (POST /v1/connect/grants/token). A revoked or expired grant answers exactly like one that never existed.

The scopes are record.summary, record.full, statements.run, alerts and verification.initiate; a call is allowed only when its grant holds the scope. Every read is recorded in the company’s access log under the platform’s name.

Conventions

Every POST takes an Idempotency-Key: a repeat with the same key and body replays the first answer; a different body is 409 idempotency_conflict.

Lists are cursor-paginated: ?limit= and the next_cursor you were given. Slow work answers 202 with a job to poll at GET /v1/me/jobs/{job_id}.

Errors are application/problem+json with a stable code, and every answer carries X-Request-Id: quote it to support.

A route of a feature switched off answers 404, exactly as an unknown route does.

Operations: Reader API

114 operations

Reader API operations in contract version 0.59.0
MethodPathOperation
GET/v1/reader/access-logReader Access Log
GET/v1/reader/access-requestsSent Access Requests
POST/v1/reader/access-requestsRequest Access
GET/v1/reader/alertsList Alerts
POST/v1/reader/alerts/{alert_id}/acknowledgeAcknowledge
GET/v1/reader/authoring-mandatesList Authoring Mandates
POST/v1/reader/authoring-mandatesGrant Authoring Mandate
POST/v1/reader/authoring-mandates/{mandate_id}/revokeRevoke Authoring Mandate
DELETE/v1/reader/auto-renewalStop Auto Renewal
GET/v1/reader/auto-renewalAuto Renewal
PUT/v1/reader/auto-renewalGive Auto Renewal
GET/v1/reader/checkouts/{checkout_id}Checkout
GET/v1/reader/connect-enrolmentMy Platform
POST/v1/reader/connect-enrolmentEnrol Platform
GET/v1/reader/contractOwn Contract
GET/v1/reader/discovery-vocabularyDiscovery Vocabulary
POST/v1/reader/discovery/matches/{match_id}/access-requestsDiscovery Access Request
POST/v1/reader/discovery/searchesDiscovery Search
GET/v1/reader/discovery/searches/{search_id}Discovery Results
GET/v1/reader/exports/{dataset}Export Dataset
GET/v1/reader/exports/audit-packs/{ke}/{pack_id}Export Audit Pack
GET/v1/reader/exports/records/{ke}Export Record
GET/v1/reader/invitationsList Invitations
POST/v1/reader/invitationsInvite Company
GET/v1/reader/invitations/{invitation_id}Read Invitation
POST/v1/reader/invitations/{invitation_id}/chaseChase Invitation
POST/v1/reader/invitations/{invitation_id}/confirmConfirm Invitation
POST/v1/reader/invitations/importsImport Invitations
GET/v1/reader/invoicesList Invoices
POST/v1/reader/invoices/{invoice_id}/checkoutsStart Payment
GET/v1/reader/invoices/{invoice_id}/payment-optionsPayment Options
GET/v1/reader/opportunity-interestsOpportunity Interests
POST/v1/reader/opportunity-interests/{share_id}/acceptAccept Interest
POST/v1/reader/opportunity-interests/{share_id}/declineDecline Interest
GET/v1/reader/organisations/{ke}/graphShared Graph
GET/v1/reader/organisations/{ke}/profileShared Profile
POST/v1/reader/organisations/{ke}/refresh-requestsRequest Refresh
GET/v1/reader/organisations/{ke}/reports/{ks}Shared Report
GET/v1/reader/payment-instructionsPayment Instructions
GET/v1/reader/policiesList Policies
POST/v1/reader/policiesCreate Policy
GET/v1/reader/policies/{policy_id}Read Policy
GET/v1/reader/policies/{policy_id}/drafts/{draft_id}Read Draft
POST/v1/reader/policies/{policy_id}/drafts/from-proseDraft From Prose
POST/v1/reader/policies/{policy_id}/testTest Policy
GET/v1/reader/policies/{policy_id}/versionsPolicy Versions
POST/v1/reader/policies/{policy_id}/versionsPublish Version
GET/v1/reader/policies/{policy_id}/versions/{version}/blocksVersion Blocks
GET/v1/reader/policies/{policy_id}/versions/{version}/readbackVersion Readback
POST/v1/reader/policies/{policy_id}/versions/{version}/testVersion Test
POST/v1/reader/policies/{policy_id}/versions/blocksPublish Blocks
DELETE/v1/reader/policy-builder/draftDiscard Policy Draft
GET/v1/reader/policy-builder/draftRead Policy Draft
PUT/v1/reader/policy-builder/draftSave Policy Draft
POST/v1/reader/policy-runsRun Policy
GET/v1/reader/policy-vocabularyPolicy Vocabulary
GET/v1/reader/portfolioRead Portfolio
GET/v1/reader/portfolio/settingsRead Portfolio Settings
PUT/v1/reader/portfolio/settingsPut Portfolio Settings
POST/v1/reader/pricing-questionnairesSubmit Pricing Questionnaire
DELETE/v1/reader/pricing-questionnaires/draftDiscard Questionnaire Draft
GET/v1/reader/pricing-questionnaires/draftRead Questionnaire Draft
PUT/v1/reader/pricing-questionnaires/draftSave Questionnaire Draft
POST/v1/reader/pricing-questionnaires/previewPreview Pricing Questionnaire
POST/v1/reader/questionnaire-requestsRequest Questionnaire
GET/v1/reader/questionnaire-templatesRead Reader Library
GET/v1/reader/quotesList Quotes
POST/v1/reader/quotes/{quote_id}/acceptAccept Quote
GET/v1/reader/reader-typeRead Reader Type
PUT/v1/reader/reader-typeSet Reader Type
GET/v1/reader/refresh-requestsRead My Refresh Requests
GET/v1/reader/relationshipsList Relationships
GET/v1/reader/relationships/{ke}Read Relationship
POST/v1/reader/relationships/{ke}/audit-packsRequest Audit Pack
GET/v1/reader/relationships/{ke}/audit-packs/{pack_id}Read Audit Pack
GET/v1/reader/relationships/{ke}/decisionsRelationship Decisions
POST/v1/reader/relationships/{ke}/decisionsRecord Decision
POST/v1/reader/relationships/{ke}/decisions/{decision_id}/approvalsApprove Decision
POST/v1/reader/relationships/{ke}/decisions/{decision_id}/overrideOverride Decision
POST/v1/reader/relationships/{ke}/factsRecord Relationship Facts
GET/v1/reader/relationships/{ke}/questionnairesRead Shared
GET/v1/reader/requirement-profilesMy Requirement Profiles
POST/v1/reader/requirement-profilesPublish Requirement Profile
DELETE/v1/reader/requirement-profiles/{profile_id}Withdraw Requirement Profile
GET/v1/reader/scope-increasesRead My Scope Increases
GET/v1/reader/service-ordersList Service Orders
POST/v1/reader/service-ordersOrder Service
GET/v1/reader/sharesList Shares
GET/v1/reader/shares/{share_id}/scopeRead My Share Scope
POST/v1/reader/shares/{share_id}/scope-increasesRequest Scope Increase
GET/v1/reader/sharing-purposesRead Reader Purposes
GET/v1/reader/sharing-scopesRead My Sharing Scopes
GET/v1/reader/ssoRead Sso
PUT/v1/reader/ssoPut Sso
GET/v1/reader/statementsList Statements
GET/v1/reader/statements/{ks}Read Statement
GET/v1/reader/statements/{ks}/summaryRead Statement Summary
GET/v1/reader/tiering-rulesRead Tiering Rules
POST/v1/reader/tiering-rulesPublish Tiering Rules
GET/v1/reader/tiering-rules/versionsTiering Rule Versions
GET/v1/reader/tiering-rules/versions/{version}Tiering Rules Version
GET/v1/reader/tiering-templatesTiering Templates
GET/v1/reader/usersList Users
POST/v1/reader/usersInvite User
DELETE/v1/reader/users/{user_id}Remove User
PATCH/v1/reader/users/{user_id}Change Role
DELETE/v1/reader/viewReset View
GET/v1/reader/viewRead View
PUT/v1/reader/viewCustomise View
GET/v1/reader/view-templatesRead View Templates
GET/v1/reader/webhooksList Webhooks
POST/v1/reader/webhooksAdd Webhook
DELETE/v1/reader/webhooks/{webhook_id}Delete Webhook
GET/v1/reader/webhooks/catalogueWebhook Events

Operations: Connect

21 operations

Connect operations in contract version 0.59.0
MethodPathOperation
POST/v1/connect/certification-runs
GET/v1/connect/certification-runs/{run_id}
PUT/v1/connect/clientConfigure Client
POST/v1/connect/consent-sessionsConsent Session
DELETE/v1/connect/grants/{grant_id}Revoke Grant
GET/v1/connect/grants/{grant_id}Read Grant
POST/v1/connect/grants/{grant_id}/policy-runsRun Policy
GET/v1/connect/grants/{grant_id}/recordRead Record
POST/v1/connect/grants/{grant_id}/verificationsInitiate Verification
GET/v1/connect/grants/{grant_id}/verifications/{kg}Verification Status
POST/v1/connect/grants/tokenExchange Code
GET/v1/connect/keysList Keys
POST/v1/connect/keysAdd Key
DELETE/v1/connect/keys/{kid}Remove Key
GET/v1/connect/policy-runs/{run_id}Policy Run
GET/v1/connect/statements/{ks}Read Statement
GET/v1/connect/usageUsage
GET/v1/connect/webhooksList Webhooks
POST/v1/connect/webhooksAdd Webhook
DELETE/v1/connect/webhooks/{webhook_id}Remove Webhook
POST/v1/connect/webhooks/{webhook_id}/testTest Webhook