Partner API

The Partner API gives partner users a company-scoped way to work with the Journeybee data shared with them. The partner surface is separate from the admin API and follows the same room, partnership, and sharing settings as the partner portal.

Base URL

https://api.journeybee.io/v1

Authentication

Partner connections use either OAuth or a partner API key. Send the credential in the Authorization header:

Authorization: Bearer <access-token-or-api-key>

OAuth (authorization-code + PKCE) is how interactive MCP clients — Claude, ChatGPT, Cursor, and similar — connect to your partnership data. Discovery and client registration happen automatically via the MCP server, so there’s nothing to configure by hand; see Partner MCP for the connect flow. For custom REST integrations, use a partner API key instead. Partner API keys are issued in the partner portal and are shown only once. Store them securely and send them as bearer credentials.

Getting started

Call GET /v1/partner/me with your credential to find out who you are and which partnerships you can act on:

curl https://api.journeybee.io/v1/partner/me \
  -H "Authorization: Bearer YOUR_CREDENTIAL"

The response includes your user identity, your read/write permissions, and the partnerships available to you — each with a uuid, name, partner_type, and status. That uuid is the {partnershipId} you send on every other request (see Company and partnership scope below).

Examples

List deals for a partnership:

curl https://api.journeybee.io/v1/partner/{partnershipId}/deals \
  -H "Authorization: Bearer YOUR_CREDENTIAL"

Create a lead:

curl -X POST https://api.journeybee.io/v1/partner/{partnershipId}/leads \
  -H "Authorization: Bearer YOUR_CREDENTIAL" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com"
  }'

API keys

Partner API keys are created and revoked on the portal’s API & MCP page. When you create one you choose read and/or write access — the same scopes an OAuth connection carries — and the full key is shown exactly once, so store it securely. A key is scoped to your partner user and the company whose portal you created it on (not to a single partnership), and starts with the jb_partner_ prefix. Each partner user may have up to 10 active keys per company — revoke ones you no longer need before creating more.

Scopes and permissions

Connections can have read and write access. Most partner operations are read-only; write endpoints require the connection to have write access. Grant only the permissions an integration needs.

Company and partnership scope

Credentials are scoped to a partner user and company. A partner can have connections for multiple companies, and each company must be authorized separately. The partnership is selected for each API request:

/v1/partner/{partnershipId}/leads
/v1/partner/{partnershipId}/deals

The API validates that the authenticated partner is an active member of the requested partnership at the credential’s company. A credential never grants access to partnerships at another company.

IDs are UUIDs

Every id in a partner API request or response is a UUID — partnership, lead, deal, tag, user, and contact ids are all uuid strings. IDs you receive back from a request round-trip directly into filters and update calls; the API never exposes numeric ids as resource identifiers. A few numeric fields do appear as display-only metadata (logo/asset ids, custom-field option ids inside options) — these are never accepted as identifiers in a request.

Responses & errors

List endpoints return a paginated envelope:

{
  "data": [],
  "pagination": { "page": 1, "per_page": 25, "total": 42, "total_pages": 2 }
}

Errors follow a single envelope:

{
  "error": { "code": "not_found", "message": "Lead not found" }
}

code is one of unauthorized, forbidden, module_disabled, not_found, validation_error, conflict, rate_limit_exceeded, or internal_error. module_disabled means the company hasn’t enabled the Partner API for its portal. Requests are rate-limited to 500 requests per minute per partner user — each partner user has their own budget, separate from other users at the same company. Exceeding it returns a 429 Too Many Requests response with a Retry-After header.

Visibility

Partner API responses follow the same visibility rules as the partner portal. Room settings, partnership settings, sharing settings, campaign sharing, and ownership rules can affect which records are visible or writable.

Reference

Every partner endpoint — full request and response schemas — is documented in the Partner API Reference section of these docs, generated from the same spec this guide describes.

​Partner API

​Base URL

​Authentication

​Getting started

​Examples

​API keys

​Scopes and permissions

​Company and partnership scope

​IDs are UUIDs

​Responses & errors

​Visibility

​Reference