AI assistant connector

The AI assistant connector lets an AI assistant — Claude, ChatGPT, Cursor, VS Code, Gemini CLI or your own application — read your Base data and answer questions about it in plain language: "Who is on top of the leaderboard?", "How many asks are active?", "Which reference requests are due this month?".

It is read-only unless you allow more. A connector token with no extra permission can look things up and cannot create, change or delete anything in Base, whatever it is asked to do. When you generate the token you can also let the assistant read ask responses, and — if connector write-back is switched on for your company — credit activities, grant points, import and update contacts and send invites. The assistant only ever sees the tools its token allows.

The connector speaks the Model Context Protocol (MCP) over HTTP. If your assistant supports MCP servers over HTTP, it works with Base.

Create a connector link

You need to be a Base admin (company owner or IT role).

1. Open Settings → Users & team → API tokens and click Generate token.
2. Give the token a name (no spaces) and, optionally, a comment.
3. Under Token type choose AI assistant connector.
4. Under Permissions choose what the assistant may do (see Permissions). Company data is always on; every other permission is off until you tick it. Leave them all off for a read-only connector.
5. Tick the acknowledgement. It names what the token allows — an assistant using this connector can read your advocates (names, emails and consent status), accounts, opportunities, asks, nominations and reference requests, plus whatever you allowed under Make changes, without a review step.
6. Click Generate token.

A token's permissions are fixed for its life: rotating keeps them, and to change them you generate a new token and delete the old one. The token list shows them in the Permissions column, and the pill next to the name reads Read only or Read & write. Generating a token records its permissions in the Audit log.

The dialog shows the connector link once. Copy it now; it cannot be shown again (you can always rotate the token to get a new one).

The link has the form:

https://<api host>/mcp/k/<token>

The same dialog offers two ways to connect:

• Link (no authentication needed) — the URL above. For chat products that can only take a URL.
• IDE / CLI header — the endpoint https://<api host>/mcp with the header Authorization: Bearer <token>. For tools that let you set request headers. The dialog gives you a ready-made Claude Code command.

Both forms carry the same token and give the same access. Treat the link like a password: anyone holding it can read your company's data through the connector — and, when the token has a Make changes permission, change it.

Connect your assistant

Claude Code

claude mcp add --transport http base https://<api host>/mcp --header "Authorization: Bearer <token>"

Then in a session, type /mcp to confirm the base server is connected, and ask away.

Cursor

Add to ~/.cursor/mcp.json (or the project's .cursor/mcp.json):

{
  "mcpServers": {
    "base": {
      "url": "https://<api host>/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

VS Code (GitHub Copilot agent mode)

Add to .vscode/mcp.json:

{
  "servers": {
    "base": {
      "type": "http",
      "url": "https://<api host>/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "base": {
      "httpUrl": "https://<api host>/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

claude.ai (custom connector)

In claude.ai go to Settings → Connectors → Add custom connector.

• Link variant: paste the connector link https://<api host>/mcp/k/<token> as the server URL and choose no authentication. The token travels inside the link.
• Header variant (beta): use https://<api host>/mcp as the server URL and add a request header Authorization with the value Bearer <token>.

Enable the connector in the chat's tools menu; Claude will then call it when a question needs Base data.

ChatGPT (custom connector)

Paste the connector link https://<api host>/mcp/k/<token> as the MCP server URL and choose no authentication. ChatGPT reaches every tool from deep research and developer mode. Its built-in search-style discovery (the tools it looks up by the names search and fetch) is not supported yet: the connector names them search_records and fetch_record, so ask from deep research or developer mode.

Anthropic Messages API (your own application)

Pass the connector as an MCP server on the request. The token goes in authorization_token; the mcp_toolset entry is required and must name the same server.

{
  "model": "claude-opus-5",
  "max_tokens": 16000,
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://<api host>/mcp",
      "name": "base",
      "authorization_token": "<token>"
    }
  ],
  "tools": [{ "type": "mcp_toolset", "mcp_server_name": "base" }],
  "messages": [{ "role": "user", "content": "How many advocates do we have?" }]
}

Send it to POST https://api.anthropic.com/v1/messages with the header anthropic-beta: mcp-client-2025-11-20.

Permissions

Ask responses and Make changes are offered only when connector write-back is switched on for your company. Any Make changes permission shows the warning "An assistant with this link can change data in Base. Every change shows in Connector usage."

What the assistant can do

Every tool calls the Base Public API and nothing else — same checks, same refusals, same field names, same page-size limits (500 rows per page, or 100 for the reference tools and ask responses; the one exception is list_custom_attribute_values, which pages the values of one attribute itself, 200 per page). Most tools are a single call; a few combine the routes named under Reads below (search_records up to nine reads, fetch_record up to four pages for an ask), and trigger_activities, grant_points and update_advocate_attributes make one call per row. Every list tool accepts countOnly: true so "how many" questions do not page through rows. Nothing outside this list is reachable, and a tool whose permission the token lacks is neither listed nor callable.

Rules for every change

• The assistant asks first. Before every change it says in plain words what will change and for how many rows, and waits for your yes. For invites it lists who will be emailed and waits for a yes in a separate message — never in the same step as an import.
• 1 to 100 rows per call. An empty list or more than 100 rows refuses the whole call. Each row is then checked on its own: a row Base refuses fails alone and the others still go through. A repeated email in one invite or contact import call (or a repeated CRM contact id) is sent once, under its first row; each later copy keeps its own line and fails as a repeat. Importing contacts never invites anyone: a new contact is not invited until send_invites.
• Time and the request limit. Crediting an activity, granting points and updating attributes send one request per row, each counting against the 100 requests a minute, and stop at the limit or after at most 2 minutes (sooner when the connector's short sign-in session is about to run out); rows they did not reach come back as "Not sent". When Base does not answer, the rows of that request come back as "may or may not have been applied" — check them in Base before sending them again. "Today" is Base's date.
• A summary and one line per row. The result counts the rows sent, succeeded and failed, and gives every row its outcome and, when it failed, why (for example "Advocate not found", "Already recorded", "Activity does not exist. Find the API identifier with list_activities."). The assistant reports every failed row, and every past activity imported with "points not synced" (saved, but its points did not reach the leaderboard).
• Retries. Crediting an activity and importing past activities skip what is already recorded, so a retried call only adds what is missing. Granting points grants again: before retrying, the assistant reads the advocates' points with get_advocate_leaderboard_entry and resends only the rows that did not apply.
• No email from imports. Importing contacts never invites anyone; only send_invites emails.

The assistant picks the tools itself; the reference below is generated from the connector's own tool registry and republished with every change to it, so it is exactly what the assistant can see. "Needs the permission" names the permission a tool needs; the parameter tables give every value rule.

Every tool only reads, except the ones under "Make changes". A tool that needs a permission is offered only to a connector token an admin gave that permission; every other tool is offered to every connector token. "Reads" and "Writes" name the public API routes a tool can call; the parameters are what the assistant may pass.

Discovery

get_company_profile — Get company profile

Return the profile of the company this connector belongs to (currently its name). Use it to confirm the connector works and to learn which company every other result describes.

Reads: GET /api/v1/status

No parameters.

list_activity_types — List activity types

Return every activity type defined for the company: its stable name, whether it needs advocate consent, and the allowed frequencies and classifications. Activity types are the vocabulary other tools use to filter engagement, so read them once before filtering by type name. Nominations carry their own type names (activityTypeName, for example Quote). Filter list_nominations by those, not by this list.

Reads: GET /api/v1/activity-types

No parameters.

describe_custom_attributes — Describe custom attributes

Return the custom attribute definitions of the company grouped by entity: contact (advocate), account, opportunity and nomination. Each definition carries the attribute name used in every other tool output, its label, type, whether advocates can edit it and valueCount, the number of allowed values of an enumerated attribute; the values themselves are listed by list_custom_attribute_values. Narrow with entity and nameContains. Read this before interpreting customAttributes values.

Reads: GET /api/v1/custom-attributes

describe_custom_objects — Describe custom objects

Return the custom object types (for example subscription, primary_contact) defined in Base for the company, grouped by the entity they attach to: contact (advocate), account, opportunity and nomination; objects synced from the CRM are not part of the public API and are not listed. Each object lists its apiName, label, the attributes its records carry (with valueCount instead of the enumerated values, which list_custom_attribute_values lists) and its CRM mappings. Use the apiName as objectName when reading custom object records. Narrow with entity.

Reads: GET /api/v1/custom-object-mapping, GET /api/v1/custom-object-attributes

list_custom_attribute_values — List custom attribute values

List the allowed values of one enumerated custom attribute, one row per value, paged (at most 200 per page). Definitions from describe_custom_attributes and describe_custom_objects only carry valueCount; use this tool to see the values themselves, narrow them with search, or count them with countOnly.

Reads: GET /api/v1/custom-attributes, GET /api/v1/custom-object-mapping

list_content_tags — List content tags

List the content tags of the company with how many items carry each tag and the category it belongs to. Filter by a name fragment or by content category; use countOnly for "how many tags" questions.

Reads: GET /api/v1/content-tags

list_content_categories — List content categories

List the content categories of the company with the number of tags in each. Filter by a name fragment; use the category uuid to narrow list_content_tags.

Reads: GET /api/v1/content-categories

get_reference_request_form_settings — Get reference request form settings

Return how the reference request form is configured for the company: enabled fields and their labels, contact limits, active reference types, allowed reference managers and the custom attributes it shows. Pass the CRM account, opportunity and reference type as context to see the rules that apply to that combination.

Reads: POST /api/v1/reference-requests/form

Advocates

list_users — List users

List the users (advocates) of the company as a basic profile: id, email, name, activation state, registration status and custom attribute values. Pass emails to look specific people up. For account linkage, points, consents and engagement use list_advocates instead. Counts user profiles. For advocate counts use list_advocates.

Reads: GET /api/v1/users

get_user — Get user

Return one user (advocate) of the company by id, with the custom attribute values set on them. Use find_advocate_by_email when you only know the email.

Reads: GET /api/v1/users/{id}

list_advocates — List advocates

List the advocates of the company. By default (detail: compact) each row carries the identity and summary fields: uuid, email, name, CRM contact id, account, points, credits, rank, registration status, dates, engagement score total and level; detail: full adds consents, recent activities, custom attribute values, custom object values and the profile image, which makes rows several KB each. Filter to one advocate by uuid or email; emailContains and nameContains match within the requested page (page through with size 500 for an exhaustive search) and, when used, pagination.totalElements is omitted while hasMore keeps its upstream meaning. An email that matches nobody returns an empty page. Use countOnly for "how many advocates" questions (not combinable with the page filters). rankPosition in list rows is 0; the API fills it only when one advocate is read by uuid or email. Use get_advocate_leaderboard_entry or get_leaderboard for ranks. list_advocates counts advocates, list_users counts user profiles and get_leaderboard lists advocates with a leaderboard entry, so their totals differ.

Reads: GET /api/v1/advocate

find_advocate_by_email — Find advocate by email

Return the single advocate with this email. detail: compact (default) returns the identity and summary fields; detail: full adds consents, activities (which can hold the whole history, more than 1,000 entries), custom attribute values and custom object values. The email is matched as stored in Base, so pass it as it appears there. Fails with NOT_FOUND when nobody in the company has that email.

Reads: GET /api/v1/advocate

list_advocates_changed_since — List advocates changed since

List the advocates sourced from one external system that changed at or after a point in time, with their CRM id, points and badges. Meant for incremental sync questions ("who changed since yesterday"). pagination.totalElements counts every advocate that changed; a page only carries those mapped to the given external system, so a page can be empty while the total is not. For advocates without a CRM mapping use list_advocates.

Reads: GET /api/v1/users-by-dates

get_advocate_custom_attributes — Get advocate custom attributes

Return the custom attribute values of up to 100 advocates, keyed by advocate uuid. Each entry carries the attribute name, label, type and uuid with the advocate's values (never the attribute's allowed-value list); an advocate with no values maps to an empty list. Use describe_custom_attributes to interpret the attribute names.

Reads: GET /api/v1/advocate/custom-attributes

list_advocate_attribute_values_changed_since — List advocate attribute values changed since

List the values of the given custom attributes across advocates that changed at or after a point in time, one row per advocate and attribute with the advocate uuid and CRM id. Meant for incremental sync questions.

Reads: GET /api/v1/advocate/custom-attributes/field-value

list_advocate_custom_object_records — List advocate custom object records

Return the records of one custom object (for example subscription) attached to one advocate, identified by uuid or email, each with its record id and attribute values. Narrow to one record with instanceId.

Reads: GET /api/v1/advocate/custom-object-record/{objectName}

Accounts and opportunities

list_accounts — List accounts

List the accounts (customer companies) of the company with domain, size, industry, CRM id, reference status, points and custom attribute values. Pass uuids to read specific accounts; use countOnly for "how many accounts" questions. The API has no name filter. To find an account by name use search_records, or page through with size 500.

Reads: GET /api/v1/account

list_account_custom_object_records — List account custom object records

Return the records of one custom object (for example primary_contact) attached to one account, identified by uuid or name, each with its record id and attribute values. Narrow to one record with instanceId.

Reads: GET /api/v1/account/custom-object-record/{objectName}

list_opportunities — List opportunities

List the sales opportunities known to the company with stage, amount, probability, close date, account name and custom attribute values. Pass uuids to read specific opportunities; use countOnly for "how many" questions.

Reads: GET /api/v1/opportunity

get_opportunity_by_crm_id — Get opportunity by CRM id

Return one opportunity by its CRM id with stage, amount, probability, close date, account name and its custom attribute values as a name-to-value map. Fails with NOT_FOUND when the CRM id is unknown to the company.

Reads: GET /api/v1/opportunity-attributes/{id}

Asks and engagement

list_asks — List asks

List the asks (what the company asks its advocates to do) with their type, schedule, trigger and tags. Active and inactive asks are returned alike and the public API offers no filters, so page through and narrow by active, challengeType, tags or dates yourself. Descriptions are plain text. Use countOnly for "how many" questions.

Reads: GET /api/v1/challenge

list_ask_responses — List ask responses

Read what advocates submitted for one ask: who responded, the response's status (Completed, Approved, Second approval, Rejected), when it was completed, the points it earned and every answer. Find the ask id with list_asks first. For a survey each answer is a question and its answer; for other asks each submitted field and its value. Answers are plain text and an uploaded file shows by its file name. Up to 100 responses per page; use countOnly for "how many". An ask nobody completed returns an empty page.

Needs the permission: Ask responses (ask_responses:read)

Reads: GET /api/v1/challenge/{uuid}/records

list_activities — List activities

List the activities advocates can be credited for (name, description, points, apiIdentifier, category, whether badges are assigned). Paging is the only input: the public API offers no filters for this list, so page through and filter by category or points yourself. Use countOnly for "how many" questions. This is the catalog of activities advocates can earn points for, not a record of what advocates did. No tool returns activity history by date.

Reads: GET /api/v1/activity

get_leaderboard — Get leaderboard

Rank advocates by points, highest first, with credits and rank position. Emails are omitted unless includeEmails is true. Page with page and size; the order is stable across pages. Use countOnly for "how many" questions. Points are lifetime totals. rankPosition counts from 1 and matches the Global rank on the advocate's profile. The profile's Company rank is not available.

Reads: GET /api/v1/leaderboard

get_advocate_leaderboard_entry — Get advocate leaderboard entry

Return one advocate's leaderboard entry (points, credits, rank position) by email, without walking the whole leaderboard. Fails with NOT_FOUND when no advocate has that email. Points are lifetime totals. rankPosition counts from 1 and matches the Global rank on the advocate's profile. The profile's Company rank is not available.

Reads: GET /api/v1/leaderboard-by-email

Reference requests and nominations

list_reference_requests — List reference requests

List reference requests (a salesperson asking for a customer reference) with their opportunity, the sourced advocate and the reference record; detail: full adds the advocate history, custom attribute values, custom object values, custom attribute filters and links. Filter by creation date (dateFrom/dateTo), opportunity, reference manager, reference type, account, status, reference record status, idle time or free text. dueFrom/dueTo filter by the deadline within the requested page (page through with size 100 for an exhaustive answer) and, when used, pagination.totalElements is omitted while hasMore keeps its upstream meaning; notes says how many requests the page checked and which page to read next. Use countOnly for "how many" questions (not combinable with dueFrom/dueTo). status takes keys and rows show labels: INITIAL = Registered, SOURCING_A_REFERENCE = Waiting Approval, REJECTED = Rejected, CANCELED = Canceled, REFERENCE_SOURCED = Reference Sourced, OWNER_REJECTED = Contact Owner Rejected, OWNER_APPROVED = Contact Owner Approved, PENDING_APPROVAL = Pending Reference Approval, REFERENCE_REJECTED = Reference Rejected, REFERENCE_PROVIDED = Received Reference, REFERENCE_INTRODUCED = Reference Introduced, REFERENCE_CONTACTED = Reference Contacted, REFERENCE_NOT_CONTACTED = Reference Not Contacted. Open requests, as Base counts them on Home, are every status except REFERENCE_CONTACTED, REJECTED and CANCELED, with referenceRecordStatus [ACTIVE] and includeEmptyReferenceRecordStatus true. With countOnly that gives the Home number.

Reads: GET /api/v1/reference-requests

list_ranked_reference_advocates — List ranked reference advocates

Rank the advocates eligible to give a reference by how well they match weighted criteria (industry, location, seniority, job title, account size, products, use cases, custom attributes, reference score) and return them best match first with their availability and reference history. Every criterion is optional. Use countOnly for "how many" questions. seniorityLevels, geographicalLocations and industryTypes take numeric ids that no tool lists. Rank by jobTitles or searchCriteria text instead.

Reads: POST /api/v1/reference-advocates/report

list_nominations — List nominations

List nominations (a salesperson or marketer putting an advocate forward for a case study, reference, review, ...) created in a date range, with their status, comments, the advocate and account, and the ask they came from. dateFrom and dateTo are required and at most 366 days apart. The report is not paged: count is the number of matches and at most 500 are returned; when truncated is true narrow the date range or filters. Repeat nominations are left out unless includeRepeatedNominations is true; the counts on Base's Home include them. Statuses come back as keys, which Base shows as INITIAL = Registered, IN_PROGRESS = In progress, APPROVED = Approved, REJECTED = Rejected, COMPLETED = Completed.

Reads: POST /api/v1/nomination

Search

search_records — Search records

Search advocates (by exact email, or by email and name containing the text), accounts (by name) and asks (by title) in one call and return typed ids (advocate:<uuid>, account:<uuid>, ask:<uuid>) with a title and link; pass an id to fetch_record for the full record. Advocates are searched by the API; only the first 2000 accounts and asks are scanned, and truncated is true when more matches may exist: beyond that window, past the time budget, or because the limit was reached first — use the list tools for exhaustive answers. When truncated is true, tell the user the search was partial (notes says how much was searched); do not say the record does not exist.

Reads: GET /api/v1/advocate, GET /api/v1/account, GET /api/v1/challenge

fetch_record — Fetch record

Fetch the full record behind a typed id returned by search_records (advocate:<uuid>, account:<uuid> or ask:<uuid>): a title, a plain-text summary, a link and the documented fields as metadata.

Reads: GET /api/v1/advocate, GET /api/v1/account, GET /api/v1/challenge

Make changes

trigger_activities — Trigger activities

Credit advocates for an activity that happened today (Base's date, which can differ from the user's near midnight), with the activity's points, credits, badge and gift and an activity feed entry, as an automated activity would. Find the activity and its apiIdentifier with list_activities first; an activity without an apiIdentifier cannot be triggered, use import_past_activities for it. Before calling, tell the user in plain words what will change and for how many rows, and wait for their yes. Unknown emails fail as "Advocate not found"; no advocate is created. The same advocate and activity on the same day returns "Already recorded", so a retried call only records the rows that are missing. Each row is one request against the token's 100 requests a minute; a call stops at that limit or after at most 2 minutes, and rows it did not reach come back as "Not sent" to send again later. Read the summary in the result and report every failed row with its reason.

Needs the permission: Credit activities (activities:write)

Writes: POST /api/v1/trigger-activity

import_past_activities — Import past activities

Credit advocates for activities that already happened, as the Previous activities import does, without a file and without the result email. Find the activity type names with list_activity_types first; the type must exist, and the activity is found by name under it or created there (a name that belongs to another type fails the row). An email not in Base creates the contact, who is not invited. Before calling, tell the user in plain words what will change and for how many rows, and wait for their yes. Say how many contacts will be created. The same advocate, activity and date fails as "Already recorded", whether in Base or earlier in the same call. Read the summary in the result and report every failed row with its reason. Also report every row imported with "points not synced": the activity was saved but its points did not reach the leaderboard, so the user must check that advocate's points.

Needs the permission: Credit activities (activities:write)

Writes: POST /api/v1/activity/import-by-email

grant_points — Grant points

Add or take away points and credits. Points raise an advocate's lifetime points (and can earn points badges); credits raise the balance they can redeem. Leaving credits out grants 0 credits, so ask the user whether the points should also be redeemable and pass credits when they should. Negative numbers take away; neither total may go below 0 and credits may not exceed points, and a row that would break that fails with the reason. The grant shows in the points grant history with the reason and "API". Before calling, tell the user in plain words what will change and for how many rows, and wait for their yes. Unknown emails fail as "Advocate not found". Each row is one request against the token's 100 requests a minute; a call stops at that limit or after at most 2 minutes, and rows it did not reach come back as "Not sent" to send again later. Read the summary in the result and report every failed row with its reason. A retried call grants again: before retrying a call that failed or timed out, read each advocate's points with get_advocate_leaderboard_entry and resend only the rows that were not applied.

Needs the permission: Grant points (points:write)

Writes: PUT /api/v1/points/grant-points

import_contacts — Import contacts

Create or update contacts by email, as Import contacts does: an existing email updates that contact; a new email creates a contact who is not invited yet (no email is sent), so invite them with send_invites. A new email needs firstName and accountName; an existing contact keeps the ones it has when they are left out or blank, and one without an account yet needs accountName. First and last name change only while the contact is not invited yet: an invited or joined contact keeps their name. An import never moves a contact to another account, and keeps their target crowd. When a name or account was not changed, the row says so in its note, so never tell the user it changed; a saved row can also carry a warning in its note, which you report. A contact who asked to join fails with its reason and nothing changed, as importing them would invite them. Optionally set consents (activity type ids from list_activity_types) and reference pool membership. Never emails anyone; use send_invites for that, separately. Check who already exists with list_advocates first. Before calling, tell the user in plain words what will change and for how many rows, and wait for their yes. Say how many contacts are new and how many will be updated. The same email twice in one call (in any case) is imported once, under its first row; each later copy fails as repeated. Each row reports Created, Updated or Imported (when Base does not say which), with the consents applied and rejected. Read the summary in the result and report every failed row with its reason.

Needs the permission: Import contacts (contacts:write)

Writes: POST /api/v1/advocate/import-by-email

import_crm_contacts — Import contacts from the CRM

Create or update contacts from the company's connected CRM by the CRM's own contact id (for example a Salesforce contact id): Base reads the name, email and account from the CRM. Works only for a company with a connected CRM; an id the CRM does not return fails that row as "Contact not found in the CRM (or the CRM connection needs reconnecting in Base)", and a CRM Base could not read fails every row with "Base could not read the CRM". The same id twice in one call is imported once, under its first row; each later copy fails as repeated. Optionally set consents (activity type ids from list_activity_types) and reference pool membership. Never emails anyone; use send_invites for that, separately. Check who already exists with list_advocates first. Before calling, tell the user in plain words what will change and for how many rows, and wait for their yes. Read the summary in the result and report every failed row with its reason.

Needs the permission: Import contacts (contacts:write)

Writes: POST /api/v1/advocate/import-by-contact-id

update_advocate_attributes — Update contact attributes

Set custom attribute values on contacts by email. Find the attribute names, and which take a single value, with describe_custom_attributes first. The values given replace the current ones; a single-value attribute takes exactly one, and every attribute needs at least one value (this tool never clears one). An unknown attribute name is reported as "Not found" while the others are still saved; a single-value attribute given several values fails the whole row, and nothing in it is saved. An unknown email fails as "Advocate not found". Before calling, tell the user in plain words what will change and for how many rows, and wait for their yes. Each row is one request against the token's 100 requests a minute; a call stops at that limit or after at most 2 minutes, and rows it did not reach come back as "Not sent" to send again later. Read the summary in the result and report every failed row with its reason.

Needs the permission: Import contacts (contacts:write)

Writes: PUT /api/v1/advocate/custom-attributes

send_invites — Send invites

Email contacts the same invitation as Invite / Re-invite on Users & accounts. A pending contact gets the invite whether or not they were invited before; a contact who already joined is skipped as "Already active"; an unknown email fails as "Contact not found". A repeated email is invited once, under its first row. Find the contacts with list_advocates first. Before calling, tell the user in plain words what will change and for how many rows, and wait for their yes. The emails cannot be taken back, so confirm strictly: list the names and the count of who will be emailed, and call this tool only after the user says yes in a separate message. Never send invites in the same step as an import, even when the user asked for both. Read the summary in the result and report every failed row with its reason.

Needs the permission: Send invites (invites:write)

Writes: POST /api/v1/advocate/invite

Limits

• 100 requests per minute per connector token, shared with any other use of the same token on the public API (full-access API tokens are not rate-limited). Every API request a tool makes counts: crediting an activity, granting points and updating attributes spend one request per row, so a large call can reach the limit part-way; its remaining rows then come back as "Not sent" and can be sent again a minute later. Above the limit a tool call answers a RATE_LIMITED error carrying retryAfterSeconds, and the assistant will usually tell you to try again in a moment. (An HTTP 429 with a Retry-After header is only answered when the connector itself is asked to open too many sessions — 30 per minute per token.)
• Results larger than 1 MB are refused with a readable error asking for a smaller page or narrower filters. Ask the assistant for a smaller page or a count.
• Pages are capped at 500 rows (100 for the reference tools, and 100 for list_advocates with detail: full). list_activities and list_asks have paging only — the assistant filters by category, points or status itself.
• A tool call is one public API call, except the few tools above that combine reads or call once per row; each of those requests counts against the limit. The assistant may make several tool calls to answer one question.
• Changes are limited to 100 rows per tool call.

Errors

Errors are readable sentences, never stack traces. 401 and 403 answers also carry a machine-readable code (additionalInfo.code) so the connector can tell them apart. The ones you may see quoted by the assistant:

Revoking access

Everything happens in the same API tokens table:

• Deactivate the token (status switch) — the connector stops within seconds; you can reactivate later.
• Rotate the token — the old link stops working immediately and a new link is shown once.
• Delete the token — permanent.

Base staff can also switch the connector off for a company; existing connector tokens then stop working immediately and the table shows Disabled by Base next to them.

If a link leaks, rotate the token. A leaked connector token is useless outside the connector: presented directly to the public API it is refused with This token can only be used through the AI assistant connector.

Usage

Every public API call the assistant makes — including refused ones and every change — is recorded with its tool, API path, status, duration, client name and time, and for a change the rows sent, succeeded and failed (a dash for a read). Rows sent are the rows that reached Base: a repeated row the assistant catches shows as failed in the chat, not in these counts. It shows in the token's Usage drawer (the chart icon on the token row) for the last 180 days. A usage row never holds the arguments or the data returned: no names, emails, points or answers. Calls stopped by the rate limit are not recorded, and under very heavy load a row can be dropped rather than slow the call down.

Each change that went through also adds an Audit log row whose User is the token. Its details name the contacts the change touched, by email (or by CRM contact id for an import by contact id), so the Audit log and its export do hold those emails. Points granted through the connector show in the points grant history with the reason and "API".

Privacy

The connector gives the assistant you connect the same view of your company as a read-only API token: advocate names, emails, consent state, points, custom attributes, accounts and opportunities — plus ask responses when you allow them. That data flows to the assistant provider you connect (Anthropic, OpenAI, Cursor, Google or your own application) under that provider's terms. Connect only assistants your organisation has approved for customer data, and rotate the token when people who knew the link leave.

Questions: support@base.ai.