> ## Documentation Index
> Fetch the complete documentation index at: https://docs.a2v2.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# API Endpoints
> Reference for every A2V2.ai Open API endpoint — contacts, contact files, forms, and document extraction.
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](/api/authentication#permission-scopes).
```text theme={null}
https://api.a2v2.ai/v1/open
```
`https://api.a2v2.ai` is the production API base URL
(see [API Overview](/api/overview#base-url)). `` 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** | `//chatbots/` | Your own system's ID for the contact. Recommended — keep your ID scheme. Must be unique per agent. |
| **A2V2 contact ID** | `/mantisid//chatbots/` | 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/` | Get the contact schema for the agent — the fields your agent accepts. Call this first to see what to send. | read |
| `POST` | `/contacts/chatbots/` | Create a contact. | create |
| `GET` | `/contacts/chatbots/` | List contacts, with filtering and pagination. | read |
| `GET` | `/contacts//chatbots/` | Get a contact by your external reference ID. | read |
| `PUT` | `/contacts//chatbots/` | Update a contact by external reference ID. | update |
| `PATCH` | `/contacts//chatbots//archive` | Archive a contact by external reference ID. | update |
| `GET` | `/contacts/mantisid//chatbots/` | Get a contact by A2V2 contact ID. | read |
| `PUT` | `/contacts/mantisid//chatbots/` | Update a contact by A2V2 contact ID. | update |
| `PATCH` | `/contacts/mantisid//chatbots//archive` | Archive a contact by A2V2 contact ID. | update |
### List query parameters
The list endpoint (`GET /contacts/chatbots/`) 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:
```text theme={null}
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.
```json theme={null}
{
"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/`
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
```bash theme={null}
curl -X POST "https://api.a2v2.ai/v1/open/contacts/chatbots/" \
-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//` | Upload a file for a contact (`multipart/form-data`, field name `file`). | create |
| `GET` | `/files/chatbots//` | List a contact's files (supports `page`, `limit`, `sortBy`, `sortOrder`). | read |
| `GET` | `/files/chatbots///files/` | Get a single file's metadata. | read |
| `GET` | `/files/chatbots///files//signed-url` | Get a temporary download URL for the file. | read |
| `DELETE` | `/files/chatbots///files/` | 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 `` 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](mailto:support@a2v2.ai).
| Method | Path | Purpose |
| ------ | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `POST` | `/forms/submit//contacts/` | Submit a form for a contact. Body: `formData` (required), optional `submissionNotes`, `clientId`. |
| `POST` | `/forms/batch/contacts//chatbots/` | Submit multiple forms at once (1–10 submissions). |
| `GET` | `/forms/contacts//chatbots/` | List a contact's submissions. Filters: `templateId`, `status`, `includeSuperseded`, `page`, `limit`. |
| `GET` | `/forms/submissions//chatbots/` | Get a single submission. |
| `PUT` | `/forms/submissions//chatbots/` | Update a submission (`formData`, `submissionNotes`, `status`, `reviewNotes`). |
| `GET` | `/forms/contacts//templates//latest/chatbots/` | Get the latest submission for a contact + template. |
| `GET` | `/forms/templates/chatbots/` | List the form templates available for the agent. |
| `GET` | `/forms/templates//schema/chatbots/` | Get a template's field definitions (recommended — use this to build `formData`). |
| `GET` | `/forms/templates//structure/chatbots/` | 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:
```json theme={null}
{
"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
```json theme={null}
{
"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](/billing/credits-explained).
***
## Managing keys
API keys themselves are created and managed in the dashboard, not with an API key —
see [Authentication](/api/authentication) and
[API keys in Settings](/settings/api-keys). Usage statistics for your keys are also
available in the dashboard.
## Related
Create a key and grant the right scopes.
Base URL, response format, pagination, and rate limits.
How contacts work in the dashboard.
Build the form templates these endpoints submit to.