API Endpoints

This is the endpoint reference for the Open API. Every path below is relative to your API base and the /v1/open prefix, and every request needs an API key with the right permission scope.

https://api.a2v2.ai/v1/open

https://api.a2v2.ai is the production API base URL (see API Overview). <AGENT_ID> is the ID of the agent your key is scoped to. Where a request or response body isn’t fully documented below, treat it as to be confirmed — call the matching schema endpoint (for contacts and forms) to see the exact fields your agent expects.

How endpoints are addressed

Most endpoints are scoped to an agent and a contact in the URL path. Contacts can be addressed two ways:

Identifier	Path style	When to use
External Reference ID	`/<externalReferenceId>/chatbots/<AGENT_ID>`	Your own system’s ID for the contact. Recommended — keep your ID scheme. Must be unique per agent.
A2V2 contact ID	`/mantisid/<contactId>/chatbots/<AGENT_ID>`	The system-generated A2V2 contact ID (a 24-character identifier).

Contacts

Create, read, update, and archive CRM contacts. Requires the Contact Access scope (contacts) with the matching action.

Method	Path	Purpose	Action
`GET`	`/contacts/schema/chatbots/<AGENT_ID>`	Get the contact schema for the agent — the fields your agent accepts. Call this first to see what to send.	read
`POST`	`/contacts/chatbots/<AGENT_ID>`	Create a contact.	create
`GET`	`/contacts/chatbots/<AGENT_ID>`	List contacts, with filtering and pagination.	read
`GET`	`/contacts/<externalReferenceId>/chatbots/<AGENT_ID>`	Get a contact by your external reference ID.	read
`PUT`	`/contacts/<externalReferenceId>/chatbots/<AGENT_ID>`	Update a contact by external reference ID.	update
`PATCH`	`/contacts/<externalReferenceId>/chatbots/<AGENT_ID>/archive`	Archive a contact by external reference ID.	update
`GET`	`/contacts/mantisid/<contactId>/chatbots/<AGENT_ID>`	Get a contact by A2V2 contact ID.	read
`PUT`	`/contacts/mantisid/<contactId>/chatbots/<AGENT_ID>`	Update a contact by A2V2 contact ID.	update
`PATCH`	`/contacts/mantisid/<contactId>/chatbots/<AGENT_ID>/archive`	Archive a contact by A2V2 contact ID.	update

List query parameters

The list endpoint (GET /contacts/chatbots/<AGENT_ID>) supports:

Parameter	Values	Notes
`page`	integer ≥ 1	Page number.
`limit`	integer 1–100	Items per page.
`search`	string	Text search across contact fields.
`status`	`active`, `inactive`, `blocked`	Filter by contact status.
`tag`	string	Filter by a single tag.
`sortBy`	`createdAt`, `updatedAt`, `firstName`, `lastName`, `primaryEmail`	Field to sort by.
`sortOrder`	`asc`, `desc`	Sort direction.

Contact fields

A contact accepts standard fields plus a free-form customFields object for your own data. The standard fields include:

firstName, lastName, middleName, salutation, dob, gender,
primaryEmail, primaryPhone, primaryPhoneCode, fullAddress,
externalReferenceId, tags, status, source, lastContactedAt, customFields

primaryEmail is required when creating a contact via the API.

{
  "externalReferenceId": "USER_12345",
  "primaryEmail": "john.doe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "tags": ["VIP"],
  "customFields": {
    "membership_level": "Gold",
    "acquisition_source": "Referral"
  }
}

The exact required/optional status and validation rules per field can vary by how the agent’s CRM schema is configured. Call GET /contacts/schema/chatbots/<AGENT_ID> to get the authoritative field list for your agent. Field-level types and rules beyond primaryEmail being required are to be confirmed against that schema.

Example — create a contact

curl -X POST "https://api.a2v2.ai/v1/open/contacts/chatbots/<AGENT_ID>" \
  -H "X-API-Key: your-api-key" \
  -H "X-API-Secret: your-api-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "externalReferenceId": "USER_12345",
    "primaryEmail": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe"
  }'

Contact files

Upload and manage files attached to a contact. Requires the Contact Access scope (contacts).

Method	Path	Purpose	Action
`POST`	`/files/chatbots/<AGENT_ID>/<contactId>`	Upload a file for a contact (`multipart/form-data`, field name `file`).	create
`GET`	`/files/chatbots/<AGENT_ID>/<contactId>`	List a contact’s files (supports `page`, `limit`, `sortBy`, `sortOrder`).	read
`GET`	`/files/chatbots/<AGENT_ID>/<contactId>/files/<fileId>`	Get a single file’s metadata.	read
`GET`	`/files/chatbots/<AGENT_ID>/<contactId>/files/<fileId>/signed-url`	Get a temporary download URL for the file.	read
`DELETE`	`/files/chatbots/<AGENT_ID>/<contactId>/files/<fileId>`	Delete a file.	delete

For file lists, sortBy accepts createdAt, fileName, or fileSize; limit is 1–100. The delete request optionally accepts a reason field in the body.

The <contactId> here is the A2V2 contact ID. Allowed file types and the maximum file size are enforced by the platform; the exact limits are to be confirmed.

Forms

Submit and read CRM form submissions on behalf of a contact.

Forms endpoints require a forms permission on the API key. The dashboard currently exposes Contact Access and Document Extraction Access scopes — the availability of a dedicated forms scope is to be confirmed. Verify your key can call these endpoints before building on them, or contact support.

Method	Path	Purpose
`POST`	`/forms/submit/<templateId>/contacts/<externalReferenceId>`	Submit a form for a contact. Body: `formData` (required), optional `submissionNotes`, `clientId`.
`POST`	`/forms/batch/contacts/<externalReferenceId>/chatbots/<AGENT_ID>`	Submit multiple forms at once (1–10 submissions).
`GET`	`/forms/contacts/<externalReferenceId>/chatbots/<AGENT_ID>`	List a contact’s submissions. Filters: `templateId`, `status`, `includeSuperseded`, `page`, `limit`.
`GET`	`/forms/submissions/<submissionId>/chatbots/<AGENT_ID>`	Get a single submission.
`PUT`	`/forms/submissions/<submissionId>/chatbots/<AGENT_ID>`	Update a submission (`formData`, `submissionNotes`, `status`, `reviewNotes`).
`GET`	`/forms/contacts/<externalReferenceId>/templates/<templateId>/latest/chatbots/<AGENT_ID>`	Get the latest submission for a contact + template.
`GET`	`/forms/templates/chatbots/<AGENT_ID>`	List the form templates available for the agent.
`GET`	`/forms/templates/<templateId>/schema/chatbots/<AGENT_ID>`	Get a template’s field definitions (recommended — use this to build `formData`).
`GET`	`/forms/templates/<templateId>/structure/chatbots/<AGENT_ID>`	Get a template’s structure with example values (legacy).

The submission status filter accepts draft, submitted, under_review, approved, rejected, or archived. When submitting, formData is a JSON object keyed by the template’s fields — call the template schema endpoint to see the expected keys.

Document extraction

Extract structured data from an uploaded document using AI. Requires the Document Extraction Access scope (document-extraction).

Method	Path	Purpose	Action
`GET`	`/document-extraction/schema-examples`	Get example extraction schemas (for example: medical, invoice, resume) to model your own on.	read
`POST`	`/document-extraction/extract`	Extract structured data from an uploaded document.	create

Extract request

Send as multipart/form-data:

Field	Required	Description
`document`	Yes	The file to process (PDF, DOCX, TXT, or images).
`schema`	Yes	A JSON object defining the fields to extract.
`customInstructions`	No	Extra natural-language guidance for the extraction.
`saveToS3`	No	Whether to retain the document in storage (default `false`).

A schema field looks like:

{
  "fieldName": {
    "type": "string",
    "description": "What this field represents",
    "required": true
  }
}

Supported field type values include string, number, date, boolean, email, array, and object.

Extract response

{
  "success": true,
  "data": { },
  "metadata": {
    "confidence": 0.85,
    "fieldConfidences": { },
    "validation": { },
    "processingTime": 2500,
    "document": { }
  }
}

data holds the extracted fields keyed by your schema; metadata.confidence is an overall confidence score, with per-field scores in fieldConfidences.

Document extraction consumes credits like other AI operations. See Credits explained.

Managing keys

API keys themselves are created and managed in the dashboard, not with an API key — see Authentication and API keys in Settings. Usage statistics for your keys are also available in the dashboard.

Authentication

Create a key and grant the right scopes.

API Overview

Base URL, response format, pagination, and rate limits.

CRM Contacts

How contacts work in the dashboard.

CRM Forms

Build the form templates these endpoints submit to.

Get Started

Build Your Agent

Medical Agents

Knowledge Base

Test Your Agent

Customize & Embed

Conversations

CRM

Billing & Plans

Team & Settings

Analytics & Usage

Integrations

Tasks

Widget & Deployment

Developer / API

Concepts

Help

How endpoints are addressed

Contacts

List query parameters

Contact fields

Example — create a contact

Contact files

Forms

Document extraction

Extract request

Extract response

Managing keys

Authentication

API Overview

CRM Contacts

CRM Forms

​How endpoints are addressed

​Contacts

​List query parameters

​Contact fields

​Example — create a contact

​Contact files

​Forms

​Document extraction

​Extract request

​Extract response

​Managing keys

​Related

Authentication

API Overview

CRM Contacts

CRM Forms

How endpoints are addressed

Contacts

List query parameters

Contact fields

Example — create a contact

Contact files

Forms

Document extraction

Extract request

Extract response

Managing keys

Related