Skip to main content
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:
IdentifierPath styleWhen 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.
MethodPathPurposeAction
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>/archiveArchive 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>/archiveArchive a contact by A2V2 contact ID.update

​
List query parameters

The list endpoint (GET /contacts/chatbots/<AGENT_ID>) supports:
ParameterValuesNotes
pageinteger ≥ 1Page number.
limitinteger 1–100Items per page.
searchstringText search across contact fields.
statusactive, inactive, blockedFilter by contact status.
tagstringFilter by a single tag.
sortBycreatedAt, updatedAt, firstName, lastName, primaryEmailField to sort by.
sortOrderasc, descSort 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).
MethodPathPurposeAction
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-urlGet 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.
MethodPathPurpose
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).
MethodPathPurposeAction
GET/document-extraction/schema-examplesGet example extraction schemas (for example: medical, invoice, resume) to model your own on.read
POST/document-extraction/extractExtract structured data from an uploaded document.create

​
Extract request

Send as multipart/form-data:
FieldRequiredDescription
documentYesThe file to process (PDF, DOCX, TXT, or images).
schemaYesA JSON object defining the fields to extract.
customInstructionsNoExtra natural-language guidance for the extraction.
saveToS3NoWhether 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.