Evenbead docs
Contents

Integrations

13 operations. All areas

GET/v1/integrations/providers

Every integration Evenbead has or plans: Built ones this deployment can connect, and Coming ones with their roadmap wave

  • Operation listIntegrationProviders
  • Scope: read
  • Read
Responses
  • 200 Providers (object)
  • Errors 400, 401, 403, 429, 500 (Error: error.type, message)

GET/v1/integrations/connections

This company's connections with their health (last sync, errors, "Reconnect"), clearing balance against the provider's, proposals waiting and mapping gaps

  • Operation listIntegrationConnections
  • Scope: read
  • Read
Parameters
  • include_disconnected query, boolean
Responses
  • 200 Connections (object)
  • Errors 400, 401, 403, 429, 500 (Error: error.type, message)

POST/v1/integrations/connections

Start connecting a provider: returns the provider's consent URL (OAuth 2.0 with PKCE; valid 15 minutes, shown once). The person consents there; the provider sends them back to Evenbead, which completes the connection. People with admin access only (a firm member needs "Manage integrations"); agents and AI apps are refused.

  • Operation startIntegrationConnect
  • Scope: admin
  • Write: needs Idempotency-Key (or dry_run)
Request body
  • provider string, required
  • payout_bank_account_id string
Responses
  • 201 Started (object)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/integrations/connections/complete

Finish a connect with what the provider sent back (state and code, or error): tokens are exchanged with the PKCE verifier and sealed; the connection gets its own agent ("<Provider> sync", read + propose, the posting threshold given, 0 by default), its clearing account and the default mapping. Until a person approves the mapping, everything it syncs is a proposal.

  • Operation completeIntegrationConnect
  • Scope: admin
  • Write: needs Idempotency-Key (or dry_run)
Request body
  • state string, required
  • code string
  • error string
  • posting_threshold_cents integer
Responses
  • 201 Connected (object)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/integrations/connections/{id}

One connection: health, mapping, the latest syncs

  • Operation getIntegrationConnection
  • Scope: read
  • Read
Parameters
  • id path, string, required
Responses
  • 200 Connection (object)
  • Errors 400, 401, 403, 404, 429, 500 (Error: error.type, message)

POST/v1/integrations/connections/{id}/settings

A connection's settings: the bank account its payouts arrive in (payouts are matched to that account's deposits), its agent's posting threshold (at or under it, routine postings post once the mapping is approved; above it they wait as proposals), pause or resume. People with admin access; audited.

  • Operation updateIntegrationSettings
  • Scope: admin
  • Write: sets a value, no Idempotency-Key needed
Parameters
  • id path, string, required
Request body
  • payout_bank_account_id string | null
  • posting_threshold_cents integer
  • paused boolean
Responses
  • 200 Settings (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/integrations/connections/{id}/sync

Sync now (within a minute or two, by the integrations worker)

  • Operation requestIntegrationSync
  • Scope: propose
  • Write: sets a value, no Idempotency-Key needed
Parameters
  • id path, string, required
Request body

Empty object {}.

Responses
  • 202 Requested (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/integrations/connections/{id}/disconnect

Disconnect: access is revoked at the provider, the tokens deleted, syncing stops and the connection's agent is revoked. Everything already in the books stays. Connecting the same account again later never posts anything twice.

  • Operation disconnectIntegration
  • Scope: admin
  • Write: sets a value, no Idempotency-Key needed
Parameters
  • id path, string, required
Request body
  • reason string, required
Responses
  • 200 Disconnected (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/integrations/connections/{id}/mappings

The mapping: sales categories, products, fees, taxes, discounts, shipping, tips, refunds and payouts to accounts (with class and project); '*' is each kind's default; keys seen in syncs without their own account are listed

  • Operation listIntegrationMappings
  • Scope: read
  • Read
Parameters
  • id path, string, required
Responses
  • 200 Mappings (object)
  • Errors 400, 401, 403, 404, 429, 500 (Error: error.type, message)

POST/v1/integrations/connections/{id}/mappings

Map one key to an account (and optionally a class and a project); account_code null makes a key use its kind's default. Changing the mapping withdraws its approval until a person approves it again. People with admin access; audited.

  • Operation setIntegrationMapping
  • Scope: admin
  • Write: sets a value, no Idempotency-Key needed
Parameters
  • id path, string, required
Request body
  • kind "category" | "product" | "discount" | "shipping" | "tax" | "tip" | "fee" | "refund" | "payout", required
  • source_key string, required
  • account_code string | null, required
  • class_name string | null
  • project_name string | null
Responses
  • 200 Mapped (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/integrations/connections/{id}/mappings/approve

Approve the mapping as it is: from now on routine postings at or under the agent's threshold post on their own (corrections of changed source objects always wait for a person). People with admin access; audited.

  • Operation approveIntegrationMapping
  • Scope: admin
  • Write: sets a value, no Idempotency-Key needed
Parameters
  • id path, string, required
Request body
  • note string
Responses
  • 200 Approved (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/integrations/connections/{id}/sync-runs

The sync log, newest first: trigger, outcome, counts (fetched, posted, proposed, corrected, unchanged, pending, needs review), errors

  • Operation listIntegrationSyncRuns
  • Scope: read
  • Read
Parameters
  • id path, string, required
  • limit query, integer
Responses
  • 200 Runs (object)
  • Errors 400, 401, 403, 404, 429, 500 (Error: error.type, message)

GET/v1/integrations/connections/{id}/objects

What the connection read (sales, refunds, fees, payouts by the provider's id) and what each became: posted, proposed, pending, needs review (with why), skipped, rejected; with its postings and, for payouts, the matched bank line

  • Operation listIntegrationObjects
  • Scope: read
  • Read
Parameters
  • id path, string, required
  • status query, "posted" | "proposed" | "pending" | "needs_review" | "skipped" | "rejected"
  • limit query, integer
Responses
  • 200 Objects (object)
  • Errors 400, 401, 403, 404, 429, 500 (Error: error.type, message)