API docs by Redocly

ultra-api CRM Agent API (1.0.0)

Download OpenAPI specification:

License: MIT

Contract-first OpenAPI spec for an AI-agent optimized CRM surface.

This API is not a raw mirror of the existing CRM routes. It exposes a small tool layer that an agent can call with explicit workspace scope, predictable inputs, audit context, and bounded outputs.

How to use this reference

The CRM Agent API has only two HTTP operations:

  1. Discover available tools with GET /crm/agent/capabilities.
  2. Execute exactly one tool with POST /crm/agent/tools/{toolName}.

Authentication

All endpoints require a super-admin Bearer token. Non-super-admin tokens are rejected even if the user belongs to the target organization.

CRM Module prerequisite

All workspace-scoped v1 tools require the outbound CRM module to be enabled on the target organization. If the module is disabled the tool returns 403. crm_resolve_workspace is the only unscoped discovery tool and can be called before the technical organization ID is known.

Workspace Scope

Workspace-scoped tool calls require organizationId. Agents that only have a human name, slug, owner email, or ambiguous operator input must first call crm_resolve_workspace, then use the returned technical organizationId for subsequent scoped tools.

Response Envelope

{ "success": true|false, "data": ..., "error": "...", "meta": {...} }

Tool Contract

GET /crm/agent/capabilities lists available tools and their JSON schemas. POST /crm/agent/tools/{toolName} executes one tool with a single scoped input payload.

Tool Families (v1)

Family Tools
Workspace resolution crm_resolve_workspace
Outbound Operations get_crm_workspace_overview, list_outbound_agents, bulk_get_agent_workloads, list_campaigns, get_campaign, create_outbound_campaign, update_outbound_campaign, attach_campaign_templates, bulk_add_contacts_to_campaign_by_filter, bulk_remove_contacts_from_campaign, find_contacts_in_multiple_campaigns, get_campaign_contact_overlap, bulk_get_campaign_contact_counts, analyze_import_contact_deduplication, bulk_assign_campaign_contacts, list_outbound_contacts
Script Templates list_script_templates, get_script_template, create_script_template, update_script_template, delete_script_template, import_script_templates, export_script_template
Qualification Templates list_qualification_templates, get_qualification_template, create_qualification_template, update_qualification_template, import_qualification_templates, export_qualification_template
Script Executions get_script_execution, upsert_script_execution
Qualifications get_qualification_schema, get_qualification, create_qualification, update_qualification, list_qualifications

Outbound operation tools let an AI agent inspect workspace state, create or update campaigns, attach script/qualification templates, add contacts from a CRM/import-folder filter, analyze import deduplication, compare campaign overlaps, and assign campaign contacts in bulk. Use find_contacts_in_multiple_campaigns, get_campaign_contact_overlap, and bulk_get_campaign_contact_counts instead of paginating list_outbound_contacts for multi-campaign comparisons. Mutating bulk tools expose dryRun; campaign assignment and campaign contact removal require confirm: true when applying the preview. Removing contacts deletes the campaign-specific outbound state, can target contacts also present in other campaigns, cancels pending/overdue campaign follow-ups by default, and preserves call history unless the caller explicitly asks to detach call logs.

CRM Call Script Authoring Rules

Script templates are interactive call paths, not internal CRM notes. Use instruction for text the agent should read, then question only for a free-form captured answer. Use yesno for binary choices with branches labelled Oui and Non; use select for multi-choice decisions and make each branch label match one of the declared options values.

Auto-qualify sends only the branch path selected by recorded agent responses to the AI server. Unmatched branch labels hide downstream context. Keep admin-only reminders such as "Reporter dans le CRM" out of agent-facing script text; represent captured data in the qualification template instead.

1. Capability Discovery

Tool discovery and schema metadata

Discover available CRM agent tools

Returns the list of available tools with their input/output schemas, risk levels, and usage examples. Pass organizationId to verify the organization exists and the CRM app is enabled before fetching the full catalog.

Authorizations:
bearerAuth
query Parameters
organizationId
string

Optional workspace filter for capability checks.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "error": "string",
  • "meta": {
    }
}

2. Tool Execution

Scoped CRM tool execution

Execute a CRM agent tool

Executes the named tool with the provided workspace scope and input.

The reason field is logged in the audit trail. The requestId can be used for idempotency or trace correlation.

Tools that support dryRun accept input.dryRun: true to validate and preview the operation without persisting any changes.

Risky delete/bulk tools additionally require input.confirm: true when input.dryRun: false.

Authorizations:
bearerAuth
path Parameters
toolName
required
string (CrmAgentToolName)
Enum: "crm_resolve_workspace" "get_crm_workspace_overview" "list_outbound_agents" "bulk_get_agent_workloads" "list_campaigns" "get_campaign" "create_outbound_campaign" "update_outbound_campaign" "attach_campaign_templates" "bulk_add_contacts_to_campaign_by_filter" "bulk_remove_contacts_from_campaign" "find_contacts_in_multiple_campaigns" "get_campaign_contact_overlap" "bulk_get_campaign_contact_counts" "analyze_import_contact_deduplication" "bulk_assign_campaign_contacts" "list_outbound_contacts" "list_script_templates" "get_script_template" "create_script_template" "update_script_template" "delete_script_template" "import_script_templates" "export_script_template" "list_qualification_templates" "get_qualification_template" "create_qualification_template" "update_qualification_template" "import_qualification_templates" "export_qualification_template" "get_script_execution" "upsert_script_execution" "get_qualification_schema" "get_qualification" "create_qualification" "update_qualification" "list_qualifications"
Request Body schema: application/json
required
organizationId
string

Explicit target CRM organization ID. Required for every scoped tool; omitted only for unscoped tools such as crm_resolve_workspace.

required
object

Tool-specific input payload (see capabilities for per-tool schema).

reason
string <= 500 characters

Human-readable reason stored in audit logs.

requestId
string <= 120 characters

Optional caller idempotency or trace identifier.

Responses

Request samples

Content type
application/json
{
  • "organizationId": "string",
  • "input": { },
  • "reason": "string",
  • "requestId": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    },
  • "error": "string",
  • "meta": {
    }
}